PROVIDER(7)

NAME
provider - OpenSSL operation implementation providers

SYNOPSIS
#include <openssl/provider.h>

DESCRIPTION

  General
A provider, in OpenSSL terms, is a unit of code that provides one or more implementations for various operations for diverse algorithms that one might want to perform.

An operation is something one wants to do, such as encryption and decryption, key derivation, MAC calculation, signing and verification, etc.

An algorithm is a named method to perform an operation. Very often, the algorithms revolve around cryptographic operations, but may also revolve around other types of operation, such as managing certain types of objects.

  Provider
NOTE: This section is mostly interesting for provider authors.

A provider offers an initialization function, as a set of base functions in the form of an OSSL_DISPATCH array, and by extension, a set of OSSL_ALGORITHMs (see openssl-core.h(7)). It may be a dynamically loadable module, or may be built-in, in OpenSSL libraries or in the application. If it's a dynamically loadable module, the initialization function must be named "OSSL_provider_init" and must be exported. If it's built-in, the initialization function may have any name.

The initialization function must have the following signature:

 int NAME(const OSSL_PROVIDER *provider,
          const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
          void **provctx);

provider is the OpenSSL library object for the provider, and works as a handle for everything the OpenSSL libraries need to know about the provider. For the provider itself, it may hold some interesting information, and is also passed to some of the functions given in the dispatch array in.

in is a dispatch array of base functions offered by the OpenSSL libraries, and the available functions are further described in provider-base(7).

*out must be assigned a dispatch array of base functions that the provider offers to the OpenSSL libraries. The functions that may be offered are further described in provider-base(7), and they are the central means of communication between the OpenSSL libraries and the provider.

*provctx should be assigned a provider specific context to allow the provider multiple simultaneous uses. This pointer will be passed to various operation functions offered by the provider.

One of the functions the provider offers to the OpenSSL libraries is the central mechanism for the OpenSSL libraries to get access to operation implementations for diverse algorithms. Its referred to with the number OSSL_FUNC_PROVIDER_QUERY_OPERATION and has the following signature:

 const OSSL_ALGORITHM *provider_query_operation(void *provctx,
                                                int operation_id,
                                                const int *no_store);

provctx is the provider specific context that was passed back by the initialization function.

operation_id is an operation identity (see "Operations" below).

no_store is a flag back to the OpenSSL libraries which, when nonzero, signifies that the OpenSSL libraries will not store a reference to the returned data in their internal store of implementations.

The returned OSSL_ALGORITHM is the foundation of any OpenSSL library API that uses providers for their implementation, most commonly in the fetching type of functions (see "Fetching algorithms" below).

  Operations
NOTE: This section is mostly interesting for provider authors.

Operations are referred to with numbers, via macros with names starting with "OSSL_OP_".

With each operation comes a set of defined function types that a provider may or may not offer, depending on its needs.

Currently available operations are:

Digests
    In the OpenSSL libraries, the corresponding method object is EVP_MD. The number for this operation is OSSL_OP_DIGEST. The functions the provider can offer are described in provider-digest(7)

Symmetric ciphers
    In the OpenSSL libraries, the corresponding method object is EVP_CIPHER. The number for this operation is OSSL_OP_CIPHER. The functions the provider can offer are described in provider-cipher(7)

Message Authentication Code (MAC)
    In the OpenSSL libraries, the corresponding method object is EVP_MAC. The number for this operation is OSSL_OP_MAC. The functions the provider can offer are described in provider-mac(7)

Key Derivation Function (KDF)
    In the OpenSSL libraries, the corresponding method object is EVP_KDF. The number for this operation is OSSL_OP_KDF. The functions the provider can offer are described in provider-kdf(7)

Key Exchange
    In the OpenSSL libraries, the corresponding method object is EVP_KEYEXCH. The number for this operation is OSSL_OP_KEYEXCH. The functions the provider can offer are described in provider-keyexch(7)

Serialization
    In the OpenSSL libraries, the corresponding method object is OSSL_SERIALIZER. The number for this operation is OSSL_OP_SERIALIZER. The functions the provider can offer are described in provider-serializer(7)

  Fetching algorithms
Explicit fetch

NOTE: This section is mostly interesting to OpenSSL users.

Users of the OpenSSL libraries never query the provider directly for its diverse implementations and dispatch tables. Instead, the diverse OpenSSL APIs often have fetching functions that do the work, and they return an appropriate method object back to the user. These functions usually have the name "APINAME_fetch", where "APINAME" is the name of the API, for example EVP_MD_fetch(3).

These fetching functions follow a fairly common pattern, where three arguments are passed:

The library context
    See OPENSSL_CTX(3) for a more detailed description. This may be NULL to signify the default (global) library context, or a context created by the user. Only providers loaded in this library context (see OSSL_PROVIDER_load(3)) will be considered by the fetching function.

An identifier
    This is most commonly an algorithm name (this is the case for all EVP methods), but may also be called something else.

A property query string
    See property(7) for a more detailed description. This is used to select more exactly which providers will get to offer an implementation.

The method object that is fetched can then be used with diverse other functions that use them, for example EVP_DigestInit_ex(3).

Implicit fetch

NOTE: This section is mostly interesting to OpenSSL users.

OpenSSL has a number of functions that return a method object with no associated implementation, such as EVP_sha256(3), EVP_blake2b512(3) or EVP_aes_128_cbc(3), which are present for compatibility with OpenSSL before version 3.0.

When they are used with functions like EVP_DigestInit_ex(3) or EVP_CipherInit_ex(3), the actual implementation to be used is fetched implicitly using default search criteria.

Implicit fetching can also occur when a NULL algorithm parameter is supplied. In this case an algorithm implementation is implicitly fetched using default search criteria and an algorithm name that is consistent with the type of EVP_PKEY being used.

Algorithm naming

Algorithm names are case insensitive. Any particular algorithm can have multiple aliases associated with it. The canonical OpenSSL naming scheme follows this format:

ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]

VERSION is only present if there are multiple versions of an algorithm (e.g. MD2, MD4, MD5). It may be omitted if there is only one version.

SUBNAME may be present where multiple algorithms are combined together, e.g. MD5-SHA1.

SIZE is only present if multiple versions of an algorithm exist with different sizes (e.g. AES-128-CBC, AES-256-CBC)

MODE is only present where applicable.

Other aliases may exist for example where standards bodies or common practice use alternative names or names that OpenSSL has used historically.

OPENSSL PROVIDERS
OpenSSL comes with a set of providers.

The algorithms available in each of these providers may vary due to build time configuration options. The openssl-list(1) command can be used to list the currently available algorithms.

The names of the algorithms shown from openssl-list(1) can be used as an algorithm identifier to the appropriate fetching function.

  Default provider
The default provider is built in as part of the libcrypto library. Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property "provider=default" can be used as a search criterion for these implementations. Some non-cryptographic algorithms (such as serializers for loading keys and parameters from files) are not FIPS algorithm implementations in themselves but support algorithms from the FIPS provider and are allowed for use in "FIPS mode". The property "fips=yes" can be used to select such algorithms.

  FIPS provider
The FIPS provider is a dynamically loadable module, and must therefore be loaded explicitly, either in code or through OpenSSL configuration (see config(5)). Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property "provider=fips" can be used as a search criterion for these implementations. All algorithm implementations in the FIPS provider can also be selected with the property "fips=yes".

  Legacy provider
The legacy provider is a dynamically loadable module, and must therefore be loaded explicitly, either in code or through OpenSSL configuration (see config(5)). Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property "provider=legacy" can be used as a search criterion for these implementations.

EXAMPLES

  Fetching
Fetch any available implementation of SHA2-256 in the default context:

 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
 ...
 EVP_MD_meth_free(md);

Fetch any available implementation of AES-128-CBC in the default context:

 EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
 ...
 EVP_CIPHER_meth_free(cipher);

Fetch an implementation of SHA2-256 from the default provider in the default context:

 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
 ...
 EVP_MD_meth_free(md);

Fetch an implementation of SHA2-256 that is not from the default provider in the default context:

 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
 ...
 EVP_MD_meth_free(md);

Fetch an implementation of SHA2-256 from the default provider in the specified context:

 EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default");
 ...
 EVP_MD_meth_free(md);

Load the legacy provider into the default context and then fetch an implementation of WHIRLPOOL from it:

 /* This only needs to be done once - usually at application start up */
 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");

 EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
 ...
 EVP_MD_meth_free(md);

Note that in the above example the property string "provider=legacy" is optional since, assuming no other providers have been loaded, the only implementation of the "whirlpool" algorithm is in the "legacy" provider. Also note that the default provider should be explicitly loaded if it is required in addition to other providers:

 /* This only needs to be done once - usually at application start up */
 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");

 EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
 EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
 ...
 EVP_MD_meth_free(md_whirlpool);
 EVP_MD_meth_free(md_sha256);

SEE ALSO
EVP_DigestInit_ex(3), EVP_EncryptInit_ex(3), OPENSSL_CTX(3), EVP_set_default_properties(3), EVP_MD_fetch(3), EVP_CIPHER_fetch(3), EVP_KEYMGMT_fetch(3), openssl-core.h(7), provider-base(7), provider-digest(7), provider-cipher(7), provider-keyexch(7)

HISTORY
The concept of providers and everything surrounding them was introduced in OpenSSL 3.0.

COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.