From b36e491b23fea67b632fb495b2b70bd438562ffa Mon Sep 17 00:00:00 2001 From: tb Date: Fri, 25 Aug 2023 05:29:35 +0000 Subject: [PATCH] Document EVP_add_{cipher,digest} and friends These and EVP_{add,remove}_{cipher,digest}_alias() are mostly for internal use. --- lib/libcrypto/man/EVP_add_cipher.3 | 158 +++++++++++++++++++++++++++++ lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/evp.3 | 5 +- 3 files changed, 163 insertions(+), 3 deletions(-) create mode 100644 lib/libcrypto/man/EVP_add_cipher.3 diff --git a/lib/libcrypto/man/EVP_add_cipher.3 b/lib/libcrypto/man/EVP_add_cipher.3 new file mode 100644 index 00000000000..ff43129259f --- /dev/null +++ b/lib/libcrypto/man/EVP_add_cipher.3 @@ -0,0 +1,158 @@ +.\" $OpenBSD: EVP_add_cipher.3,v 1.1 2023/08/25 05:29:35 tb Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 25 2023 $ +.Dt EVP_ADD_CIPHER 3 +.Os +.Sh NAME +.Nm EVP_add_cipher , +.Nm EVP_add_cipher_alias , +.Nm EVP_delete_cipher_alias , +.Nm EVP_add_digest , +.Nm EVP_add_cipher_alias , +.Nm EVP_delete_cipher_alias +.Nd maintain cipher and digest lookup by names +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_add_cipher +.Fa "const EVP_CIPHER *cipher" +.Fc +.Ft int +.Fo EVP_add_cipher_alias +.Fa "const char *name" +.Fa "const char *alias" +.Fc +.Ft int +.Fo EVP_remove_cipher_alias +.Fa "const char *name" +.Fa "const char *alias" +.Fc +.Ft int +.Fo EVP_add_digest +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_add_digest_alias +.Fa "const char *name" +.Fa "const char *alias" +.Fc +.Ft int +.Fo EVP_remove_digest_alias +.Fa "const char *name" +.Fa "const char *alias" +.Fc +.Sh DESCRIPTION +.Fn EVP_add_cipher +adds +.Fa cipher +to a global lookup table so that it can be retrieved with +.Xr EVP_get_cipherbyname 3 +using both its long and short names, +as determined by the +.Fa cipher Ns 's +NID via +.Xr OBJ_nid2ln 3 +and +.Xr OBJ_nid2sn 3 . +It is the caller's responsibility to ensure that the long +and short names are not +.Dv NULL . +Internally, the lookup table is the global associative array and +.Xr OBJ_NAME_add 3 +is used to add two key-value pairs with value pointer +.Fa cipher +and the keys consisting of the names and +the type +.Dv OBJ_NAME_TYPE_CIPHER_METH . +.Pp +.Fn EVP_add_cipher_alias +and +.Fn EVP_remove_cipher_alias +add and remove the +.Fa alias +for the cipher +.Fa name . +They are implemented as macros. +.Pp +.Fn EVP_add_digest +adds +.Fa md +to a global lookup table so that it can be retrieved with +.Xr EVP_get_digestbyname 3 +using both its long and short names, +as determined by the +.Fa md Ns 's +NID via +.Xr OBJ_nid2ln 3 +and +.Xr OBJ_nid2sn 3 . +If the +.Fa md +has an associated public key signing algorithm (see +.Xr EVP_MD_pkey_type 3 ) +distinct from the +.Fa md Ns 's +NID, the signing algorithm's short and long names are added as aliases for +the short name of +.Fa md . +It is the caller's responsibility to ensure that the long +and short names are not +.Dv NULL . +Internally, the lookup table is the global associative array and +.Xr OBJ_NAME_add 3 +is used to add two key-value pairs with value pointer +.Fa md +and the keys consisting of the names and +the type +.Dv OBJ_NAME_TYPE_MD_METH . +The aliases are added with +.Fn EVP_add_digest_alias . +.Pp +.Fn EVP_add_digest_alias +and +.Fn EVP_remove_digest_alias +add and remove the +.Fa alias +for the digest +.Fa name . +They are implemented as macros. +.Sh RETURN VALUES +These functions return 1 on success and 0 on failure. +.Sh SEE ALSO +.Xr EVP_CIPHER_meth_new 3 , +.Xr EVP_get_cipherbyname 3 , +.Xr EVP_get_digestbyname 3 , +.Xr EVP_MD_meth_new 3 , +.Xr OBJ_create 3 , +.Xr OBJ_NAME_add 3 +.Sh HISTORY +.Fn EVP_add_cipher +and +.Fn EVP_add_digest +first appeared in OpenSSL 0.9.0 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_add_cipher_alias , +.Fn EVP_delete_cipher_alias , +.Fn EVP_add_cipher_alias , +and +.Fn EVP_delete_cipher_alias +first appeared in OpenSSL 0.9.4 and have been available since +.Ox 2.6 . +.Sh BUGS +Key-value pairs already added before an error occurred +remain in the global associative array. diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 9af9d28c4fa..27e64c494f9 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.261 2023/08/15 11:26:49 schwarze Exp $ +# $OpenBSD: Makefile,v 1.262 2023/08/25 05:29:35 tb Exp $ .include @@ -198,6 +198,7 @@ MAN= \ EVP_SealInit.3 \ EVP_SignInit.3 \ EVP_VerifyInit.3 \ + EVP_add_cipher.3 \ EVP_aes_128_cbc.3 \ EVP_camellia_128_cbc.3 \ EVP_chacha20.3 \ diff --git a/lib/libcrypto/man/evp.3 b/lib/libcrypto/man/evp.3 index 36f0e07003f..02e21b85709 100644 --- a/lib/libcrypto/man/evp.3 +++ b/lib/libcrypto/man/evp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: evp.3,v 1.17 2023/08/15 11:26:49 schwarze Exp $ +.\" $OpenBSD: evp.3,v 1.18 2023/08/25 05:29:35 tb Exp $ .\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +0100 .\" .\" This file was written by Ulf Moeller , @@ -51,7 +51,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 15 2023 $ +.Dd $Mdocdate: August 25 2023 $ .Dt EVP 3 .Os .Sh NAME @@ -194,6 +194,7 @@ operations are more efficient using the high-level interfaces. .Xr ENGINE_get_cipher 3 , .Xr ENGINE_register_RSA 3 , .Xr EVP_AEAD_CTX_init 3 , +.Xr EVP_add_cipher 3 , .Xr EVP_aes_128_cbc 3 , .Xr EVP_BytesToKey 3 , .Xr EVP_camellia_128_cbc 3 , -- 2.20.1