From: Matt Caswell Date: Thu, 25 Mar 2021 16:55:51 +0000 (+0000) Subject: Update provider.pod X-Git-Tag: openssl-3.0.0-alpha14~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4adfbe4c927da1b607ccb7af74872de32d54977f;p=thirdparty%2Fopenssl.git 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 (Merged from https://github.com/openssl/openssl/pull/1487) --- diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index e9d9c6b7b11..797ef455531 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, 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 for further details. -I +=head2 Provider A I offers an initialization function, as a set of base functions in the form of an B array, and by extension, @@ -90,12 +92,10 @@ implementations. The returned B is the foundation of any OpenSSL library API that uses providers for their implementation, most commonly in the I type of functions -(see L below). +(see L). =head2 Operations -I - Operations are referred to with numbers, via macros with names starting with C. @@ -170,74 +170,6 @@ L =back -=head2 Fetching algorithms - -=head3 Explicit fetch - -I - -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, where -C is the name of the API, for example L. - -These fetching functions follow a fairly common pattern, where three -arguments are passed: - -=over 4 - -=item The library context - -See L 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) 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). - -=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 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. - -=head3 Implicit fetch - -I - -OpenSSL has a number of functions that return a method object with no -associated implementation, such as L, -L or L, which are present for -compatibility with OpenSSL before version 3.0. - -When they are used with functions like L or -L, 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 command can be used to list the -currently available algorithms. - -The names of the algorithms shown from L 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 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 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). -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). -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 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 for an overview of these +providers. =head1 SEE ALSO