.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.3 2018/05/13 15:53:30 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: May 13 2018 $
.Dt EVP_PKEY_ASN1_METHOD 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 Fo (*pub_decode)
.Fa "EVP_PKEY *pk"
.Fa "X509_PUBKEY *pub"
.Fc
.Ft int Fo (*pub_encode)
.Fa "X509_PUBKEY *pub"
.Fa "const EVP_PKEY *pk"
.Fc
.Ft int Fo (*pub_cmp)
.Fa "const EVP_PKEY *a"
.Fa "const EVP_PKEY *b"
.Fc
.Ft int Fo (*pub_print)
.Fa "BIO *out"
.Fa "const EVP_PKEY *pkey"
.Fa "int indent"
.Fa "ASN1_PCTX *pctx"
.Fc
.Ed
.Pp
The
.Fn pub_decode
and
.Fn pub_encode
methods are called to decode and encode
.Vt X509_PUBKEY
ASN.1 parameters to and from
.Fa pk .
They must return 0 on error and 1 on success.
They are called by
.Xr X509_PUBKEY_get 3
and
.Xr X509_PUBKEY_set 3 .
.Pp
The
.Fn pub_cmp
method is called when two public keys are compared.
It must return 1 when the keys are equal and 0 otherwise.
It is called by
.Xr EVP_PKEY_cmp 3 .
.Pp
The
.Fn pub_print
method is called to print a public key in humanly readable text to
.Fa out ,
indented
.Fa indent
spaces.
It must return 0 on error and 1 on success.
It is called by
.Xr EVP_PKEY_print_public 3 .
.Bd -unfilled
.Ft int Fo (*priv_decode)
.Fa "EVP_PKEY *pk"
.Fa "const PKCS8_PRIV_KEY_INFO *p8inf"
.Fc
.Ft int Fo (*priv_encode)
.Fa "PKCS8_PRIV_KEY_INFO *p8"
.Fa "const EVP_PKEY *pk"
.Fc
.Ft int Fo (*priv_print)
.Fa "BIO *out"
.Fa "const EVP_PKEY *pkey"
.Fa "int indent"
.Fa "ASN1_PCTX *pctx"
.Fc
.Ed
.Pp
The
.Fn priv_decode
and
.Fn priv_encode
methods are called to decode and encode
.Vt PKCS8_PRIV_KEY_INFO
form private key to and from
.Fa pk .
They must return 0 on error, 1 on success.
They are called by
.Fn EVP_PKCS82PKEY
and
.Fn EVP_PKEY2PKCS8 .
.Pp
The
.Fn priv_print
method is called to print a private key in humanly readable text to
.Fa out ,
indented
.Fa indent
spaces.
It 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"
.Ft int Fn (*pkey_bits) "const EVP_PKEY *pk";
.Ed
.Pp
The
.Fn pkey_size
method returns the key size in bytes.
It is called by
.Xr EVP_PKEY_size 3 .
.Pp
The
.Fn pkey_bits
method returns the key size in bits.
It is called by
.Xr EVP_PKEY_bits 3 .
.Bd -unfilled
.Ft int Fo (*param_decode)
.Fa "EVP_PKEY *pkey"
.Fa "const unsigned char **pder"
.Fa "int derlen"
.Fc
.Ft int Fo (*param_encode)
.Fa "const EVP_PKEY *pkey"
.Fa "unsigned char **pder"
.Fc
.Ft int Fo (*param_missing)
.Fa "const EVP_PKEY *pk"
.Fc
.Ft int Fo (*param_copy)
.Fa "EVP_PKEY *to"
.Fa "const EVP_PKEY *from"
.Fc
.Ft int Fo (*param_cmp)
.Fa "const EVP_PKEY *a"
.Fa "const EVP_PKEY *b"
.Fc
.Ft int Fo (*param_print)
.Fa "BIO *out"
.Fa "const EVP_PKEY *pkey"
.Fa "int indent"
.Fa "ASN1_PCTX *pctx"
.Fc
.Ed
.Pp
The
.Fn param_decode
and
.Fn param_encode
methods are called to decode and encode DER formatted parameters to and from
.Fa pk .
They must return 0 on error and 1 on success.
They are called by
.Fn PEM_read_bio_Parameters .
.Pp
The
.Fn param_missing
method returns 0 if a key parameter is missing or otherwise 1.
It is called by
.Xr EVP_PKEY_missing_parameters 3 .
.Pp
The
.Fn param_copy
method copies key parameters from
.Fa from
to
.Fa to .
It must return 0 on error and 1 on success.
It is called by
.Xr EVP_PKEY_copy_parameters 3 .
.Pp
The
.Fn param_cmp
method compares the parameters of the keys
.Fa a
and
.Fa b .
It 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 .
.Pp
The
.Fn param_print
method prints the private key parameters in humanly readable text to
.Fa out ,
indented
.Fa indent
spaces.
It 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
The
.Fn pkey_free
method helps freeing the internals of
.Fa pkey .
It is called by
.Xr EVP_PKEY_free 3 ,
.Fn EVP_PKEY_set_type ,
.Fn EVP_PKEY_set_type_str ,
and
.Fn EVP_PKEY_assign .
.Bd -unfilled
.Ft int Fo (*pkey_ctrl)
.Fa "EVP_PKEY *pkey"
.Fa "int op"
.Fa "long arg1"
.Fa "void *arg2"
.Fc
.Ed
.Pp
The
.Fn pkey_ctrl
method adds extra algorithm specific control.
It 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 HISTORY
These functions first appeared in OpenSSL 1.0.0
and have been available since
.Ox 4.9 .