.\" $OpenBSD: EVP_add_cipher.3,v 1.6 2023/08/25 18:39:04 schwarze 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_digest_alias ,
.Nm EVP_delete_digest_alias
.Nd maintain lookup tables for cipher and digest 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_delete_cipher_alias
.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_delete_digest_alias
.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_delete_cipher_alias
add and remove the
.Fa alias
for the cipher
.Fa name .
They are implemented as macros wrapping
.Xr OBJ_NAME_add 3
and
.Xr OBJ_NAME_remove 3
with
.Fa type
set to the bitwise or of
.Dv OBJ_NAME_TYPE_CIPHER_METH
and
.Dv OBJ_NAME_ALIAS .
.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 ,
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 all 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_delete_digest_alias
add and remove the
.Fa alias
for the digest
.Fa name .
They are implemented as macros wrapping
.Xr OBJ_NAME_add 3
and
.Xr OBJ_NAME_remove 3
with
.Fa type
set to the bitwise or of
.Dv OBJ_NAME_TYPE_MD_METH
and
.Dv OBJ_NAME_ALIAS .
.Sh RETURN VALUES
.Fn EVP_add_cipher ,
.Fn EVP_add_cipher_alias ,
.Fn EVP_add_digest ,
and
.Fn EVP_add_digest_alias
return 1 on success or 0 if memory allocation fails.
.Pp
.Fn EVP_delete_cipher_alias
and
.Fn EVP_delete_digest_alias
return 1 if one alias was removed or 0 otherwise.
.Sh SEE ALSO
.Xr evp 3 ,
.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 ,
.Xr OpenSSL_add_all_algorithms 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_digest_alias ,
and
.Fn EVP_delete_digest_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,
leaving it in an unknown state.
.Pp
While aliases can be added and removed, there is no dedicated API
to remove added ciphers or digests.