diff options
author | Matt Caswell <matt@openssl.org> | 2021-10-22 15:34:19 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2021-10-27 12:15:16 +0100 |
commit | 81cb26d457f866efdc3a22ffb018327c5a002570 (patch) | |
tree | 5ecf4eade64bfc2c479255dbe51b3a9de314b9a6 | |
parent | dd292ed62cc5d3eb0c529aa51a07ec1ed34a9a5f (diff) |
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)
(cherry picked from commit 971dbab4ad20193c27e8c3865e92e8f487b89334)
-rw-r--r-- | doc/man3/EVP_DigestInit.pod | 18 | ||||
-rw-r--r-- | doc/man3/EVP_EncryptInit.pod | 25 | ||||
-rw-r--r-- | 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. |