[openssl] master update
Matt Caswell
matt at openssl.org
Thu Apr 8 11:21:23 UTC 2021
The branch master has been updated
via 71a05dcd33ccdb8e3446d9a0cc7a36e8993a83ce (commit)
via 906bced110c156f98e5e4725d7d6de5a8da93089 (commit)
via 4adfbe4c927da1b607ccb7af74872de32d54977f (commit)
via 7008df2ba5089ab39543c5b519ad3b8f6eed633f (commit)
via 0666d5318e5b71869b461fa5aae38ed44cd7e4ab (commit)
from 27947123c9f17deac005b2afd265e38903349918 (commit)
- Log -----------------------------------------------------------------
commit 71a05dcd33ccdb8e3446d9a0cc7a36e8993a83ce
Author: Matt Caswell <matt at openssl.org>
Date: Thu Mar 25 17:05:49 2021 +0000
Remove a TODO in EVP_set_default_properties
Fixes #14371
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1487)
commit 906bced110c156f98e5e4725d7d6de5a8da93089
Author: Matt Caswell <matt at openssl.org>
Date: Thu Mar 25 17:02:25 2021 +0000
Update the algorithm fetching documentation links
The documentation on algorithm fetching has moved. There were a lot of
references to the old location so we update all of those locations.
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1487)
commit 4adfbe4c927da1b607ccb7af74872de32d54977f
Author: Matt Caswell <matt at openssl.org>
Date: Thu Mar 25 16:55:51 2021 +0000
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 at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1487)
commit 7008df2ba5089ab39543c5b519ad3b8f6eed633f
Author: Matt Caswell <matt at openssl.org>
Date: Thu Mar 25 15:54:56 2021 +0000
Add additional glossary entries
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1487)
commit 0666d5318e5b71869b461fa5aae38ed44cd7e4ab
Author: Matt Caswell <matt at openssl.org>
Date: Wed Mar 24 17:41:01 2021 +0000
Expand the libcrypto documentation
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1487)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/EVP_ASYM_CIPHER_free.pod | 4 +-
doc/man3/EVP_DigestInit.pod | 4 +-
doc/man3/EVP_EncryptInit.pod | 2 +-
doc/man3/EVP_KDF.pod | 2 +-
doc/man3/EVP_KEM_free.pod | 4 +-
doc/man3/EVP_KEYEXCH_free.pod | 4 +-
doc/man3/EVP_MAC.pod | 2 +-
doc/man3/EVP_RAND.pod | 2 +-
doc/man3/EVP_SIGNATURE_free.pod | 4 +-
doc/man3/EVP_set_default_properties.pod | 8 +-
doc/man3/OCSP_response_status.pod | 4 +-
doc/man3/OSSL_CRMF_pbmp_new.pod | 2 +-
doc/man3/SRP_Calc_B.pod | 2 +-
doc/man3/SRP_create_verifier.pod | 2 +-
doc/man3/SSL_CTX_new.pod | 2 +-
doc/man7/crypto.pod | 463 ++++++++++++++++++++++++++++++--
doc/man7/openssl-glossary.pod | 131 +++++++++
doc/man7/provider.pod | 200 +-------------
18 files changed, 602 insertions(+), 240 deletions(-)
diff --git a/doc/man3/EVP_ASYM_CIPHER_free.pod b/doc/man3/EVP_ASYM_CIPHER_free.pod
index 2500109e45..dfe67d9993 100644
--- a/doc/man3/EVP_ASYM_CIPHER_free.pod
+++ b/doc/man3/EVP_ASYM_CIPHER_free.pod
@@ -38,7 +38,7 @@ B<algorithm> from any provider offering it, within the criteria given
by the B<properties> and in the scope of the given library context B<ctx> (see
L<OSSL_LIB_CTX(3)>). The algorithm will be one offering functions for performing
asymmetric cipher related tasks such as asymmetric encryption and decryption.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
The returned value must eventually be freed with EVP_ASYM_CIPHER_free().
@@ -90,7 +90,7 @@ return a constant B<OSSL_PARAM> array or NULL on error.
=head1 SEE ALSO
-L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
+L<crypto(7)/ALGORITHM FETCHING>, L<OSSL_PROVIDER(3)>
=head1 HISTORY
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 6299aa3d20..d01414e5e6 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -122,7 +122,7 @@ The B<EVP_MD> type is a structure for digest method implementation.
Fetches the digest implementation for the given I<algorithm> from any
provider offering it, within the criteria given by the I<properties>.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
The returned value must eventually be freed with EVP_MD_free().
@@ -677,7 +677,7 @@ L<EVP_sha224(3)>,
L<EVP_sha3_224(3)>,
L<EVP_sm3(3)>,
L<EVP_whirlpool(3)>
-L<provider(7)/Fetching algorithms>
+L<crypto(7)/ALGORITHM FETCHING>
=head1 HISTORY
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 303e93fe06..b07c102e04 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -191,7 +191,7 @@ The B<EVP_CIPHER> type is a structure for cipher method implementation.
EVP_CIPHER_fetch() fetches the cipher implementation for the given
B<algorithm> from any provider offering it, within the criteria given
by the B<properties>.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
The returned value must eventually be freed with EVP_CIPHER_free().
diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod
index c3d0464d2e..08b15f08ab 100644
--- a/doc/man3/EVP_KDF.pod
+++ b/doc/man3/EVP_KDF.pod
@@ -73,7 +73,7 @@ B<EVP_KDF_CTX> is a context type that holds the algorithm inputs.
EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given
a library context I<libctx> and a set of I<properties>.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of
algorithms supported by the default provider.
diff --git a/doc/man3/EVP_KEM_free.pod b/doc/man3/EVP_KEM_free.pod
index 0551afcf8d..906f4eebed 100644
--- a/doc/man3/EVP_KEM_free.pod
+++ b/doc/man3/EVP_KEM_free.pod
@@ -34,7 +34,7 @@ provider offering it, within the criteria given by the B<properties> and in the
scope of the given library context B<ctx> (see L<OSSL_LIB_CTX(3)>). The algorithm
will be one offering functions for performing asymmetric kem related tasks such
as key encapsulation and decapsulation.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
The returned value must eventually be freed with EVP_KEM_free().
@@ -83,7 +83,7 @@ a constant B<OSSL_PARAM> array or NULL on error.
=head1 SEE ALSO
-L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
+L<crypto(7)/ALGORITHM FETCHING>, L<OSSL_PROVIDER(3)>
=head1 HISTORY
diff --git a/doc/man3/EVP_KEYEXCH_free.pod b/doc/man3/EVP_KEYEXCH_free.pod
index a040e7d604..1257dd2e5c 100644
--- a/doc/man3/EVP_KEYEXCH_free.pod
+++ b/doc/man3/EVP_KEYEXCH_free.pod
@@ -35,7 +35,7 @@ EVP_KEYEXCH_gettable_ctx_params, EVP_KEYEXCH_settable_ctx_params
EVP_KEYEXCH_fetch() fetches the key exchange implementation for the given
I<algorithm> from any provider offering it, within the criteria given
by the I<properties>.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
The returned value must eventually be freed with EVP_KEYEXCH_free().
@@ -92,7 +92,7 @@ a constant B<OSSL_PARAM> array or NULL on error.
=head1 SEE ALSO
-L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
+L<crypto(7)/ALGORITHM FETCHING>, L<OSSL_PROVIDER(3)>
=head1 HISTORY
diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index a4da280ab4..2a8fb5332e 100644
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -86,7 +86,7 @@ rely on an underlying computation algorithm.
EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given
a library context I<libctx> and a set of I<properties>.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
See L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)> for the list
of algorithms supported by the default provider.
diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod
index ab0fdbcb48..23906da5ba 100644
--- a/doc/man3/EVP_RAND.pod
+++ b/doc/man3/EVP_RAND.pod
@@ -97,7 +97,7 @@ B<EVP_RAND_CTX> structures are reference counted.
EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given
a library context I<libctx> and a set of I<properties>.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
The returned value must eventually be freed with
L<EVP_RAND_free(3)>.
diff --git a/doc/man3/EVP_SIGNATURE_free.pod b/doc/man3/EVP_SIGNATURE_free.pod
index de1b22f387..71f283fdc6 100644
--- a/doc/man3/EVP_SIGNATURE_free.pod
+++ b/doc/man3/EVP_SIGNATURE_free.pod
@@ -38,7 +38,7 @@ B<algorithm> from any provider offering it, within the criteria given
by the B<properties>.
The algorithm will be one offering functions for performing signature related
tasks such as signing and verifying.
-See L<provider(7)/Fetching algorithms> for further information.
+See L<crypto(7)/ALGORITHM FETCHING> for further information.
The returned value must eventually be freed with EVP_SIGNATURE_free().
@@ -90,7 +90,7 @@ return a constant B<OSSL_PARAM> array or NULL on error.
=head1 SEE ALSO
-L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
+L<crypto(7)/ALGORITHM FETCHING>, L<OSSL_PROVIDER(3)>
=head1 HISTORY
diff --git a/doc/man3/EVP_set_default_properties.pod b/doc/man3/EVP_set_default_properties.pod
index 00404bd999..c8385ad1b4 100644
--- a/doc/man3/EVP_set_default_properties.pod
+++ b/doc/man3/EVP_set_default_properties.pod
@@ -17,11 +17,9 @@ EVP_default_properties_is_fips_enabled
=head1 DESCRIPTION
EVP_set_default_properties() sets the default properties for all
-future EVP algorithm fetches, implicit as well as explicit.
-
-=for comment TODO(3.0) We should consider having an EVP document in
-section 7 that details everything about implicit vs explicit fetches
-and how they relate to properties.
+future EVP algorithm fetches, implicit as well as explicit. See
+L<crypto(7)/ALGORITHM FETCHING> for information about implicit and explicit
+fetching.
EVP_set_default_properties stores the properties given with the string
I<propq> among the EVP data that's been stored in the library context
diff --git a/doc/man3/OCSP_response_status.pod b/doc/man3/OCSP_response_status.pod
index c97f22c4ed..9113af3836 100644
--- a/doc/man3/OCSP_response_status.pod
+++ b/doc/man3/OCSP_response_status.pod
@@ -54,7 +54,7 @@ OCSP_RESPID_set_by_key_ex() sets the key of the OCSP_RESPID to be the same as th
key in the supplied X509 certificate I<cert> for the OCSP responder. The key is
stored as a SHA1 hash. To calculate the hash the SHA1 algorithm is fetched using
the library ctx I<libctx> and the property query string I<propq> (see
-L<provider(7)/Fetching algorithms> for further information).
+L<crypto(7)/ALGORITHM FETCHING> for further information).
OCSP_RESPID_set_by_key() does the same as OCSP_RESPID_set_by_key_ex() except
that the default library context is used with an empty property query string.
@@ -66,7 +66,7 @@ setting.
OCSP_RESPID_match_ex() tests whether the OCSP_RESPID given in I<respid> matches
with the X509 certificate I<cert> based on the SHA1 hash. To calculate the hash
the SHA1 algorithm is fetched using the library ctx I<libctx> and the property
-query string I<propq> (see L<provider(7)/Fetching algorithms> for further
+query string I<propq> (see L<crypto(7)/ALGORITHM FETCHING> for further
information).
OCSP_RESPID_match() does the same as OCSP_RESPID_match_ex() except that the
diff --git a/doc/man3/OSSL_CRMF_pbmp_new.pod b/doc/man3/OSSL_CRMF_pbmp_new.pod
index 25368401f1..ff8b3c327c 100644
--- a/doc/man3/OSSL_CRMF_pbmp_new.pod
+++ b/doc/man3/OSSL_CRMF_pbmp_new.pod
@@ -27,7 +27,7 @@ parameters I<pbmp>, message I<msg>, and secret I<sec>, along with the respective
lengths I<msglen> and I<seclen>.
The optional library context I<libctx> and I<propq> parameters may be used
to influence the selection of the MAC algorithm referenced in the I<pbmp>;
-see L<provider(7)/Fetching algorithms> for further information.
+see L<crypto(7)/ALGORITHM FETCHING> for further information.
On success writes the address of the newly
allocated MAC via the I<mac> reference parameter and writes the length via the
I<maclen> reference parameter unless it its NULL.
diff --git a/doc/man3/SRP_Calc_B.pod b/doc/man3/SRP_Calc_B.pod
index 48eb018328..8fa25b0b56 100644
--- a/doc/man3/SRP_Calc_B.pod
+++ b/doc/man3/SRP_Calc_B.pod
@@ -63,7 +63,7 @@ BIGNUM parameters to these functions.
Most of these functions come in two forms. Those that take a I<libctx> and
I<propq> parameter, and those that don't. Any cryptogrpahic functions that
are fetched and used during the calculation use the provided I<libctx> and
-I<propq>. See L<provider(7)/Fetching algorithms> for more details. The variants
+I<propq>. See L<crypto(7)/ALGORITHM FETCHING> for more details. The variants
that do not take a I<libctx> and I<propq> parameter use the default library
context and property query string. The SRP_Calc_server_key() and SRP_Calc_A()
functions do not have a form that takes I<libctx> or I<propq> parameters because
diff --git a/doc/man3/SRP_create_verifier.pod b/doc/man3/SRP_create_verifier.pod
index 74d520199d..37022b7dda 100644
--- a/doc/man3/SRP_create_verifier.pod
+++ b/doc/man3/SRP_create_verifier.pod
@@ -42,7 +42,7 @@ The SRP_create_verifier_BN_ex() function creates an SRP password verifier from
the supplied parameters as defined in section 2.4 of RFC 5054 using the library
context I<libctx> and property query string I<propq>. Any cryptographic
algorithms that need to be fetched will use the I<libctx> and I<propq>. See
-L<provider(7)/Fetching algorithms>.
+L<crypto(7)/ALGORITHM FETCHING>.
SRP_create_verifier_BN() is the same as SRP_create_verifier_BN_ex() except the
default library context and property query string is used.
diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod
index 1c953098e2..6bab45631f 100644
--- a/doc/man3/SSL_CTX_new.pod
+++ b/doc/man3/SSL_CTX_new.pod
@@ -79,7 +79,7 @@ library context I<libctx> (see L<OSSL_LIB_CTX(3)>) is used to provide the
cryptographic algorithms needed for the session. Any cryptographic algorithms
that are used by any B<SSL> objects created from this B<SSL_CTX> will be fetched
from the I<libctx> using the property query string I<propq> (see
-L<provider(7)/Fetching algorithms>. Either or both the I<libctx> or I<propq>
+L<crypto(7)/ALGORITHM FETCHING>. Either or both the I<libctx> or I<propq>
parameters may be NULL.
SSL_CTX_new() does the same as SSL_CTX_new_ex() except that the default
diff --git a/doc/man7/crypto.pod b/doc/man7/crypto.pod
index aa6b6405ba..cf2c3f01d7 100644
--- a/doc/man7/crypto.pod
+++ b/doc/man7/crypto.pod
@@ -12,41 +12,458 @@ See the individual manual pages for details.
The OpenSSL crypto library (C<libcrypto>) implements a wide range of
cryptographic algorithms used in various Internet standards. The services
-provided by this library are used by the OpenSSL implementations of SSL, TLS
-and S/MIME, and they have also been used to implement SSH, OpenPGP, and
-other cryptographic standards.
+provided by this library are used by the OpenSSL implementations of TLS and
+CMS, and they have also been used to implement many other third party products
+and protocols.
-C<libcrypto> consists of a number of sub-libraries that implement the
-individual algorithms.
+The functionality includes symmetric encryption, public key cryptography, key
+agreement, certificate handling, cryptographic hash functions, cryptographic
+pseudo-random number generators, message authentication codes (MACs), key
+derivation functions (KDFs), and various utilities.
-The functionality includes symmetric encryption, public key
-cryptography and key agreement, certificate handling, cryptographic
-hash functions, cryptographic pseudo-random number generator, and
-various utilities.
+=head2 Algorithms
-=head1 NOTES
+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).
-Some of the newer functions follow a naming convention using the numbers
-B<0> and B<1>. For example the functions:
+=head2 Operations
- int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
- int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
+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 L<EVP_EncryptInit(3)> page. Or to
+perform a digest operation using SHA256 then you would use the digesting
+functions on the L<EVP_DigestInit(3)> page.
-The B<0> version uses the supplied structure pointer directly
-in the parent and it will be freed up when the parent is freed.
-In the above example I<crl> would be freed but I<rev> would not.
+=head2 Providers
-The B<1> function uses a copy of the supplied structure pointer
-(or in some cases increases its link count) in the parent and
-so both (I<x> and I<obj> above) should be freed up.
+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.
-=head1 RETURN VALUES
+=head2 Library contexts
-See the individual manual pages for details.
+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 B<OSSL_LIB_CTX> type. Many OpenSSL API
+functions take a library context as a parameter. Applications can always pass
+B<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 L<OSSL_LIB_CTX(3)> for more information about library contexts.
+
+=head2 Multi-threaded applications
+
+As long as OpenSSL has been built with support for threads (the default case
+on most platforms) then most OpenSSL I<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 I<data structures> are not thread-safe. For example
+the L<BIO_write(3)> and L<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 B<BIO> object
+since both of them may attempt to make changes to the same B<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 B<OSSL_LIB_CTX> in
+multiple threads.
+
+See L<openssl-threads(7)> for a more detailed discussion on OpenSSL threading
+support.
+
+=head1 ALGORITHM FETCHING
+
+In order to use an algorithm an implementation for it must first be "fetched".
+Fetching is the process of looking through the available implementations,
+applying selection criteria (via a property query string), and finally choosing
+the implementation that will be used.
+
+Two types of fetching are supported by OpenSSL - explicit fetching and implicit
+fetching.
+
+=head2 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 L<EVP_set_default_properties(3)> function. 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 L<property(7)> for more information about properties.
+
+=head2 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 C<APINAME_fetch>, where
+C<APINAME> is the name of the operation. For example L<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 C<APINAME_fetch> function
+using C<APINAME_free> when it is no longer needed.
+
+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 then the default provider
+will be loaded as a fallback (see L<OSSL_PROVIDER-default(7)>).
+
+=item An identifier
+
+For all currently implemented fetching functions this is the algorithm name.
+
+=item A property query string
+
+The property query string used to guide selection of the algorithm
+implementation.
+
+=back
+
+The algorithm implementation that is fetched can then be used with other diverse
+functions that use them. For example the L<EVP_DigestInit_ex(3)> function takes
+as a parameter an B<EVP_MD> object which may have been returned from an earlier
+call to L<EVP_MD_fetch(3)>.
+
+=head2 Implicit fetch
+
+OpenSSL has a number of functions that return an algorithm object with no
+associated implementation, such as L<EVP_sha256(3)>,
+L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(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 L<EVP_DigestInit_ex(3)> or
+L<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.
+
+=head1 FETCHING EXAMPLES
+
+The following section provides a series of examples of fetching algorithm
+implementations.
+
+Fetch any available implementation of SHA2-256 in the default context. Note
+that some algorithms have aliases. So "SHA256" and "SHA2-256" are synonymous:
+
+ 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);
+
+=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. Also see the provider
+specific manual pages linked below for further details about using the
+algorithms available in each of the providers.
+
+As well as the OpenSSL providers third parties can also implemment providers.
+For information on writing a provider see L<provider(7)>.
+
+=head2 Default provider
+
+The default provider is built in as part of the F<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 L<OSSL_PROVIDER-default(7)>.
+
+=head2 Base provider
+
+The base provider is built in as part of the F<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 L<OSSL_PROVIDER-base(7)>.
+
+=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)>). 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 L<OSSL_PROVIDER-FIPS(7)>.
+
+=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)>). 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 L<OSSL_PROVIDER-legacy(7)>.
+
+=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.
+
+See L<OSSL_PROVIDER-null(7)>.
+
+=head1 USING ALGORITHMS IN APPLICATIONS
+
+Cryptographic algorithms are made available to applications through use of the
+"EVP" APIs. Each of the various operations such as encryption, digesting,
+message authentication codes, etc., have a set of EVP function calls that can
+be invoked to use them. See the L<evp(7)> page for further details.
+
+Most of these follow a common pattern. A "context" object is first created. For
+example for a digest operation you would use an B<EVP_MD_CTX>, and for an
+encryption/decryption operation you would use an B<EVP_CIPHER_CTX>. The
+operation is then initialised ready for use via an "init" function - optionally
+passing in a set of parameters (using the B<OSSL_PARAM> type) to configure how
+the operation should behave. Next data is fed into the operation in a series of
+"update" calls. The operation is finalised using a "final" call which will
+typically provide some kind of output. Finally the context is cleaned up and
+freed.
+
+The following shows a complete example for doing this process for digesting
+data using SHA256. The process is similar for other operations such as
+encryption/decryption, signatures, message authentication codes, etc.
+
+ #include <stdio.h>
+ #include <openssl/evp.h>
+ #include <openssl/bio.h>
+
+ int main(void)
+ {
+ EVP_MD_CTX *ctx = NULL;
+ EVP_MD *sha256 = NULL;
+ const unsigned char msg[] = {
+ 0x00, 0x01, 0x02, 0x03
+ };
+ unsigned int len = 0;
+ unsigned char *outdigest = NULL;
+
+ /* Create a context for the digest operation */
+ ctx = EVP_MD_CTX_new();
+ if (ctx == NULL)
+ goto err;
+
+ /*
+ * Fetch the SHA256 algorithm implementation for doing the digest. We're
+ * using the "default" library context here (first NULL parameter), and
+ * we're not supplying any particular search criteria for our SHA256
+ * implementation (second NULL parameter). Any SHA256 implementation will
+ * do.
+ */
+ sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
+ if (sha256 == NULL)
+ goto err;
+
+ /* Initialise the digest operation */
+ if (!EVP_DigestInit_ex(ctx, sha256, NULL))
+ goto err;
+
+ /*
+ * Pass the message to be digested. This can be passed in over multiple
+ * EVP_DigestUpdate calls if necessary
+ */
+ if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
+ goto err;
+
+ /* Allocate the output buffer */
+ outdigest = OPENSSL_malloc(EVP_MD_size(sha256));
+ if (outdigest == NULL)
+ goto err;
+
+ /* Now calculate the digest itself */
+ if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
+ goto err;
+
+ /* Print out the digest result */
+ BIO_dump_fp(stdout, outdigest, len);
+
+ err:
+ /* Clean up all the resources we allocated */
+ OPENSSL_free(outdigest);
+ EVP_MD_free(sha256);
+ EVP_MD_CTX_free(ctx);
+ }
+
+=head1 CONFIGURATION
+
+By default OpenSSL will load a configuration file when it is first used. This
+will set up various configuration settings within the default library context.
+Applications that create their own library contexts may optionally configure
+them with a config file using the L<OSSL_LIB_CTX_load_config(3)> function.
+
+The configuration file can be used to automatically load providers and set up
+default property query strings.
+
+For information on the OpenSSL configuration file format see L<config(5)>.
+
+=head1 ENCODING AND DECODING KEYS
+
+Many algorithms require the use of a key. Keys can be generated dynamically
+using the EVP APIs (for example see L<EVP_PKEY_gen(3)>). However it is often
+necessary to save or load keys (or their associated parameters) to or from some
+external format such as PEM or DER (see L<openssl-glossary(7)>). OpenSSL uses
+encoders and decoders to perform this task.
+
+Encoders and decoders are just algorithm implementations in the same way as
+any other algorithm implementation in OpenSSL. They are implemented by
+providers. The OpenSSL encoders and decoders are available in the default
+provider. They are also duplicated in the base provider.
+
+For information about encoders see L<OSSL_ENCODER_CTX_new_for_pkey(3)>. For
+information about decoders see L<OSSL_DECODER_CTX_new_for_pkey(3)>.
+
+=head1 LIBRARY CONVENTIONS
+
+Many OpenSSL functions that "get" or "set" a value follow a naming convention
+using the numbers B<0> and B<1>, i.e. "get0", "get1", "set0" and "set1". This
+can also apply to some functions that "add" a value to an existing set, i.e.
+"add0" and "add1".
+
+For example the functions:
+
+ int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
+ int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
+
+In the B<0> version the ownership of the object is passed to (for an add or set)
+or retained by (for a get) the parent object. For example after calling the
+X509_CRL_add0_revoked() function above, ownership of the I<rev> object is passed
+to the I<crl> object. Therefore, after calling this function I<rev> should not
+be freed directly. It will be freed implicitly when I<crl> is freed.
+
+In the B<1> version the ownership of the object is not passed to or retained by
+the parent object. Instead a copy or "up ref" of the object is performed. So
+after calling the X509_add1_trust_object() function above the application will
+still be responsible for freeing the I<obj> value where appropriate.
=head1 SEE ALSO
-L<openssl(1)>, L<ssl(7)>
+L<openssl(1)>, L<ssl(7)>, L<evp(7)>, L<OSSL_LIB_CTX(3)>, L<openssl-threads(7)>,
+L<property(7)>, L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-base(7)>,
+L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-legacy(7)>, L<OSSL_PROVIDER-null(7)>,
+L<openssl-glossary(7)>, L<provider(7)>
=head1 COPYRIGHT
diff --git a/doc/man7/openssl-glossary.pod b/doc/man7/openssl-glossary.pod
index 7aa71ea7a5..5f92a8403c 100644
--- a/doc/man7/openssl-glossary.pod
+++ b/doc/man7/openssl-glossary.pod
@@ -10,6 +10,14 @@ openssl-glossary - An OpenSSL Glossary
=over 4
+=item Algorithm
+
+Cryptograpic primitives such as the SHA256 digest, or AES encryption are
+referred to in OpenSSL as "algorithms". There can be more than one
+implementation for any given algorithm available for use.
+
+L<crypto(7)>
+
=item ASN.1, ASN1
ASN.1 ("Abstract Syntax Notation One") is a notation for describing abstract
@@ -20,6 +28,30 @@ L<https://www.itu.int/rec/T-REC-X.681>,
L<https://www.itu.int/rec/T-REC-X.682>,
L<https://www.itu.int/rec/T-REC-X.683>
+=item Base Provider
+
+An OpenSSL Provider that contains encoders and decoders for OpenSSL keys. All
+the algorithm implementations in the Base Provider are also available in the
+Default Provider.
+
+L<OSSL_PROVIDER-base(7)>
+
+=item Decoder
+
+A decoder is a type of algorithm used for decoding keys and parameters from some
+external format such as PEM or DER.
+
+L<OSSL_DECODER_CTX_new_for_pkey(3)>
+
+=item Default Provider
+
+An OpenSSL Provider that contains the most commmon OpenSSL algorithm
+implementations. It is loaded by default if no other provider is available. All
+the algorithm implementations in the Base Provider are also available in the
+Default Provider.
+
+L<OSSL_PROVIDER-default(7)>
+
=item DER ("Distinguished Encoding Rules")
DER is a binary encoding of data, structured according to an ASN.1
@@ -30,11 +62,81 @@ It is defined in ITU-T document X.690:
L<https://www.itu.int/rec/T-REC-X.690>
+=item Encoder
+
+An encoder is a type of algorithm used for encoding keys and parameters to some
+external format such as PEM or DER.
+
+L<OSSL_ENCODER_CTX_new_for_pkey(3)>
+
+=item Explicit Fetching
+
+Explicit Fetching is a type of Fetching (see Fetching). Explicit Fetching is
+where a function call is made to obtain an algorithm object representing an
+implementation such as L<EVP_MD_fetch(3)> or L<EVP_CIPHER_fetch(3)>
+
+=item Fetching
+
+Fetching is the process of looking through the available algorithm
+implementations, applying selection criteria (via a property query string), and
+finally choosing the implementation that will be used.
+
+Also see Explicit Fetching and Implict Fetching.
+
+L<crypto(7)>
+
+=item FIPS Provider
+
+An OpenSSL Provider that contains OpenSSL algorithm implementations that have
+been validated according to the FIPS 140-2 standard.
+
+L<OSSL_PROVIDER-FIPS(7)>
+
+=item Implicit Fetching
+
+Implicit Fetching is a type of Fetching (see Fetching). Implicit Fetching is
+where an algorithm object with no associated implementation is used such as the
+return value from L<EVP_sha256(3)> or L<EVP_aes_128_cbc(3)>. With implicit
+fetching an implementation is fetched automatically using default selection
+criteria the first time the algorithm is used.
+
+=item Legacy Provider
+
+An OpenSSL Provider that contains algorithm implementations that are considered
+insecure or are no longer in common use.
+
+L<OSSL_PROVIDER-legacy(7)>
+
+=item Library Context
+
+A Library Context in OpenSSL is represented by the type B<OSSL_LIB_CTX>. It can
+be thought of as a scope within which configuration options apply. If an
+application does not explicitly create a library context then the "default"
+one is used. Many OpenSSL functions can take a library context as an argument.
+A NULL value can always be passed to indicate the default library context.
+
+L<OSSL_LIB_CTX(3)>
+
=item MSBLOB
MSBLOB is a Microsoft specific binary format for RSA and DSA keys, both
private and public. This form is never passphrase protected.
+=item Null Provider
+
+An OpenSSL Provider that contains no algorithm implementations. This can be
+useful to prevent the default provider from being automatically loaded in a
+library context.
+
+L<OSSL_PROVIDER-null(7)>
+
+=item Operation
+
+An operation is a group of OpenSSL functions with a common purpose such as
+encryption, or digesting.
+
+L<crypto(7)>
+
=item PEM ("Privacy Enhanced Message")
PEM is a format used for encoding of binary content into a mail and ASCII
@@ -66,6 +168,35 @@ This is specified in RFC 5208:
L<https://tools.ietf.org/html/rfc5208>
+=item Property
+
+A property is a way of classifying and selecting algorithm implementations.
+A property is a key/value pair expressed as a string. For example all algorithm
+implementations in the default provider have the property "provider=default".
+An algorithm implementation can have multiple properties defined against it.
+
+Also see Property Query String.
+
+L<property(7)>
+
+=item Property Query String
+
+A property query string is a string containing a sequence of properties that
+can be used to select an algorithm implementation. For example the query string
+"provider=example,foo=bar" will select algorithms from the "example" provider
+that have a "foo" property defined for them with a value of "bar".
+
+Property Query Strings are used during fetching. See Fetching.
+
+L<property(7)>
+
+=item Provider
+
+A provider in OpenSSL is a component that groups together algorithm
+implementations. Providers can come from OpenSSL itself or from third parties.
+
+L<provider(7)>
+
=item PVK
PVK is a Microsoft specific binary format for RSA and DSA private keys.
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
More information about the openssl-commits
mailing list