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)

1 files changed, 21 insertions, 4 deletions

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 93b4f2c383..f289a842a3 100644
--- 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()