diff options
author | Matt Caswell <matt@openssl.org> | 2021-03-25 16:55:51 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2021-04-08 12:20:22 +0100 |
commit | 4adfbe4c927da1b607ccb7af74872de32d54977f (patch) | |
tree | 7f532d80a01b35cbb7f938e2120a8f7a1b600d85 | |
parent | 7008df2ba5089ab39543c5b519ad3b8f6eed633f (diff) |
Update provider.pod
The previous commits moved some content out of provider.pod into other
pages, so that content is now removed. provider.pod is now exclusively
focussed on provider authors.
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1487)
-rw-r--r-- | doc/man7/provider.pod | 200 |
1 files changed, 8 insertions, 192 deletions
diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index e9d9c6b7b1..797ef45553 100644 --- a/doc/man7/provider.pod +++ b/doc/man7/provider.pod @@ -14,6 +14,8 @@ provider - OpenSSL operation implementation providers =head2 General +This page contains information useful to provider authors. + 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. @@ -27,9 +29,9 @@ 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 +See L<crypto(7)> for further details. -I<NOTE: This section is mostly interesting for provider authors.> +=head2 Provider 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, @@ -90,12 +92,10 @@ 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). +(see L<crypto(7)/ALGORITHM FETCHING>). =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_>. @@ -170,74 +170,6 @@ L<provider-encoder(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<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 -L<OSSL_PROVIDER_load(3)>) will be considered by the fetching -function. In case no provider has been loaded in this library context -the default provider will be loaded as fallback (see -L<OSSL_PROVIDER-default(7)>). - -=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)>. - -=head3 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 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. - =head3 Algorithm naming Algorithm names are case insensitive. Any particular algorithm can have multiple @@ -262,125 +194,9 @@ use alternative names or names that OpenSSL has used historically. =head1 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 L<openssl-list(1)> command can be used to list the -currently available algorithms. - -The names of the algorithms shown from L<openssl-list(1)> 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 "provider=default" -can be used as a search criterion for these implementations. The default -provider includes all the functionality of the base provider below. - -=head2 Base provider - -The base 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 "provider=base" -can be used as a search criterion for these implementations. Some -non-cryptographic algorithms (such as encoders 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. - -=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 "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 also contains a number of non-approved algorithm -implementations and these can be selected with the property "fips=no". - -=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 "provider=legacy" can be -used as a search criterion for these implementations. - -=head2 Null provider - -The null provider is built in as part of the F<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. - -=head1 EXAMPLES - -=head2 Fetching - -Fetch any available implementation of SHA2-256 in the default context: - - EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL); - ... - EVP_MD_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_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_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_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_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_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_free(md_whirlpool); - EVP_MD_free(md_sha256); - +OpenSSL provides a number of its own providers. These are the default, base, +fips, legacy and null providers. See L<crypto(7)> for an overview of these +providers. =head1 SEE ALSO |