Clarify the documentation for the "byname" functions

Make it clear that the cipher/digest objects returned from
EVP_get_cipherbyname() and EVP_get_digestbyname() functions have no
associated implementation fetched from a provider.

Fixes #16864

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/16893)

diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 75d8e63e24bbfea29aa01eec316770b52973dda4..391081c9cbce726653b4218f87fcb6269c5cf318 100644 (file)
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -420,6 +420,24 @@ EVP_get_digestbyobj()
 Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an
 B<ASN1_OBJECT> structure respectively.
 
+The EVP_get_digestbyname() function is present for backwards compatibility with
+OpenSSL prior to version 3 and is different to the EVP_MD_fetch() function
+since it does not attempt to "fetch" an implementation of the cipher.
+Additionally, it only knows about digests that are built-in to OpenSSL and have
+an associated NID. Similarly EVP_get_digestbynid() and EVP_get_digestbyobj()
+also return objects without an associated implementation.
+
+When the digest objects returned by these functions are used (such as in a call
+to EVP_DigestInit_ex()) an implementation of the digest will be implicitly
+fetched from the loaded providers. This fetch could fail if no suitable
+implementation is available. Use EVP_MD_fetch() instead to explicitly fetch
+the algorithm and an associated implementation from a provider.
+
+See L<crypto(7)/ALGORITHM FETCHING> for more information about fetching.
+
+The digest objects returned from these functions do not need to be freed with
+EVP_MD_free().
+
 =item EVP_MD_CTX_get_pkey_ctx()
 
 Returns the B<EVP_PKEY_CTX> assigned to I<ctx>. The returned pointer should not

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 93b4f2c38320871deba972de04b08a5e1a7807ba..f289a842a30c1877bba1d2a0fcd71265709fc64c 100644 (file)
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -444,13 +444,30 @@ EVP_CipherFinal_ex() instead.
 
 =item EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
 
-Return an EVP_CIPHER structure when passed a cipher name, a NID or an
-ASN1_OBJECT structure.
+Returns an B<EVP_CIPHER> structure when passed a cipher name, a cipher B<NID> or
+an B<ASN1_OBJECT> structure respectively.
 
 EVP_get_cipherbyname() will return NULL for algorithms such as "AES-128-SIV",
 "AES-128-CBC-CTS" and "CAMELLIA-128-CBC-CTS" which were previously only
-accessible via low level interfaces. Use EVP_CIPHER_fetch() instead to retrieve
-these algorithms from a provider.
+accessible via low level interfaces.
+
+The EVP_get_cipherbyname() function is present for backwards compatibility with
+OpenSSL prior to version 3 and is different to the EVP_CIPHER_fetch() function
+since it does not attempt to "fetch" an implementation of the cipher.
+Additionally, it only knows about ciphers that are built-in to OpenSSL and have
+an associated NID. Similarly EVP_get_cipherbynid() and EVP_get_cipherbyobj()
+also return objects without an associated implementation.
+
+When the cipher objects returned by these functions are used (such as in a call
+to EVP_EncryptInit_ex()) an implementation of the cipher will be implicitly
+fetched from the loaded providers. This fetch could fail if no suitable
+implementation is available. Use EVP_CIPHER_fetch() instead to explicitly fetch
+the algorithm and an associated implementation from a provider.
+
+See L<crypto(7)/ALGORITHM FETCHING> for more information about fetching.
+
+The cipher objects returned from these functions do not need to be freed with
+EVP_CIPHER_free().
 
 =item EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid()
 

diff --git a/doc/man7/crypto.pod b/doc/man7/crypto.pod
index 9aa667118d33cb44c525f1b33d3434d28c7b39d0..2b09ad8903a21e3c8a05d320673da0ba3dda6f6d 100644 (file)
--- a/doc/man7/crypto.pod
+++ b/doc/man7/crypto.pod
@@ -167,8 +167,8 @@ call to L<EVP_MD_fetch(3)>.
 =head2 Implicit fetch
 
 OpenSSL has a number of functions that return an algorithm object with no
-associated implementation, such as L<EVP_sha256(3)>,
-L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>. These are present for
+associated implementation, such as L<EVP_sha256(3)>, L<EVP_aes_128_cbc(3)>,
+L<EVP_get_cipherbyname(3)> or L<EVP_get_digestbyname(3)>. These are present for
 compatibility with OpenSSL before version 3.0 where explicit fetching was not
 available.