diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man7/provider.pod | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod new file mode 100644 index 0000000000..d9010dc9f5 --- /dev/null +++ b/doc/man7/provider.pod @@ -0,0 +1,401 @@ +=pod + +=head1 NAME + +provider - OpenSSL operation implementation providers + +=head1 SYNOPSIS + +=for comment generic + +#include <openssl/provider.h> + +=head1 DESCRIPTION + +=head2 General + +A I<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 I<operation> is something one wants to do, such as encryption and +decryption, key derivation, MAC calculation, signing and verification, +etc. + +An I<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. + +=head2 Provider + +I<NOTE: This section is mostly interesting for provider authors.> + +A I<provider> offers an initialization function, as a set of base +functions in the form of an B<OSSL_DISPATCH> array, and by extension, +a set of B<OSSL_ALGORITHM>s (see L<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 C<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); + +I<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 I<in>. + +I<in> is a dispatch array of base functions offered by the OpenSSL +libraries, and the available functions are further described in +L<provider-base(7)>. + +I<*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 +L<provider-base(7)>, and they are the central means of communication +between the OpenSSL libraries and the provider. + +I<*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 B<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); + +I<provctx> is the provider specific context that was passed back by +the initialization function. + +I<operation_id> is an operation identity (see L</Operations> below). + +I<no_store> is a flag back to the OpenSSL libraries which, when +non-zero, signifies that the OpenSSL libraries will not store a +reference to the returned data in their internal store of +implementations. + +The returned B<OSSL_ALGORITHM> is the foundation of any OpenSSL +library API that uses providers for their implementation, most +commonly in the I<fetching> type of functions +(see L</Fetching algorithms> below). + +=head2 Operations + +I<NOTE: This section is mostly interesting for provider authors.> + +Operations are referred to with numbers, via macros with names +starting with C<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: + +=over 4 + +=item Digests + +In the OpenSSL libraries, the corresponding method object is +B<EVP_MD>. +The number for this operation is B<OSSL_OP_DIGEST>. +The functions the provider can offer are described in +L<provider-digest(7)> + +=item Symmetric ciphers + +In the OpenSSL libraries, the corresponding method object is +B<EVP_CIPHER>. +The number for this operation is B<OSSL_OP_CIPHER>. +The functions the provider can offer are described in +L<provider-cipher(7)> + +=begin comment NOT AVAILABLE YET + +=item Message Authentication Code (MAC) + +In the OpenSSL libraries, the corresponding method object is +B<EVP_MAC>. +The number for this operation is B<OSSL_OP_MAC>. +The functions the provider can offer are described in +L<provider-mac(7)> + +=end comment + +=begin comment NOT AVAILABLE YET + +=item Key Derivation Function (KDF) + +In the OpenSSL libraries, the corresponding method object is +B<EVP_KDF>. +The number for this operation is B<OSSL_OP_KDF>. +The functions the provider can offer are described in +L<provider-kdf(7)> + +=end comment + +=item Key Exchange + +In the OpenSSL libraries, the corresponding method object is +B<EVP_KEYEXCh>. +The number for this operation is B<OSSL_OP_KEYEXCH>. +The functions the provider can offer are described in +L<provider-keyexch(7)> + +=back + +=head2 Fetching algorithms + +=head3 Explicit fetch + +I<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 C<APINAME_fetch>, where +C<APINAME> is the name of the API, for example L<EVP_MD_fetch(3)>. + +These fetching functions follow a fairly common pattern, where three +arguments are passed: + +=over 4 + +=item The library context + +See L<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 +L<OSSL_PROVIDER_load(3)>) will be considered by the fetching +function. + +=item An identifier + +This is most commonly an algorithm name (this is the case for all EVP +methods), but may also be called something else. + +=for comment For example, an OSSL_STORE implementation would use the +URI scheme as an identifier. + +=item A property query string + +See L<property(7)> for a more detailed description. +This is used to select more exactly which providers will get to offer +an implementation. + +=back + +The method object that is fetched can then be used with diverse other +functions that use them, for example L<EVP_DigestInit_ex(3)>. + +=head2 Implicit fetch + +I<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 L<EVP_sha256(3)>, +L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>, which are present for +compatibility with OpenSSL before version 3.0. + +When they are used with functions like L<EVP_DigestInit_ex(3)> or +L<EVP_CipherInit_ex(3)>, the actual implementation to be used is +fetched implicitly using default search criteria. + +Implicit fetching can also occur with functions such as +L<EVP_PKEY_CTX_derive_init_ex(3)> where 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. + +=head1 OPENSSL PROVIDERS + +OpenSSL comes with a set of providers. +All the algorithm names mentioned can be used as an algorithm +identifier to the appropriate fetching function. + +=head2 Default provider + +The default provider is built in as part of the F<libcrypto> library. +Should it be needed (if other providers are loaded and offer +implementations of the same algorithms), the property "default=yes" +can be used as a search criterion for these implementations. + +It currently offers the following named algorithms: + +=over 4 + +=item Digests + +SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256, +SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3, +BLAKE2b512, BLAKE2s256, KMAC128, KMAC256, MD5, MD5-SHA1 + +=item Symmetric ciphers + +AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC, +AES-128-CBC, AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB, +AES-192-CFB, AES-128-CFB, AES-256-CFB1, AES-192-CFB1, AES-128-CFB1, +AES-256-CFB8, AES-192-CFB8, AES-128-CFB8, AES-256-CTR, AES-192-CTR, +AES-128-CTR, id-aes256-GCM, id-aes192-GCM, id-aes128-GCM + +=item Key Exchange + +dhKeyAgreement + +=back + +=head2 FIPS provider + +The FIPS provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see L<config(5)>). +Should it be needed (if other providers are loaded and offer +implementations of the same algorithms), the property "fips=yes" can +be used as a search criterion for these implementations. + +It currently offers the following FIPS approved named algorithms: + +=over 4 + +=item Digests + +SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256, +SHA3-224, SHA3-256, SHA3-384, SHA3-512, KMAC128, KMAC256 + +=item Symmetric ciphers + +AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC, +AES-128-CBC, AES-256-CTR, AES-192-CTR, AES-128-CTR + +=back + +=head2 Legacy provider + +The legacy provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see L<config(5)>). +Should it be needed (if other providers are loaded and offer +implementations of the same algorithms), the property "legacy=yes" can be +used as a search criterion for these implementations. + +It currently offers the following named algorithms: + +=over 4 + +=item Digest algorithms: + +RIPEMD160, MD2, MD4, MDC2, whirlpool. + +=back + +=head1 EXAMPLES + +=head2 Fetching + +Fetch any available implementation of SHA256 in the default context: + + EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", 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 SHA256 from the default provider in the default +context: + + EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes"); + ... + EVP_MD_meth_free(md); + +Fetch an implementation of SHA256 that is not from the default provider in the +default context: + + EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no"); + ... + EVP_MD_meth_free(md); + +Fetch an implementation of SHA256 from the default provider in the specified +context: + + EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes"); + ... + 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", "legacy=yes"); + ... + EVP_MD_meth_free(md); + +Note that in the above example the property string "legacy=yes" 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, "SHA256", NULL); + ... + EVP_MD_meth_free(md_whirlpool); + EVP_MD_meth_free(md_sha256); + + +=head1 SEE ALSO + +L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>, +L<EVP_PKEY_derive_init_ex(3)>, +L<OPENSSL_CTX(3)>, +L<EVP_set_default_properties(3)>, +L<EVP_MD_fetch(3)>, +L<EVP_CIPHER_fetch(3)>, +L<EVP_KEYMGMT_fetch(3)>, +L<openssl-core.h(7)>, +L<provider-base(7)>, +L<provider-digest(7)>, +L<provider-cipher(7)>, +L<provider-keyexch(7)> + +=head1 HISTORY + +The concept of providers and everything surrounding them was +introduced in OpenSSL 3.0. + +=head1 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 +L<https://www.openssl.org/source/license.html>. + +=cut |