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:08:44 +0100 |
commit | 971dbab4ad20193c27e8c3865e92e8f487b89334 (patch) | |
tree | 5d313dc28f9084704339a7d1e96d9599d68acfcb /doc/man3/EVP_EncryptInit.pod | |
parent | 051228353a9842eede597294603cc06a55e3a22c (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)
Diffstat (limited to 'doc/man3/EVP_EncryptInit.pod')
-rw-r--r-- | doc/man3/EVP_EncryptInit.pod | 25 |
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() |