[openssl] master update
Richard Levitte
levitte at openssl.org
Mon Jul 22 14:42:28 UTC 2019
The branch master has been updated
via d4c69c69d171edb17b4d609c15891a9599809ed0 (commit)
via 2cafb1dff3ef13c470c4d2d7b1d8a1f7142d8813 (commit)
via e4c0ec6278f1fbfc50fcdd09769f65ca80866f6b (commit)
from a80278b071426c7262c07d3b29100573b94df16d (commit)
- Log -----------------------------------------------------------------
commit d4c69c69d171edb17b4d609c15891a9599809ed0
Author: Richard Levitte <levitte at openssl.org>
Date: Thu Jul 18 15:07:13 2019 +0200
Documentation: add provider-base(7), describing the base functions
The base functions are the first tables of function pointers that
libcrypto and the provider pass to each other, thereby providing a
baseline with which they can communicate further with each other.
This also contains an example for a ficticious provider, providing an
implement of a fictitious algorithm for a fictitious operation.
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9409)
commit 2cafb1dff3ef13c470c4d2d7b1d8a1f7142d8813
Author: Richard Levitte <levitte at openssl.org>
Date: Thu Jul 18 12:24:55 2019 +0200
Documentation: Move the description of the fetching functions
Now that the general descriptions have moved from
doc/man3/EVP_MD_fetch.pod to doc/man7/provider.pod, the description of
the fetching functions themselves can be moved to other pages where
related functions are already described.
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9409)
commit e4c0ec6278f1fbfc50fcdd09769f65ca80866f6b
Author: Richard Levitte <levitte at openssl.org>
Date: Thu Jul 18 12:23:23 2019 +0200
Documentation: Add provider(7), for general description of providers
This includes an enumeration of the providers supplied with OpenSSL,
and what implementations they offer.
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9409)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/EVP_DigestInit.pod | 25 ++-
doc/man3/EVP_EncryptInit.pod | 23 ++-
doc/man3/EVP_KEYEXCH_free.pod | 18 +-
doc/man3/EVP_MD_fetch.pod | 249 -----------------------
doc/man7/provider-base.pod | 464 ++++++++++++++++++++++++++++++++++++++++++
doc/man7/provider.pod | 401 ++++++++++++++++++++++++++++++++++++
6 files changed, 921 insertions(+), 259 deletions(-)
delete mode 100644 doc/man3/EVP_MD_fetch.pod
create mode 100644 doc/man7/provider-base.pod
create mode 100644 doc/man7/provider.pod
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index bc10fa3..6f36f0a 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -2,6 +2,7 @@
=head1 NAME
+EVP_MD_fetch,
EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_params, EVP_MD_CTX_get_params,
EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
@@ -18,6 +19,8 @@ EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
#include <openssl/evp.h>
+ EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm,
+ const char *properties);
EVP_MD_CTX *EVP_MD_CTX_new(void);
int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);
void EVP_MD_CTX_free(EVP_MD_CTX *ctx);
@@ -75,6 +78,14 @@ and should be used instead of the cipher-specific functions.
=over 4
+=item EVP_MD_fetch()
+
+Fetches the digest 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.
+
+The returned value must eventually be freed with L<EVP_MD_meth_free(3)>.
+
=item EVP_MD_CTX_new()
Allocates and returns a digest context.
@@ -123,9 +134,12 @@ If B<impl> is NULL the default implementation of digest B<type> is used.
=item EVP_DigestInit_ex()
-Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
-B<type> will typically be supplied by a function such as EVP_sha1(). If
-B<impl> is NULL then the default implementation of digest B<type> is used.
+Sets up digest context B<ctx> to use a digest B<type>.
+B<type> is typically supplied by a function such as EVP_sha1(), or a
+value explicitly fetched with EVP_MD_fetch().
+
+If B<impl> is non-NULL, its implementation of the digest B<type> is used if
+there is one, and if not, the default implementation is used.
=item EVP_DigestUpdate()
@@ -343,6 +357,10 @@ disabled with this flag.
=over 4
+=item EVP_MD_fetch()
+
+Returns a pointer to a B<EVP_MD> for success or NULL for failure.
+
=item EVP_DigestInit_ex(),
EVP_DigestUpdate(),
EVP_DigestFinal_ex()
@@ -487,6 +505,7 @@ L<EVP_sha224(3)>,
L<EVP_sha3_224(3)>,
L<EVP_sm3(3)>,
L<EVP_whirlpool(3)>
+L<provider(7)/Fetching algorithms>
=head1 HISTORY
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 3c2e36b..e4fb0c4 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -2,6 +2,7 @@
=head1 NAME
+EVP_CIPHER_fetch,
EVP_CIPHER_CTX_new,
EVP_CIPHER_CTX_reset,
EVP_CIPHER_CTX_free,
@@ -54,6 +55,8 @@ EVP_enc_null
#include <openssl/evp.h>
+ EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
+ const char *properties);
EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
@@ -123,6 +126,14 @@ EVP_enc_null
The EVP cipher routines are a high level interface to certain
symmetric ciphers.
+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.
+
+The returned value must eventually be freed with
+L<EVP_CIPHER_meth_free(3)>.
+
EVP_CIPHER_CTX_new() creates a cipher context.
EVP_CIPHER_CTX_free() clears all information from a cipher context
@@ -132,10 +143,11 @@ cipher are complete so sensitive information does not remain in
memory.
EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
-with cipher B<type> from ENGINE B<impl>. B<ctx> must be created
-before calling this function. B<type> is normally supplied
-by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
-default implementation is used. B<key> is the symmetric key to use
+with cipher B<type>. B<type> is typically supplied by a function such
+as EVP_aes_256_cbc(), or a value explicitly fetched with
+EVP_CIPHER_fetch(). If B<impl> is non-NULL, its implementation of the
+cipher B<type> is used if there is one, and if not, the default
+implementation is used. B<key> is the symmetric key to use
and B<iv> is the IV to use (if necessary), the actual number of bytes
used for the key and IV depends on the cipher. It is possible to set
all parameters to NULL except B<type> in an initial call and supply
@@ -280,6 +292,9 @@ buffer at least as big as the value returned by EVP_CIPHER_CTX_key_length().
=head1 RETURN VALUES
+EVP_CIPHER_fetch() returns a pointer to a B<EVP_CIPHER> for success
+and B<NULL> for failure.
+
EVP_CIPHER_CTX_new() returns a pointer to a newly created
B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
diff --git a/doc/man3/EVP_KEYEXCH_free.pod b/doc/man3/EVP_KEYEXCH_free.pod
index d10d768..912434d 100644
--- a/doc/man3/EVP_KEYEXCH_free.pod
+++ b/doc/man3/EVP_KEYEXCH_free.pod
@@ -2,21 +2,30 @@
=head1 NAME
-EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref
+EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref
- Functions to manage EVP_KEYEXCH algorithm objects
=head1 SYNOPSIS
#include <openssl/evp.h>
+ EVP_KEYEXCH *EVP_KEYEXCH_fetch(OPENSSL_CTX *ctx, const char *algorithm,
+ const char *properties);
void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange);
int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange);
=head1 DESCRIPTION
+EVP_KEYEXCH_fetch() fetches the key exchange 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.
+
+The returned value must eventually be freed with EVP_KEYEXCH_free().
+
EVP_KEYEXCH_free() decrements the reference count for the B<EVP_KEYEXCH>
structure. Typically this structure will have been obtained from an earlier call
-to L<EVP_KEYEXCH_fetch(3)>. If the reference count drops to 0 then the
+to EVP_KEYEXCH_fetch(). If the reference count drops to 0 then the
structure is freed.
EVP_KEYEXCH_up_ref() increments the reference count for an B<EVP_KEYEXCH>
@@ -24,11 +33,14 @@ structure.
=head1 RETURN VALUES
+EVP_KEYEXCH_fetch() returns a pointer to a B<EVP_KEYEXCH> for success
+or B<NULL> for failure.
+
EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise.
=head1 SEE ALSO
-L<EVP_KEYEXCH_fetch(3)>
+L<provider(7)/Fetching algorithms>
=head1 HISTORY
diff --git a/doc/man3/EVP_MD_fetch.pod b/doc/man3/EVP_MD_fetch.pod
deleted file mode 100644
index 98e4c84..0000000
--- a/doc/man3/EVP_MD_fetch.pod
+++ /dev/null
@@ -1,249 +0,0 @@
-=pod
-
-=head1 NAME
-
-EVP_MD_fetch, EVP_CIPHER_fetch, EVP_KEYEXCH_fetch
-- Functions to explicitly fetch algorithm implementations
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm,
- const char *properties);
- EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
- const char *properties);
- EVP_KEYEXCH *EVP_KEYEXCH_fetch(OPENSSL_CTX *ctx, const char *algorithm,
- const char *properties);
-
-=head1 DESCRIPTION
-
-Cryptographic algorithms are represented by different OpenSSL objects depending
-on what type of algorithm it is. The following cryptographic algorithm types are
-supported.
-
-=over 4
-
-=item B<EVP_MD>
-
-Represents a digest algorithm.
-
-=item B<EVP_CIPHER>
-
-Represents a symmetric cipher algorithm.
-
-=item B<EVP_MAC>
-
-Represents a Message Authentication Code algorithm.
-
-=item B<EVP_KDF>
-
-Represents a Key Derivation Function algorithm.
-
-=item B<EVP_KEYEXCH>
-
-Represents a Key Exchange algorithm.
-
-=back
-
-The algorithm objects may or may not have an associated algorithm
-implementation.
-Cryptographic algorithms are implemented by providers.
-Any algorithm may be supported by zero or more providers.
-In order to use an algorithm an implementation must first be obtained.
-This can happen in one of three ways, i.e. implicit fetch, explicit fetch or
-user defined.
-
-=over 4
-
-=item Implicit Fetch
-
-With implicit fetch an application can use functions such as L<EVP_sha256(3)>,
-L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)> to obtain an algorithm object with
-no associated implementation.
-When used in a function like L<EVP_DigestInit_ex(3)> or L<EVP_CipherInit_ex(3)>
-the actual implementation to be used will be fetched implicitly using default
-search criteria.
-Typically, this will return an implementation of the appropriate algorithm from
-the default provider unless the default search criteria have been changed and/or
-different providers have been loaded.
-
-Implicit fetching can also occur with functions such as
-L<EVP_PKEY_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.
-
-=item Explicit Fetch
-
-With explicit fetch an application uses one of the "fetch" functions to obtain
-an algorithm object with an associated implementation.
-An implementation with the given name that satisfies the search criteria
-specified in the B<properties> parameter combined with the default search
-criteria will be looked for within the available providers and returned.
-See L<EVP_set_default_properties(3)> for information on default search criteria
-and L<OSSL_PROVIDER(3)> for information about providers.
-
-=item User defined
-
-Using the user defined approach an application constructs its own algorithm
-object.
-See L<EVP_MD_meth_new(3)> and L<EVP_CIPHER_meth_new(3)> for details.
-
-=back
-
-Having obtained an algorithm implementation as an algorithm object it can then
-be used to perform cryptographic operations.
-For example to calculate the digest of input data with an B<EVP_MD> algorithm
-object you can use functions such as L<EVP_DigestInit_ex(3)>,
-L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>.
-
-The fetch functions will look for an algorithm within the providers that
-have been loaded into the B<OPENSSL_CTX> given in the B<ctx> parameter.
-This parameter may be NULL in which case the default B<OPENSSL_CTX> will be
-used.
-See L<OPENSSL_CTX_new(3)> and L<OSSL_PROVIDER_load(3)> for further details.
-
-The B<algorithm> parameter gives the name of the algorithm to be looked up.
-Different algorithms can be made available by loading different providers.
-
-The built-in default provider digest algorithm implementation names are: SHA1,
-SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256, SHA3-224, SHA3-256,
-SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3, BLAKE2b512, BLAKE2s256 and
-MD5-SHA1.
-
-The built-in default provider cipher algorithm implementation names are:
-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 and id-aes128-GCM.
-
-Additional algorithm implementations may be obtained by loading the "legacy"
-provider.
-
-The legacy provider digest algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and
-whirlpool.
-
-The B<properties> parameter specifies the search criteria that will be used to
-look for an algorithm implementation. Properties are given as a comma delimited
-string of name value pairs. In order for an implementation to match, all the
-properties in the query string must match those defined for that implementation.
-Any properties defined by an implementation but not given in the query string
-are ignored. All algorithm implementations in the default provider have the
-property "default=yes". All algorithm implementations in the legacy provider have
-the property "legacy=yes". All algorithm implementations in the FIPS provider
-have the property "fips=yes". In the event that more than one implementation
-of the given algorithm name matches the specified properties then an unspecified
-one of those implementations may be returned. The B<properties> parameter may be
-NULL in which case any implementation from the available providers with the
-given algorithm name will be returned.
-
-The return value from a call to EVP_MD_fetch() must be freed by the caller using
-L<EVP_MD_meth_free(3)>.
-Note that EVP_MD objects are reference counted. See L<EVP_MD_up_ref(3)>.
-
-The return value from a call to EVP_CIPHER_fetch() must be freed by the caller
-using L<EVP_CIPHER_meth_free(3)>.
-Note that EVP_CIPHER objects are reference counted.
-See L<EVP_CIPHER_up_ref(3)>.
-
-=head1 NOTES
-
-Where an application that previously used implicit fetch is converted to use
-explicit fetch care should be taken with the L<EVP_MD_CTX_md(3)> function.
-Specifically, this function returns the EVP_MD object originally passed to
-EVP_DigestInit_ex() (or other similar function). With implicit fetch the
-returned EVP_MD object is guaranteed to be available throughout the application
-lifetime. However, with explicit fetch EVP_MD objects are reference counted.
-EVP_MD_CTX_md does not increment the reference count and so the returned EVP_MD
-object may not be accessible beyond the lifetime of the EVP_MD_CTX it is
-associated with.
-
-=head1 RETURN VALUES
-
-EVP_MD_fetch() returns a pointer to the algorithm implementation represented by
-an EVP_MD object, or NULL on error.
-
-=head1 EXAMPLES
-
-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_MD_meth_new(3)>,
-L<EVP_MD_meth_free(3)>, L<EVP_CIPHER_meth_new(3)>, L<EVP_CIPHER_meth_free(3)>,
-L<EVP_MD_up_ref(3)>, L<EVP_CIPHER_up_ref(3)>, L<OSSL_PROVIDER_load(3)>,
-L<OPENSSL_CTX(3)>, L<EVP_set_default_properties(3)>
-
-=head1 HISTORY
-
-The functions described here were added 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
diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
new file mode 100644
index 0000000..e8e5d28
--- /dev/null
+++ b/doc/man7/provider-base.pod
@@ -0,0 +1,464 @@
+=pod
+
+=head1 NAME
+
+provider-base
+- The basic OpenSSL library E<lt>-E<gt> provider functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/core_numbers.h>
+
+ /*
+ * None of these are actual functions, but are displayed like this for
+ * the function signatures for functions that are offered as function
+ * pointers in OSSL_DISPATCH arrays.
+ */
+
+ /* Functions offered by libcrypto to the providers */
+ const OSSL_ITEM *core_get_param_types(const OSSL_PROVIDER *prov);
+ int core_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
+ int core_thread_start(const OSSL_PROVIDER *prov,
+ OSSL_thread_stop_handler_fn handfn);
+ void core_put_error(const OSSL_PROVIDER *prov,
+ uint32_t reason, const char *file, int line);
+ void core_add_error_vdata(const OSSL_PROVIDER *prov,
+ int num, va_list args);
+ OPENSSL_CTX *core_get_library_context(const OSSL_PROVIDER *prov);
+
+ /*
+ * Some OpenSSL functionality is directly offered to providers via
+ * dispatch
+ */
+ void *CRYPTO_malloc(size_t num, const char *file, int line);
+ void *CRYPTO_zalloc(size_t num, const char *file, int line);
+ void *CRYPTO_memdup(const void *str, size_t siz,
+ const char *file, int line);
+ char *CRYPTO_strdup(const char *str, const char *file, int line);
+ char *CRYPTO_strndup(const char *str, size_t s,
+ const char *file, int line);
+ void CRYPTO_free(void *ptr, const char *file, int line);
+ void CRYPTO_clear_free(void *ptr, size_t num,
+ const char *file, int line);
+ void *CRYPTO_realloc(void *addr, size_t num,
+ const char *file, int line);
+ void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num,
+ const char *file, int line);
+ void *CRYPTO_secure_malloc(size_t num, const char *file, int line);
+ void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);
+ void CRYPTO_secure_free(void *ptr, const char *file, int line);
+ void CRYPTO_secure_clear_free(void *ptr, size_t num,
+ const char *file, int line);
+ int CRYPTO_secure_allocated(const void *ptr);
+ void OPENSSL_cleanse(void *ptr, size_t len);
+ unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
+
+ /* Functions offered by the provider to libcrypto */
+ void provider_teardown(void *provctx);
+ const OSSL_ITEM *provider_get_param_types(void *provctx);
+ int provider_get_params(void *provctx, OSSL_PARAM params[]);
+ const OSSL_ALGORITHM *provider_query_operation(void *provctx,
+ int operation_id,
+ const int *no_store);
+ const OSSL_ITEM *provider_get_reason_strings(void *provctx);
+
+=head1 DESCRIPTION
+
+All "functions" mentioned here are passed as function pointers between
+F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays, in the call
+of the provider initialization function. See L<provider(7)/Provider>
+for a description of the initialization function.
+
+All these "functions" have a corresponding function type definition
+named B<OSSL_{name}_fn>, and a helper function to retrieve the
+function pointer from a B<OSSL_DISPATCH> element named
+B<OSSL_get_{name}>.
+For example, the "function" core_get_param_types() has these:
+
+ typedef OSSL_ITEM *
+ (OSSL_core_get_param_types_fn)(const OSSL_PROVIDER *prov);
+ static ossl_inline OSSL_NAME_core_get_param_types_fn
+ OSSL_get_core_get_param_types(const OSSL_DISPATCH *opf);
+
+B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
+macros in L<openssl-core_numbers.h(7)>, as follows:
+
+For I<in> (the B<OSSL_DISPATCH> array passed from F<libcrypto> to the
+provider):
+
+ core_get_param_types OSSL_FUNC_CORE_GET_PARAM_TYPES
+ core_get_params OSSL_FUNC_CORE_GET_PARAMS
+ core_thread_start OSSL_FUNC_CORE_THREAD_START
+ core_put_error OSSL_FUNC_CORE_PUT_ERROR
+ core_add_error_vdata OSSL_FUNC_CORE_ADD_ERROR_VDATA
+ core_get_library_context OSSL_FUNC_CORE_GET_LIBRARY_CONTEXT
+ CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC
+ CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC
+ CRYPTO_memdup OSSL_FUNC_CRYPTO_MEMDUP
+ CRYPTO_strdup OSSL_FUNC_CRYPTO_STRDUP
+ CRYPTO_strndup OSSL_FUNC_CRYPTO_STRNDUP
+ CRYPTO_free OSSL_FUNC_CRYPTO_FREE
+ CRYPTO_clear_free OSSL_FUNC_CRYPTO_CLEAR_FREE
+ CRYPTO_realloc OSSL_FUNC_CRYPTO_REALLOC
+ CRYPTO_clear_realloc OSSL_FUNC_CRYPTO_CLEAR_REALLOC
+ CRYPTO_secure_malloc OSSL_FUNC_CRYPTO_SECURE_MALLOC
+ CRYPTO_secure_zalloc OSSL_FUNC_CRYPTO_SECURE_ZALLOC
+ CRYPTO_secure_free OSSL_FUNC_CRYPTO_SECURE_FREE
+ CRYPTO_secure_clear_free OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE
+ CRYPTO_secure_allocated OSSL_FUNC_CRYPTO_SECURE_ALLOCATED
+ OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE
+ OPENSSL_hexstr2buf OSSL_FUNC_OPENSSL_HEXSTR2BUF
+
+For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
+F<libcrypto>):
+
+ provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN
+ provider_get_param_types OSSL_FUNC_PROVIDER_GET_PARAM_TYPES
+ provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS
+ provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION
+ provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
+
+=head2 Core functions
+
+core_get_param_types() returns a constant array of descriptor
+B<OSSL_PARAM>, for parameters that core_get_params() can handle.
+
+core_get_params() retrieves I<prov> parameters from the core.
+See L</Core parameters> below for a description of currently known
+parameters.
+
+=for comment core_thread_start() TBA
+
+core_put_error() is used to report an error back to the core, with
+reference to the provider object I<prov>.
+The I<reason> is a number defined by the provider and used to index
+the reason strings table that's returned by
+provider_get_reason_strings().
+I<file> and I<line> may also be passed to indicate exactly where the
+error occured or was reported.
+This corresponds to the OpenSSL function L<ERR_put_error(3)>.
+
+core_add_error_vdata() is used to add additional text data to an
+error already reported with core_put_error().
+It takes I<num> strings in a B<va_list> and concatenates them.
+Provider authors will have to write the corresponding variadic
+argument function.
+
+core_get_library_context() retrieves the library context in which the
+B<OSSL_PROVIDER> object I<prov> is stored.
+This may sometimes be useful if the provider wishes to store a
+reference to its context in the same library context.
+
+CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_memdup(), CRYPTO_strdup(),
+CRYPTO_strndup(), CRYPTO_free(), CRYPTO_clear_free(),
+CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(),
+CRYPTO_secure_zalloc(), CRYPTO_secure_free(),
+CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(),
+OPENSSL_cleanse(), and OPENSSL_hexstr2buf() correspond exactly to the
+public functions with the same name.
+As a matter of fact, the pointers in the B<OSSL_DISPATCH> array are
+direct pointers to those public functions.
+
+=head2 Provider functions
+
+provider_teardown() is called when a provider is shut down and removed
+from the core's provider store.
+It must free the passed I<provctx>.
+
+provider_get_param_types() should return a constant array of
+descriptor B<OSSL_PARAM>, for parameters that provider_get_params()
+can handle.
+
+provider_get_params() should process the B<OSSL_PARAM> array
+I<params>, setting the values of the parameters it understands.
+
+provider_query_operation() should return a constant B<OSSL_ALGORITHM>
+that corresponds to the given I<operation_id>.
+It should indicate if the core may store a reference to this array by
+setting I<*no_store> to 0 (core may store a reference) or 1 (core may
+not store a reference).
+
+provider_get_reason_strings() should return a constant B<OSSL_ITEM>
+array that provides reason strings for reason codes the provider may
+use when reporting errors using core_put_error().
+
+None of these functions are mandatory, but a provider is fairly
+useless without at least provider_query_operation(), and
+provider_get_param_types() is fairly useless if not accompanied by
+provider_get_params().
+
+=head2 Core parameters
+
+core_get_params() understands the following known parameters:
+
+=over 4
+
+=item "openssl-version"
+
+This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
+OpenSSL libraries' full version string, i.e. the string expanded from
+the macro B<OPENSSL_VERSION_STR>.
+
+=item "provider-name"
+
+This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
+OpenSSL libraries' idea of what the calling provider is called.
+
+=back
+
+Additionally, provider specific configuration parameters from the
+config file are available, in dotted name form.
+The dotted name form is a concatenation of section names and final
+config command name separated by periods.
+
+For example, let's say we have the following config example:
+
+ openssl_conf = openssl_init
+
+ [openssl_init]
+ providers = providers_sect
+
+ [providers_sect]
+ foo = foo_sect
+
+ [foo_sect]
+ activate = 1
+ data1 = 2
+ data2 = str
+ more = foo_more
+
+ [foo_more]
+ data3 = foo,bar
+
+The provider will have these additional parameters available:
+
+=over 4
+
+=item "activate"
+
+pointing at the string "1"
+
+=item "data1"
+
+pointing at the string "2"
+
+=item "data2"
+
+pointing at the string "str"
+
+=item "more.data3"
+
+pointing at the string "foo,bar"
+
+=back
+
+For more information on handling parameters, see L<OSSL_PARAM(3)> as
+L<OSSL_PARAM_int(3)>.
+
+=head1 EXAMPLES
+
+This is an example of a simple provider made available as a
+dynamically loadable module.
+It implements the fictitious algorithm C<FOO> for the fictitious
+operation C<BAR>.
+
+ #include <malloc.h>
+ #include <openssl/core.h>
+ #include <openssl/core_numbers.h>
+
+ /* Errors used in this provider */
+ #define E_MALLOC 1
+
+ static const OSSL_ITEM reasons[] = {
+ { E_MALLOC, "memory allocation failure" }.
+ { 0, NULL } /* Termination */
+ };
+
+ /*
+ * To ensure we get the function signature right, forward declare
+ * them using function types provided by openssl/core_numbers.h
+ */
+ OSSL_OP_bar_newctx_fn foo_newctx;
+ OSSL_OP_bar_freectx_fn foo_freectx;
+ OSSL_OP_bar_init_fn foo_init;
+ OSSL_OP_bar_update_fn foo_update;
+ OSSL_OP_bar_final_fn foo_final;
+
+ OSSL_provider_query_operation_fn p_query;
+ OSSL_provider_get_reason_strings_fn p_reasons;
+ OSSL_provider_teardown_fn p_teardown;
+
+ OSSL_provider_init_fn OSSL_provider_init;
+
+ OSSL_core_put_error *c_put_error = NULL;
+
+ /* Provider context */
+ struct prov_ctx_st {
+ OSSL_PROVIDER *prov;
+ }
+
+ /* operation context for the algorithm FOO */
+ struct foo_ctx_st {
+ struct prov_ctx_st *provctx;
+ int b;
+ };
+
+ static void *foo_newctx(void *provctx)
+ {
+ struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx));
+
+ if (fooctx != NULL)
+ fooctx->provctx = provctx;
+ else
+ c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__);
+ return fooctx;
+ }
+
+ static void foo_freectx(void *fooctx)
+ {
+ free(fooctx);
+ }
+
+ static int foo_init(void *vfooctx)
+ {
+ struct foo_ctx_st *fooctx = vfooctx;
+
+ fooctx->b = 0x33;
+ }
+
+ static int foo_update(void *vfooctx, unsigned char *in, size_t inl)
+ {
+ struct foo_ctx_st *fooctx = vfooctx;
+
+ /* did you expect something serious? */
+ if (inl == 0)
+ return 1;
+ for (; inl-- > 0; in++)
+ *in ^= fooctx->b;
+ return 1;
+ }
+
+ static int foo_final(void *vfooctx)
+ {
+ struct foo_ctx_st *fooctx = vfooctx;
+
+ fooctx->b = 0x66;
+ }
+
+ static const OSSL_DISPATCH foo_fns[] = {
+ { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx },
+ { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx },
+ { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init },
+ { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update },
+ { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final },
+ { 0, NULL }
+ };
+
+ static const OSSL_ALGORITHM bars[] = {
+ { "FOO", "provider=chumbawamba", foo_fns },
+ { NULL, NULL, NULL }
+ };
+
+ static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id,
+ int *no_store)
+ {
+ switch (operation_id) {
+ case OSSL_OP_BAR:
+ return bars;
+ }
+ return NULL;
+ }
+
+ static const OSSL_ITEM *p_reasons(void *provctx)
+ {
+ return reasons;
+ }
+
+ static void p_teardown(void *provctx)
+ {
+ free(provctx);
+ }
+
+ static const OSSL_DISPATCH prov_fns[] = {
+ { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown },
+ { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query },
+ { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons },
+ { 0, NULL }
+ };
+
+ int OSSL_provider_init(const OSSL_PROVIDER *provider,
+ const OSSL_DISPATCH *in,
+ const OSSL_DISPATCH **out,
+ void **provctx)
+ {
+ struct prov_ctx_st *pctx = NULL;
+
+ for (; in->function_id != 0; in++)
+ switch (in->function_id) {
+ case OSSL_FUNC_CORE_PUT_ERROR:
+ c_put_error = OSSL_get_core_put_error(in);
+ break;
+ }
+
+ *out = prov_fns;
+
+ if ((pctx = malloc(sizeof(*pctx))) == NULL) {
+ /*
+ * ALEA IACTA EST, if the core retrieves the reason table
+ * regardless, that string will be displayed, otherwise not.
+ */
+ c_put_error(provider, E_MALLOC, __FILE__, __LINE__);
+ return 0;
+ }
+ return 1;
+ }
+
+This relies on a few things existing in F<openssl/core_numbers.h>:
+
+ #define OSSL_OP_BAR 4711
+
+ #define OSSL_FUNC_BAR_NEWCTX 1
+ typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
+ static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
+ { return (OSSL_OP_bar_newctx_fn *)opf->function; }
+
+ #define OSSL_FUNC_BAR_FREECTX 2
+ typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
+ static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
+ { return (OSSL_OP_bar_freectx_fn *)opf->function; }
+
+ #define OSSL_FUNC_BAR_INIT 3
+ typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
+ static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
+ { return (OSSL_OP_bar_init_fn *)opf->function; }
+
+ #define OSSL_FUNC_BAR_UPDATE 4
+ typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
+ unsigned char *in, size_t inl);
+ static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
+ { return (OSSL_OP_bar_update_fn *)opf->function; }
+
+ #define OSSL_FUNC_BAR_FINAL 5
+ typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
+ static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
+ { return (OSSL_OP_bar_final_fn *)opf->function; }
+
+=head1 SEE ALSO
+
+L<provider(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
diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod
new file mode 100644
index 0000000..d9010dc
--- /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
More information about the openssl-commits
mailing list