[openssl] openssl-3.0 update

[Matt Caswell]

The branch openssl-3.0 has been updated
       via  81cb26d457f866efdc3a22ffb018327c5a002570 (commit)
      from  dd292ed62cc5d3eb0c529aa51a07ec1ed34a9a5f (commit)


- Log -----------------------------------------------------------------
commit 81cb26d457f866efdc3a22ffb018327c5a002570
Author: Matt Caswell <matt at openssl.org>
Date:   Fri Oct 22 15:34:19 2021 +0100

    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 at openssl.org>
    Reviewed-by: Tomas Mraz <tomas at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/16893)
    
    (cherry picked from commit 971dbab4ad20193c27e8c3865e92e8f487b89334)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/EVP_DigestInit.pod  | 18 ++++++++++++++++++
 doc/man3/EVP_EncryptInit.pod | 25 +++++++++++++++++++++----
 doc/man7/crypto.pod          |  4 ++--
 3 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 75d8e63e24..391081c9cb 100644
--- 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 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()
 
diff --git a/doc/man7/crypto.pod b/doc/man7/crypto.pod
index 9aa667118d..2b09ad8903 100644
--- 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.