--- /dev/null
+.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.1 2018/02/14 02:15:46 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: February 14 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's called by
+.Fn EVP_PKEY_bits .
+.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.
projects / openbsd / commitdiff