Document the functions EVP_MD_fetch() and EVP_MD_upref()

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/8513)

2 files changed, 175 insertions, 4 deletions

diff --git a/doc/man3/EVP_MD_fetch.pod b/doc/man3/EVP_MD_fetch.pod
new file mode 100644
index 0000000000..17481089f0
--- /dev/null
+++ b/doc/man3/EVP_MD_fetch.pod
@@ -0,0 +1,162 @@
+=pod
+
+=head1 NAME
+
+EVP_MD_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);
+
+=head1 DESCRIPTION
+
+The B<EVP_MD> object is used for representing a digest method implementation.
+
+Having obtained a digest implementation as an B<EVP_MD> type it can be used to
+calculate the digest of input data using functions such as
+L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>.
+
+Digest implementations may be obtained in one of three ways, i.e. implicit
+lookup, explicit lookup or user defined.
+
+=over 4
+
+=item Implicit Lookup
+
+With implicit lookup an application can use functions such as L<EVP_sha256(3)>,
+L<EVP_sha512(3)> or L<EVP_blake2b512(3)> to obtain an B<EVP_MD> object. When
+used in a function like L<EVP_DigestInit_ex(3)> the actual implementation to
+be used will be fetched implicitly using default search criteria. Typically,
+(unless the default search criteria have been changed and/or different providers
+have been loaded), this will return an implementation of the appropriate
+algorithm from the default provider.
+
+=item Explicit Lookup
+
+With explicit lookup an application uses the EVP_MD_fetch() function to obtain
+an algorithm implementation. An implementation with the given name and
+satisfying the search criteria specified in the B<properties> parameter will be
+looked for within the available providers and returned. See L<OSSL_PROVIDER(3)>
+for information about providers.
+
+=item User defined
+
+Using the user defined approach an application constructs its own EVP_MD object.
+See L<EVP_MD_meth_new(3)> for details.
+
+=back
+
+The EVP_MD_fetch() function 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 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.
+
+Additional algorithm implementations may be obtained by loading the "legacy"
+provider. The names of these 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_upref(3)>.
+
+=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);
+
+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 implmentation 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(3)>, L<EVP_MD_meth_new(3)>, L<EVP_MD_meth_free(3)>,
+L<EVP_MD_upref(3)>, L<OSSL_PROVIDER_load(3)>, L<OPENSSL_CTX(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/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod
index f4ac92d561..6269a05c34 100644
--- a/doc/man3/EVP_MD_meth_new.pod
+++ b/doc/man3/EVP_MD_meth_new.pod
@@ -11,7 +11,7 @@ EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
 EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
 EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
 EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
-EVP_MD_meth_get_ctrl
+EVP_MD_meth_get_ctrl, EVP_MD_upref
 - Routines to build up EVP_MD methods
 
 =head1 SYNOPSIS
@@ -54,17 +54,21 @@ EVP_MD_meth_get_ctrl
  int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
                                                int p1, void *p2);
 
+ int EVP_MD_upref(EVP_MD *md);
+
 =head1 DESCRIPTION
 
 The B<EVP_MD> type is a structure for digest method implementation.
 It can also have associated public/private key signing and verifying
 routines.
 
-EVP_MD_meth_new() creates a new B<EVP_MD> structure.
+EVP_MD_meth_new() creates a new B<EVP_MD> structure. Note that B<EVP_MD>
+structures are reference counted.
 
 EVP_MD_meth_dup() creates a copy of B<md>.
 
-EVP_MD_meth_free() destroys a B<EVP_MD> structure.
+EVP_MD_meth_free() decrements the reference count for the B<EVP_MD> structure.
+If the reference count drops to 0 then the structure is freed.
 
 EVP_MD_meth_set_input_blocksize() sets the internal input block size
 for the method B<md> to B<blocksize> bytes.
@@ -158,6 +162,8 @@ EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
 to retrieve the method data given with the EVP_MD_meth_set_*()
 functions above.
 
+EVP_MD_upref() increments the reference count for an EVP_MD structure.
+
 =head1 RETURN VALUES
 
 EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly
@@ -169,6 +175,8 @@ indicated sizes or flags.
 All other EVP_CIPHER_meth_get_*() functions return pointers to their
 respective B<md> function.
 
+EVP_MD_upref() returns 1 for success or 0 otherwise.
+
 =head1 SEE ALSO
 
 L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
@@ -176,7 +184,8 @@ L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
 =head1 HISTORY
 
 The B<EVP_MD> structure was openly available in OpenSSL before version
-1.1.  The functions described here were added in OpenSSL 1.1.
+1.1.  EVP_MD_upref() was added in OpenSSL 3.0. All other functions described
+here were added in OpenSSL 1.1.
 
 =head1 COPYRIGHT