From 81cb26d457f866efdc3a22ffb018327c5a002570 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Fri, 22 Oct 2021 15:34:19 +0100 Subject: 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 Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/16893) (cherry picked from commit 971dbab4ad20193c27e8c3865e92e8f487b89334) --- 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 structure when passed a digest name, a digest B or an B 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 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 assigned to I. 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 structure when passed a cipher name, a cipher B or +an B 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 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. =head2 Implicit fetch OpenSSL has a number of functions that return an algorithm object with no -associated implementation, such as L, -L or L. These are present for +associated implementation, such as L, L, +L or L. These are present for compatibility with OpenSSL before version 3.0 where explicit fetching was not available. -- cgit v1.2.3