mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-02-17 14:32:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Clarify the documentation for the "byname" functions

Browse Source 
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)
This commit is contained in:
Matt Caswell 2021-10-22 15:34:19 +01:00
parent 051228353a
commit 971dbab4ad
3 changed files with 41 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/man3/EVP_DigestInit.pod
View File

@ -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

25
doc/man3/EVP_EncryptInit.pod
View File

@ -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()

4
doc/man7/crypto.pod
View File

@ -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.