From 2cafb1dff3ef13c470c4d2d7b1d8a1f7142d8813 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Thu, 18 Jul 2019 12:24:55 +0200 Subject: [PATCH] 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 (Merged from https://github.com/openssl/openssl/pull/9409) --- 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 ---------------------------------- 4 files changed, 56 insertions(+), 259 deletions(-) delete mode 100644 doc/man3/EVP_MD_fetch.pod diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index bc10fa36c5..6f36f0a07b 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 + 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 from any +provider offering it, within the criteria given by the B. +See L for further information. + +The returned value must eventually be freed with L. + =item EVP_MD_CTX_new() Allocates and returns a digest context. @@ -123,9 +134,12 @@ If B is NULL the default implementation of digest B is used. =item EVP_DigestInit_ex() -Sets up digest context B to use a digest B from ENGINE B. -B will typically be supplied by a function such as EVP_sha1(). If -B is NULL then the default implementation of digest B is used. +Sets up digest context B to use a digest B. +B is typically supplied by a function such as EVP_sha1(), or a +value explicitly fetched with EVP_MD_fetch(). + +If B is non-NULL, its implementation of the digest B 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 for success or NULL for failure. + =item EVP_DigestInit_ex(), EVP_DigestUpdate(), EVP_DigestFinal_ex() @@ -487,6 +505,7 @@ L, L, L, L +L =head1 HISTORY diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 3c2e36bb89..e4fb0c43ca 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 + 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 from any provider offering it, within the criteria given +by the B. +See L for further information. + +The returned value must eventually be freed with +L. + 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 for encryption -with cipher B from ENGINE B. B must be created -before calling this function. B is normally supplied -by a function such as EVP_aes_256_cbc(). If B is NULL then the -default implementation is used. B is the symmetric key to use +with cipher B. B is typically supplied by a function such +as EVP_aes_256_cbc(), or a value explicitly fetched with +EVP_CIPHER_fetch(). If B is non-NULL, its implementation of the +cipher B is used if there is one, and if not, the default +implementation is used. B is the symmetric key to use and B 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 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 for success +and B for failure. + EVP_CIPHER_CTX_new() returns a pointer to a newly created B for success and B for failure. diff --git a/doc/man3/EVP_KEYEXCH_free.pod b/doc/man3/EVP_KEYEXCH_free.pod index d10d768b97..912434d5c9 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 + 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 from any provider offering it, within the criteria given +by the B. +See L for further information. + +The returned value must eventually be freed with EVP_KEYEXCH_free(). + EVP_KEYEXCH_free() decrements the reference count for the B structure. Typically this structure will have been obtained from an earlier call -to L. 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 @@ -24,11 +33,14 @@ structure. =head1 RETURN VALUES +EVP_KEYEXCH_fetch() returns a pointer to a B for success +or B for failure. + EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise. =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/man3/EVP_MD_fetch.pod b/doc/man3/EVP_MD_fetch.pod deleted file mode 100644 index 98e4c84e86..0000000000 --- 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 - - 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 - -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. - -=item B - -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, -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. - -Implicit fetching can also occur with functions such as -L 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 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 algorithm -object. -See L and L 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 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 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 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. - -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 - -Where an application that previously used implicit fetch is converted to use -explicit fetch care should be taken with the L 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, L, L, -L, L, 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 -- 2.25.1