.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.7 2021/11/06 15:00:25 schwarze Exp $
.\" selective merge up to:
.\" OpenSSL man3/EVP_PKEY_ASN1_METHOD b0004708 Nov 1 00:45:24 2017 +0800
.\"
.\" This file was written by Richard Levitte <levitte@openssl.org>
.\" 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: November 6 2021 $
.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
.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
.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 ,
.Fn EVP_PKEY_set_type_str ,
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.
This method is called by
.Xr EVP_PKEY_get_default_digest_nid 3 ,
.Fn PKCS7_SIGNER_INFO_set ,
.Fn PKCS7_RECIP_INFO_set ,
and other functions.
.Ss Functions
.Fn EVP_PKEY_asn1_new
creates and returns a new
.Vt EVP_PKEY_ASN1_METHOD
object, 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 an
.Vt EVP_PKEY_ASN1_METHOD
object from
.Fa src
to
.Fa dst .
This function is not thread safe, it is recommended to only use this when
initializing the application.
.Pp
.Fn EVP_PKEY_asn1_free
frees an existing
.Vt EVP_PKEY_ASN1_METHOD
pointed by
.Fa ameth .
.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 ,
and
.Fn EVP_PKEY_asn1_set_ctrl
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 an
.Vt EVP_PKEY_ASN1_METHOD
object or
.Dv NULL
on error.
.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
These functions first appeared in OpenSSL 1.0.0
and have been available since
.Ox 4.9 .