From fdf6c0b6b72756ba69be589b2aaecdd51e4ec12a Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Mon, 18 Mar 2019 16:15:58 +0000 Subject: [PATCH] Document the functions EVP_MD_fetch() and EVP_MD_upref() Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/8513) --- doc/man3/EVP_MD_fetch.pod | 162 +++++++++++++++++++++++++++++++++++ doc/man3/EVP_MD_meth_new.pod | 17 +++- 2 files changed, 175 insertions(+), 4 deletions(-) create mode 100644 doc/man3/EVP_MD_fetch.pod 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 + + EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm, + const char *properties); + +=head1 DESCRIPTION + +The B object is used for representing a digest method implementation. + +Having obtained a digest implementation as an B type it can be used to +calculate the digest of input data using functions such as +L, L and L. + +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, +L or L to obtain an B object. When +used in a function like L 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 parameter will be +looked for within the available providers and returned. See L +for information about providers. + +=item User defined + +Using the user defined approach an application constructs its own EVP_MD object. +See L for details. + +=back + +The EVP_MD_fetch() function will look for an algorithm within the providers that +have been loaded into the B given in the B parameter. This +parameter may be NULL in which case the default B will be used. See +L and L for further details. + +The B 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 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 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. Note that EVP_MD objects are reference counted. See +L. + +=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, L, L, +L, L, L + +=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. + +=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 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 structure. +EVP_MD_meth_new() creates a new B structure. Note that B +structures are reference counted. EVP_MD_meth_dup() creates a copy of B. -EVP_MD_meth_free() destroys a B structure. +EVP_MD_meth_free() decrements the reference count for the B 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 to B 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 function. +EVP_MD_upref() returns 1 for success or 0 otherwise. + =head1 SEE ALSO L, L, L @@ -176,7 +184,8 @@ L, L, L =head1 HISTORY The B 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 -- 2.34.1