Document EVP_add_{cipher,digest} and friends

These and EVP_{add,remove}_{cipher,digest}_alias() are mostly for internal
use.

3 files changed, 163 insertions, 3 deletions

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 <tb@openbsd.org>
+.\"
+.\" 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 <bsd.own.mk>
 
@@ -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 <ulf@openssl.org>,
@@ -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 ,