From: Matt Caswell Date: Mon, 24 Jun 2019 16:34:14 +0000 (+0100) Subject: Add documentation for EVP_CIPHER_fetch X-Git-Tag: openssl-3.0.0-alpha1~1854 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=42738cdeaa1103c0bd1e7500cf64ac62a015b3a2 Add documentation for EVP_CIPHER_fetch We extend the EVP_MD_fetch documentation to be more generic and to also cover EVP_CIPHER_fetch. We expect this to be further expanded with other "fetch" functions in the future. Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/9233) --- diff --git a/doc/man3/EVP_MD_fetch.pod b/doc/man3/EVP_MD_fetch.pod index cba3bc4f0b..f229292a50 100644 --- a/doc/man3/EVP_MD_fetch.pod +++ b/doc/man3/EVP_MD_fetch.pod @@ -2,7 +2,7 @@ =head1 NAME -EVP_MD_fetch +EVP_MD_fetch, EVP_CIPHER_fetch - Functions to explicitly fetch algorithm implementations =head1 SYNOPSIS @@ -11,60 +11,106 @@ EVP_MD_fetch 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); =head1 DESCRIPTION -The B object is used for representing a digest method implementation. +Cryptographic algorithms are represented by different OpenSSL objects depending +on what type of algorithm it is. The following cryptographic algorithm types are +supported. -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. +=over 4 + +=item B + +Represents a digest algorithm. + +=item B + +Represents a symmetric cipher algorithm. + +=item B + +Represents a Message Authentication Code algorithm. + +=item B + +Represents a Key Derivation Function algorithm. + +=back -Digest implementations may be obtained in one of three ways, i.e. implicit -fetch, explicit fetch or user defined. +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, -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. +L or L to obtain an algorithm object with +no associated implementation. +When used in a function like L or L +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. =item Explicit Fetch -With explicit fetch 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 -combined with the default search criteria will be looked for within the -available providers and returned. +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 parameter combined with the default search +criteria will be looked for within the available providers and returned. See L for information on default search criteria and 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. +Using the user defined approach an application constructs its own algorithm +object. +See L and 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. +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 algorithm +object you can use functions such as L, +L and L. + +The fetch functions 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. +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 names of these algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and +provider. + +The legacy provider digest algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and whirlpool. The B parameter specifies the search criteria that will be used to @@ -82,8 +128,13 @@ 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. +L. +Note that EVP_MD objects are reference counted. See L. + +The return value from a call to EVP_CIPHER_fetch() must be freed by the caller +using L. +Note that EVP_CIPHER objects are reference counted. +See L. =head1 NOTES @@ -107,6 +158,14 @@ an EVP_MD object, or NULL on error. 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: @@ -157,9 +216,10 @@ other providers: =head1 SEE ALSO -L, L, L, -L, L, L, -L +L, L, L, +L, L, L, +L, L, L, +L, L =head1 HISTORY diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index 0dc4379a69..1162a2e11c 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -496,7 +496,6 @@ EVP_CIPHER_CTX_set_num EVP_CIPHER_CTX_test_flags EVP_CIPHER_do_all EVP_CIPHER_do_all_sorted -EVP_CIPHER_fetch EVP_CIPHER_get_asn1_iv EVP_CIPHER_impl_ctx_size EVP_CIPHER_set_asn1_iv