Algorithms¶

Cryptographic primitives such as the SHA256 digest, or AES encryption are referred to in OpenSSL as "algorithms". Each algorithm may have multiple implementations available for use. For example the RSA algorithm is available as a "default" implementation suitable for general use, and a "fips" implementation which has been validated to FIPS standards for situations where that is important. It is also possible that a third party could add additional implementations such as in a hardware security module (HSM).

Operations¶

Different algorithms can be grouped together by their purpose. For example there are algorithms for encryption, and different algorithms for digesting data. These different groups are known as "operations" in OpenSSL. Each operation has a different set of functions associated with it. For example to perform an encryption operation using AES (or any other encryption algorithm) you would use the encryption functions detailed on the EVP_EncryptInit(3) page. Or to perform a digest operation using SHA256 then you would use the digesting functions on the EVP_DigestInit(3) page.

Providers¶

A provider in OpenSSL is a component that collects together algorithm implementations. In order to use an algorithm you must have at least one provider loaded that contains an implementation of it. OpenSSL comes with a number of providers and they may also be obtained from third parties. If you don't load a provider explicitly (either in program code or via config) then the OpenSSL built-in "default" provider will be automatically loaded.

Library contexts¶

A library context can be thought of as a "scope" within which configuration options take effect. When a provider is loaded, it is only loaded within the scope of a given library context. In this way it is possible for different components of a complex application to each use a different library context and have different providers loaded with different configuration settings.

If an application does not explicitly create a library context then the "default" library context will be used.

Library contexts are represented by the OSSL_LIB_CTX type. Many OpenSSL API functions take a library context as a parameter. Applications can always pass NULL for this parameter to just use the default library context.

The default library context is automatically created the first time it is needed. This will automatically load any available configuration file and will initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to 1.1.0) no explicit initialisation steps need to be taken.

Similarly when the application exits the default library context is automatically destroyed. No explicit de-initialisation steps need to be taken.

See OSSL_LIB_CTX(3) for more information about library contexts. See also "ALGORITHM FETCHING".

Multi-threaded applications¶

As long as OpenSSL has been built with support for threads (the default case on most platforms) then most OpenSSL functions are thread-safe in the sense that it is safe to call the same function from multiple threads at the same time. However most OpenSSL data structures are not thread-safe. For example the BIO_write(3) and BIO_read(3) functions are thread safe. However it would not be thread safe to call BIO_write() from one thread while calling BIO_read() in another where both functions are passed the same BIO object since both of them may attempt to make changes to the same BIO object.

There are exceptions to these rules. A small number of functions are not thread safe at all. Where this is the case this restriction should be noted in the documentation for the function. Similarly some data structures may be partially or fully thread safe. For example it is safe to use an OSSL_LIB_CTX in multiple threads.

See openssl-threads(7) for a more detailed discussion on OpenSSL threading support.

Property query strings¶

When fetching an algorithm it is possible to specify a property query string to guide the selection process. For example a property query string of "provider=default" could be used to force the selection to only consider algorithm implementations in the default provider.

Property query strings can be specified explicitly as an argument to a function. It is also possible to specify a default property query string for the whole library context using the EVP_set_default_properties(3) or EVP_default_properties_enable_fips(3) functions. Where both default properties and function specific properties are specified then they are combined. Function specific properties will override default properties where there is a conflict.

See property(7) for more information about properties.

Explicit fetching¶

Users of the OpenSSL libraries never query a provider directly for an algorithm implementation. Instead, the diverse OpenSSL APIs often have explicit fetching functions that do the work, and they return an appropriate algorithm object back to the user. These functions usually have the name "APINAME_fetch", where "APINAME" is the name of the operation. For example EVP_MD_fetch(3) can be used to explicitly fetch a digest algorithm implementation. The user is responsible for freeing the object returned from the "APINAME_fetch" function using "APINAME_free" when it is no longer needed.

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

The library context

See OSSL_LIB_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. In case no provider has been loaded in this library context then the default provider will be loaded as a fallback (see OSSL_PROVIDER-default(7)).

An identifier

For all currently implemented fetching functions this is the algorithm name.

A property query string

The property query string used to guide selection of the algorithm implementation.

The algorithm implementation that is fetched can then be used with other diverse functions that use them. For example the EVP_DigestInit_ex(3) function takes as a parameter an EVP_MD object which may have been returned from an earlier call to EVP_MD_fetch(3).

Implicit fetching¶

OpenSSL has a number of functions that return an algorithm object with no associated implementation, such as EVP_sha256(3), EVP_aes_128_cbc(3), EVP_get_cipherbyname(3) or EVP_get_digestbyname(3). These are present for compatibility with OpenSSL before version 3.0 where explicit fetching was not available.

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.

In some cases 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 context in which it is being used.

Functions that revolve around EVP_PKEY_CTX and EVP_PKEY(3), such as EVP_DigestSignInit(3) and friends, all fetch the implementations implicitly. Because these functions involve both an operation type (such as EVP_SIGNATURE(3)) and an EVP_KEYMGMT(3) for the EVP_PKEY(3), they try the following:

1.

Fetch the operation type implementation from any provider given a library context and property string stored in the EVP_PKEY_CTX.

If the provider of the operation type implementation is different from the provider of the EVP_PKEY(3)'s EVP_KEYMGMT(3) implementation, try to fetch a EVP_KEYMGMT(3) implementation in the same provider as the operation type implementation and export the EVP_PKEY(3) to it (effectively making a temporary copy of the original key).

If anything in this step fails, the next step is used as a fallback.

2.

As a fallback, try to fetch the operation type implementation from the same provider as the original EVP_PKEY(3)'s EVP_KEYMGMT(3), still using the property string from the EVP_PKEY_CTX.

Performance¶

If you perform the same operation many times then it is recommended to use "Explicit fetching" to prefetch an algorithm once initially, and then pass this created object to any operations that are currently using "Implicit fetching". See an example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS".

Prior to OpenSSL 3.0, constant method tables (such as EVP_sha256()) were used directly to access methods. If you pass one of these convenience functions to an operation the fixed methods are ignored, and only the name is used to internally fetch methods from a provider.

If the prefetched object is not passed to operations, then any implicit fetch will use the internally cached prefetched object, but it will still be slower than passing the prefetched object directly.

Fetching via a provider offers more flexibility, but it is slower than the old method, since it must search for the algorithm in all loaded providers, and then populate the method table using provider supplied methods. Internally OpenSSL caches similar algorithms on the first fetch (so loading a digest caches all digests).

The following methods can be used for prefetching:

EVP_MD_fetch(3)

EVP_CIPHER_fetch(3)

EVP_KDF_fetch(3)

EVP_MAC_fetch(3)

EVP_KEM_fetch(3)

OSSL_ENCODER_fetch(3)

OSSL_DECODER_fetch(3)

EVP_RAND_fetch(3)

The following methods are used internally when performing operations:

EVP_KEYMGMT_fetch(3)

EVP_KEYEXCH_fetch(3)

EVP_SIGNATURE_fetch(3)

OSSL_STORE_LOADER_fetch(3)

See OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7) and OSSL_PROVIDER-legacy(7) for a list of algorithm names that can be fetched.

Default provider¶

The default provider is built in as part of the libcrypto library and contains all of the most commonly used algorithm implementations. Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property query string "provider=default" can be used as a search criterion for these implementations. The default provider includes all of the functionality in the base provider below.

If you don't load any providers at all then the "default" provider will be automatically loaded. If you explicitly load any provider then the "default" provider would also need to be explicitly loaded if it is required.

See OSSL_PROVIDER-default(7).

Base provider¶

The base provider is built in as part of the libcrypto library and contains algorithm implementations for encoding and decoding for OpenSSL keys. Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property query string "provider=base" can be used as a search criterion for these implementations. Some encoding and decoding algorithm implementations are not FIPS algorithm implementations in themselves but support algorithms from the FIPS provider and are allowed for use in "FIPS mode". The property query string "fips=yes" can be used to select such algorithms.

See OSSL_PROVIDER-base(7).

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)). It contains algorithm implementations that have been validated according to the FIPS 140-2 standard. Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property query string "provider=fips" can be used as a search criterion for these implementations. All approved algorithm implementations in the FIPS provider can also be selected with the property "fips=yes". The FIPS provider may also contain non-approved algorithm implementations and these can be selected with the property "fips=no".

See OSSL_PROVIDER-FIPS(7) and fips_module(7).

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)). It contains algorithm implementations that are considered insecure, or are no longer in common use such as MD2 or RC4. 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.

See OSSL_PROVIDER-legacy(7).

Null provider¶

The null provider is built in as part of the libcrypto library. It contains no algorithms in it at all. When fetching algorithms the default provider will be automatically loaded if no other provider has been explicitly loaded. To prevent that from happening you can explicitly load the null provider.

See OSSL_PROVIDER-null(7).