From 0415126d1cd7a26e02d2feb3f3e0298779fb8fc6 Mon Sep 17 00:00:00 2001 From: tb <> Date: Fri, 25 Aug 2023 05:29:35 +0000 Subject: Document EVP_add_{cipher,digest} and friends These and EVP_{add,remove}_{cipher,digest}_alias() are mostly for internal use. --- src/lib/libcrypto/man/EVP_add_cipher.3 | 158 +++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 src/lib/libcrypto/man/EVP_add_cipher.3 (limited to 'src/lib/libcrypto/man/EVP_add_cipher.3') diff --git a/src/lib/libcrypto/man/EVP_add_cipher.3 b/src/lib/libcrypto/man/EVP_add_cipher.3 new file mode 100644 index 0000000000..ff43129259 --- /dev/null +++ b/src/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. -- cgit v1.2.3-55-g6feb