Document the functions EVP_MD_fetch() and EVP_MD_upref()

=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

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

 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.

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

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)>

=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