.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.10 2023/09/13 14:18:21 schwarze Exp $
.\" selective merge up to:
.\" OpenSSL man3/EVP_PKEY_ASN1_METHOD b0004708 Nov 1 00:45:24 2017 +0800
.\"
.\" This file is a derived work.
.\" The changes are covered by the following Copyright and license:
.\"
.\" Copyright (c) 2023 Ingo Schwarze <schwarze@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.
.\"
.\" The original file was written by Richard Levitte <levitte@openssl.org>
.\" and Paul Yang <yang.yang@baishancloud.com>.
.\" Copyright (c) 2017 The OpenSSL Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: September 13 2023 $
.Dt EVP_PKEY_ASN1_NEW 3
.Os
.Sh NAME
.Nm EVP_PKEY_asn1_new ,
.Nm EVP_PKEY_asn1_copy ,
.Nm EVP_PKEY_asn1_free ,
.Nm EVP_PKEY_asn1_add0 ,
.Nm EVP_PKEY_asn1_add_alias ,
.Nm EVP_PKEY_asn1_set_public ,
.Nm EVP_PKEY_asn1_set_private ,
.Nm EVP_PKEY_asn1_set_param ,
.Nm EVP_PKEY_asn1_set_free ,
.Nm EVP_PKEY_asn1_set_ctrl ,
.Nm EVP_PKEY_asn1_set_check ,
.Nm EVP_PKEY_asn1_set_public_check ,
.Nm EVP_PKEY_asn1_set_param_check ,
.Nm EVP_PKEY_asn1_set_security_bits
.Nd manipulating and registering an EVP_PKEY_ASN1_METHOD structure
.Sh SYNOPSIS
.In openssl/evp.h
.Ft EVP_PKEY_ASN1_METHOD *
.Fo EVP_PKEY_asn1_new
.Fa "int id"
.Fa "int flags"
.Fa "const char *pem_str"
.Fa "const char *info"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_copy
.Fa "EVP_PKEY_ASN1_METHOD *dst"
.Fa "const EVP_PKEY_ASN1_METHOD *src"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_free
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fc
.Ft int
.Fo EVP_PKEY_asn1_add0
.Fa "const EVP_PKEY_ASN1_METHOD *ameth"
.Fc
.Ft int
.Fo EVP_PKEY_asn1_add_alias
.Fa "int to"
.Fa "int from"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_public
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "int (*pub_decode)(EVP_PKEY *pk, X509_PUBKEY *pub)"
.Fa "int (*pub_encode)(X509_PUBKEY *pub, const EVP_PKEY *pk)"
.Fa "int (*pub_cmp)(const EVP_PKEY *a, const EVP_PKEY *b)"
.Fa "int (*pub_print)(BIO *out, const EVP_PKEY *pkey, int indent,\
 ASN1_PCTX *pctx)"
.Fa "int (*pkey_size)(const EVP_PKEY *pk)"
.Fa "int (*pkey_bits)(const EVP_PKEY *pk)"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_private
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "int (*priv_decode)(EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf)"
.Fa "int (*priv_encode)(PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk)"
.Fa "int (*priv_print)(BIO *out, const EVP_PKEY *pkey, int indent,\
 ASN1_PCTX *pctx)"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_param
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "int (*param_decode)(EVP_PKEY *pkey, const unsigned char **pder,\
 int derlen)"
.Fa "int (*param_encode)(const EVP_PKEY *pkey, unsigned char **pder)"
.Fa "int (*param_missing)(const EVP_PKEY *pk)"
.Fa "int (*param_copy)(EVP_PKEY *to, const EVP_PKEY *from)"
.Fa "int (*param_cmp)(const EVP_PKEY *a, const EVP_PKEY *b)"
.Fa "int (*param_print)(BIO *out, const EVP_PKEY *pkey, int indent,\
 ASN1_PCTX *pctx)"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_free
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "void (*pkey_free)(EVP_PKEY *pkey)"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_ctrl
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "int (*pkey_ctrl)(EVP_PKEY *pkey, int op, long arg1, void *arg2)"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_check
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "int (*pkey_check)(const EVP_PKEY *pk)"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_public_check
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "int (*pkey_public_check)(const EVP_PKEY *pk)"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_param_check
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "int (*pkey_param_check)(const EVP_PKEY *pk)"
.Fc
.Ft void
.Fo EVP_PKEY_asn1_set_security_bits
.Fa "EVP_PKEY_ASN1_METHOD *ameth"
.Fa "int (*pkey_security_bits)(const EVP_PKEY *pkey)"
.Fc
.Sh DESCRIPTION
.Vt EVP_PKEY_ASN1_METHOD
is a structure which holds a set of ASN.1 conversion, printing and
information methods for a specific public key algorithm.
.Pp
There are two places where the
.Vt EVP_PKEY_ASN1_METHOD
objects are stored: one is a built-in array representing the standard
methods for different algorithms, and the other one is a stack of
user-defined application-specific methods, which can be manipulated by
using
.Fn EVP_PKEY_asn1_add0 .
.Ss Methods
The methods are the underlying implementations of a particular public
key algorithm present by the
.Vt EVP_PKEY
object.
.Bd -unfilled
.Ft int Fn (*pub_decode) "EVP_PKEY *pk" "X509_PUBKEY *pub"
.Ft int Fn (*pub_encode) "X509_PUBKEY *pub" "const EVP_PKEY *pk"
.Ed
.Pp
Decode and encode
.Vt X509_PUBKEY
ASN.1 parameters to and from
.Fa pk .
These methods must return 0 on error and 1 on success.
They are called by
.Xr X509_PUBKEY_get 3
and
.Xr X509_PUBKEY_set 3 .
.Bd -unfilled
.Ft int Fn (*pub_cmp) "const EVP_PKEY *a" "const EVP_PKEY *b"
.Ed
.Pp
Compare two public keys.
This method must return 1 when the keys are equal and 0 otherwise.
It is called by
.Xr EVP_PKEY_cmp 3 .
.Bd -filled
.Ft int Fo (*pub_print)
.Fa "BIO *out"
.Fa "const EVP_PKEY *pkey"
.Fa "int indent"
.Fa "ASN1_PCTX *pctx"
.Fc
.Ed
.Pp
Print a public key in humanly readable text to
.Fa out ,
indented
.Fa indent
spaces.
This method must return 0 on error and 1 on success.
It is called by
.Xr EVP_PKEY_print_public 3 .
.Bd -unfilled
.Ft int Fn (*priv_decode) "EVP_PKEY *pk" "const PKCS8_PRIV_KEY_INFO *p8inf"
.Ft int Fn (*priv_encode) "PKCS8_PRIV_KEY_INFO *p8" "const EVP_PKEY *pk"
.Ed
.Pp
Decode and encode
.Vt PKCS8_PRIV_KEY_INFO
form private key to and from
.Fa pk .
These methods must return 0 on error, 1 on success.
They are called by
.Xr EVP_PKCS82PKEY 3
and
.Xr EVP_PKEY2PKCS8 3 .
.Bd -filled
.Ft int Fo (*priv_print)
.Fa "BIO *out"
.Fa "const EVP_PKEY *pkey"
.Fa "int indent"
.Fa "ASN1_PCTX *pctx"
.Fc
.Ed
.Pp
Print a private key in humanly readable text to
.Fa out ,
indented
.Fa indent
spaces.
This method must return 0 on error and 1 on success.
It is called by
.Xr EVP_PKEY_print_private 3 .
.Bd -unfilled
.Ft int Fn (*pkey_size) "const EVP_PKEY *pk"
.Ed
.Pp
Returns the key size in bytes.
This method is called by
.Xr EVP_PKEY_size 3 .
.Bd -unfilled
.Ft int Fn (*pkey_bits) "const EVP_PKEY *pk"
.Ed
.Pp
Returns the key size in bits.
This method is called by
.Xr EVP_PKEY_bits 3 .
.Bd -filled
.Ft int Fo (*param_decode)
.Fa "EVP_PKEY *pkey"
.Fa "const unsigned char **pder"
.Fa "int derlen"
.Fc
.br
.Ft int Fo (*param_encode)
.Fa "const EVP_PKEY *pkey"
.Fa "unsigned char **pder"
.Fc
.Ed
.Pp
Decode and encode DER formatted parameters to and from
.Fa pk .
These methods must return 0 on error and 1 on success.
They are called by
.Fn PEM_read_bio_Parameters .
.Bd -unfilled
.Ft int Fn (*param_missing) "const EVP_PKEY *pk"
.Ed
.Pp
Return 0 if a key parameter is missing or 1 otherwise.
This method is called by
.Xr EVP_PKEY_missing_parameters 3 .
.Bd -unfilled
.Ft int Fn (*param_copy) "EVP_PKEY *to" "const EVP_PKEY *from"
.Ed
.Pp
Copy key parameters from
.Fa from
to
.Fa to .
This method must return 0 on error and 1 on success.
It is called by
.Xr EVP_PKEY_copy_parameters 3 .
.Bd -unfilled
.Ft int Fn (*param_cmp) "const EVP_PKEY *a" "const EVP_PKEY *b"
.Ed
.Pp
Compare the parameters of the keys
.Fa a
and
.Fa b .
This method must return 1 when the keys are equal, 0 when not equal, and a
negative number on error.
It is called by
.Xr EVP_PKEY_cmp_parameters 3 .
.Bd -filled
.Ft int Fo (*param_print)
.Fa "BIO *out"
.Fa "const EVP_PKEY *pkey"
.Fa "int indent"
.Fa "ASN1_PCTX *pctx"
.Fc
.Ed
.Pp
Print the private key parameters in humanly readable text to
.Fa out ,
indented
.Fa indent
spaces.
This method must return 0 on error and 1 on success.
It is called by
.Xr EVP_PKEY_print_params 3 .
.Bd -unfilled
.Ft void Fn (*pkey_free) "EVP_PKEY *pkey"
.Ed
.Pp
Free the internals of
.Fa pkey .
This method is called by
.Xr EVP_PKEY_free 3 ,
.Xr EVP_PKEY_set_type 3 ,
.Xr EVP_PKEY_set_type_str 3 ,
and
.Xr EVP_PKEY_assign 3 .
.Bd -filled
.Ft int Fo (*pkey_ctrl)
.Fa "EVP_PKEY *pkey"
.Fa "int op"
.Fa "long arg1"
.Fa "void *arg2"
.Fc
.Ed
.Pp
Add extra algorithm specific control.
.Pp
If the
.Fa op
argument is
.Dv ASN1_PKEY_CTRL_DEFAULT_MD_NID ,
the
.Fa pkey_ctrl
method is supposed to write the message digest NID
for public key signature operations with the given
.Fa pkey
to
.Pf * Fa arg2
as documented in the
.Xr EVP_PKEY_get_default_digest_nid 3
manual page.
.Pp
The
.Fa pkey_ctrl
method is also called by
.Fn PKCS7_SIGNER_INFO_set ,
.Fn PKCS7_RECIP_INFO_set ,
and other functions.
.\" TODO:
.\" ASN1_PKEY_CTRL_CMS_ENVELOPE in cms_env.c rsa_ameth.c
.\" ASN1_PKEY_CTRL_CMS_RI_TYPE in cms_env.c dsa_ameth.c ec_ameth.c rsa_ameth.c
.\" ASN1_PKEY_CTRL_CMS_SIGN in cms_sd.c dsa_ameth.c ec_ameth.c rsa_ameth.c
.\" ASN1_PKEY_CTRL_PKCS7_ENCRYPT in pk7_lib.c rsa_ameth.c
.\" ASN1_PKEY_CTRL_PKCS7_SIGN in pk7_lib.c dsa_ameth.c ec_ameth.c rsa_ameth.c
.Bd -unfilled
.Ft int Fn (*pkey_check) "const EVP_PKEY *pk"
.Ft int Fn (*pkey_public_check) "const EVP_PKEY *pk"
.Ft int Fn (*pkey_param_check) "const EVP_PKEY *pk"
.Ed
.Pp
Check the validity of
.Fa pk
for key-pair, public component, and parameters, respectively.
These methods must return 0 for an invalid key or 1 for a valid key.
They are called by
.Xr EVP_PKEY_check 3 ,
.Xr EVP_PKEY_public_check 3 ,
and
.Xr EVP_PKEY_param_check 3 ,
respectively.
.Bd -unfilled
.Ft int Fn (*pkey_security_bits) "const EVP_PKEY *pkey"
.Ed
.Pp
Return the security strength measured in bits of
.Fa pkey .
It is called by
.Xr EVP_PKEY_security_bits 3 .
.Ss Functions
.Fn EVP_PKEY_asn1_new
creates and returns a new
.Vt EVP_PKEY_ASN1_METHOD
object, marks it as dynamically allocated, and associates the given
.Fa id ,
.Fa flags ,
.Fa pem_str
and
.Fa info .
.Fa id
is a NID,
.Fa pem_str
is the PEM type string,
.Fa info
is a descriptive string.
If
.Dv ASN1_PKEY_SIGPARAM_NULL
is set in
.Fa flags ,
the signature algorithm parameters are given the type
.Dv V_ASN1_NULL
by default, otherwise they will be given the type
.Dv V_ASN1_UNDEF
(i.e. the parameter is omitted).
See
.Xr X509_ALGOR_set0 3
for more information.
.Pp
.Fn EVP_PKEY_asn1_copy
copies all function pointers from
.Fa src
to
.Fa dst .
The data in
.Fa dst
that can be set with
.Fn EVP_PKEY_asn1_new
\(em NIDs, flags, and strings \(em
remains unchanged.
This function is not thread safe, it is recommended to only use this when
initializing the application.
.Pp
.Fn EVP_PKEY_asn1_free
frees the dynamically allocated
.Fa ameth
including all memory it refers to.
If
.Fa ameth
is
.Dv NULL
of not marked as dynamically allocated, no action occurs.
.Pp
.Fn EVP_PKEY_asn1_add0
adds
.Fa ameth
to the user defined stack of methods unless another
.Vt EVP_PKEY_ASN1_METHOD
with the same NID is already there.
This function is not thread safe, it is recommended to only use this when
initializing the application.
.Pp
.Fn EVP_PKEY_asn1_add_alias
creates an alias with the NID
.Fa to
for the
.Vt EVP_PKEY_ASN1_METHOD
with NID
.Fa from
unless another
.Vt EVP_PKEY_ASN1_METHOD
with the same NID is already added.
This function is not thread safe, it's recommended to only use this when
initializing the application.
.Pp
.Fn EVP_PKEY_asn1_set_public ,
.Fn EVP_PKEY_asn1_set_private ,
.Fn EVP_PKEY_asn1_set_param ,
.Fn EVP_PKEY_asn1_set_free ,
.Fn EVP_PKEY_asn1_set_ctrl ,
.Fn EVP_PKEY_asn1_set_check ,
.Fn EVP_PKEY_asn1_set_public_check ,
.Fn EVP_PKEY_asn1_set_param_check ,
and
.Fn EVP_PKEY_asn1_set_security_bits
set the diverse methods of the given
.Vt EVP_PKEY_ASN1_METHOD
object.
.Sh RETURN VALUES
.Fn EVP_PKEY_asn1_new
returns a pointer to the new
.Vt EVP_PKEY_ASN1_METHOD
object or
.Dv NULL
if memory allocation fails.
.Pp
.Fn EVP_PKEY_asn1_add0
and
.Fn EVP_PKEY_asn1_add_alias
return 0 on error or 1 on success.
.Sh SEE ALSO
.Xr EVP_PKEY_asn1_get_count 3 ,
.Xr EVP_PKEY_new 3 ,
.Xr X509_PUBKEY_new 3
.Sh HISTORY
.Fn EVP_PKEY_asn1_new ,
.Fn EVP_PKEY_asn1_copy ,
.Fn EVP_PKEY_asn1_free ,
.Fn EVP_PKEY_asn1_add0 ,
.Fn EVP_PKEY_asn1_add_alias ,
.Fn EVP_PKEY_asn1_set_public ,
.Fn EVP_PKEY_asn1_set_private ,
.Fn EVP_PKEY_asn1_set_param ,
.Fn EVP_PKEY_asn1_set_free ,
and
.Fn EVP_PKEY_asn1_set_ctrl
first appeared in OpenSSL 1.0.0 and have been available since
.Ox 4.9 .
.Pp
.Fn EVP_PKEY_asn1_set_check ,
.Fn EVP_PKEY_asn1_set_public_check ,
and
.Fn EVP_PKEY_asn1_set_param_check
first appeared in OpenSSL 1.1.1 and have been available since
.Ox 7.1 .
.Pp
.Fn EVP_PKEY_asn1_set_security_bits
first appeared in OpenSSL 1.1.0 and has been available since
.Ox 7.2 .