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 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 "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 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 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 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 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 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 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 The 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 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_blake2b512(3) or EVP_DigestInit_ex(3) or 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) 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 Legacy provider

The legacy provider is a dynamically loadable module, and must therefore be loaded explicitly, either in code or through OpenSSL configuration (see 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);

HISTORY

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

COPYRIGHT

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.