191 lines
4.5 KiB
Groff
191 lines
4.5 KiB
Groff
.\" $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.
|