[thirdparty/openssl.git] / doc / man3 / EVP_PKEY_ASN1_METHOD.pod

=pod

=head1 NAME

EVP_PKEY_ASN1_METHOD,
EVP_PKEY_asn1_new,
EVP_PKEY_asn1_copy,
EVP_PKEY_asn1_free,
EVP_PKEY_asn1_add0,
EVP_PKEY_asn1_add_alias,
EVP_PKEY_asn1_set_public,
EVP_PKEY_asn1_set_private,
EVP_PKEY_asn1_set_param,
EVP_PKEY_asn1_set_free,
EVP_PKEY_asn1_set_ctrl,
EVP_PKEY_asn1_set_item,
EVP_PKEY_asn1_set_siginf,
EVP_PKEY_asn1_set_check,
EVP_PKEY_asn1_set_public_check,
EVP_PKEY_asn1_set_param_check,
EVP_PKEY_asn1_set_security_bits,
EVP_PKEY_asn1_set_set_priv_key,
EVP_PKEY_asn1_set_set_pub_key,
EVP_PKEY_get0_asn1
- manipulating and registering EVP_PKEY_ASN1_METHOD structure

=head1 SYNOPSIS

 #include <openssl/evp.h>

 typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;

 EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags,
                                         const char *pem_str,
                                         const char *info);
 void EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst,
                         const EVP_PKEY_ASN1_METHOD *src);
 void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth);
 int EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth);
 int EVP_PKEY_asn1_add_alias(int to, int from);

 void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,
                               int (*pub_decode) (EVP_PKEY *pk,
                                                  X509_PUBKEY *pub),
                               int (*pub_encode) (X509_PUBKEY *pub,
                                                  const EVP_PKEY *pk),
                               int (*pub_cmp) (const EVP_PKEY *a,
                                               const EVP_PKEY *b),
                               int (*pub_print) (BIO *out,
                                                 const EVP_PKEY *pkey,
                                                 int indent, ASN1_PCTX *pctx),
                               int (*pkey_size) (const EVP_PKEY *pk),
                               int (*pkey_bits) (const EVP_PKEY *pk));
 void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth,
                                int (*priv_decode) (EVP_PKEY *pk,
                                                    const PKCS8_PRIV_KEY_INFO
                                                    *p8inf),
                                int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8,
                                                    const EVP_PKEY *pk),
                                int (*priv_print) (BIO *out,
                                                   const EVP_PKEY *pkey,
                                                   int indent,
                                                   ASN1_PCTX *pctx));
 void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth,
                              int (*param_decode) (EVP_PKEY *pkey,
                                                   const unsigned char **pder,
                                                   int derlen),
                              int (*param_encode) (const EVP_PKEY *pkey,
                                                   unsigned char **pder),
                              int (*param_missing) (const EVP_PKEY *pk),
                              int (*param_copy) (EVP_PKEY *to,
                                                 const EVP_PKEY *from),
                              int (*param_cmp) (const EVP_PKEY *a,
                                                const EVP_PKEY *b),
                              int (*param_print) (BIO *out,
                                                  const EVP_PKEY *pkey,
                                                  int indent,
                                                  ASN1_PCTX *pctx));

 void EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth,
                             void (*pkey_free) (EVP_PKEY *pkey));
 void EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth,
                             int (*pkey_ctrl) (EVP_PKEY *pkey, int op,
                                               long arg1, void *arg2));
 void EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth,
                             int (*item_verify) (EVP_MD_CTX *ctx,
                                                 const ASN1_ITEM *it,
                                                 void *asn,
                                                 X509_ALGOR *a,
                                                 ASN1_BIT_STRING *sig,
                                                 EVP_PKEY *pkey),
                             int (*item_sign) (EVP_MD_CTX *ctx,
                                               const ASN1_ITEM *it,
                                               void *asn,
                                               X509_ALGOR *alg1,
                                               X509_ALGOR *alg2,
                                               ASN1_BIT_STRING *sig));

 void EVP_PKEY_asn1_set_siginf(EVP_PKEY_ASN1_METHOD *ameth,
                               int (*siginf_set) (X509_SIG_INFO *siginf,
                                                  const X509_ALGOR *alg,
                                                  const ASN1_STRING *sig));

 void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,
                              int (*pkey_check) (const EVP_PKEY *pk));

 void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,
                                     int (*pkey_pub_check) (const EVP_PKEY *pk));

 void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,
                                    int (*pkey_param_check) (const EVP_PKEY *pk));

 void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
                                      int (*pkey_security_bits) (const EVP_PKEY
                                                                 *pk));

 void EVP_PKEY_asn1_set_set_priv_key(EVP_PKEY_ASN1_METHOD *ameth,
                                     int (*set_priv_key) (EVP_PKEY *pk,
                                                          const unsigned char
                                                             *priv,
                                                          size_t len));

 void EVP_PKEY_asn1_set_set_pub_key(EVP_PKEY_ASN1_METHOD *ameth,
                                    int (*set_pub_key) (EVP_PKEY *pk,
                                                        const unsigned char *pub,
                                                        size_t len));

 const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);

=head1 DESCRIPTION

B<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.

There are two places where the B<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
L<EVP_PKEY_asn1_add0(3)>.

=head2 Methods

The methods are the underlying implementations of a particular public
key algorithm present by the B<EVP_PKEY> object.

 int (*pub_decode) (EVP_PKEY *pk, X509_PUBKEY *pub);
 int (*pub_encode) (X509_PUBKEY *pub, const EVP_PKEY *pk);
 int (*pub_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);
 int (*pub_print) (BIO *out, const EVP_PKEY *pkey, int indent,
                   ASN1_PCTX *pctx);

The pub_decode() and pub_encode() methods are called to decode /
encode B<X509_PUBKEY> ASN.1 parameters to / from B<pk>.
They MUST return 0 on error, 1 on success.
They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>.

The pub_cmp() method is called when two public keys are to be
compared.
It MUST return 1 when the keys are equal, 0 otherwise.
It's called by L<EVP_PKEY_cmp(3)>.

The pub_print() method is called to print a public key in humanly
readable text to B<out>, indented B<indent> spaces.
It MUST return 0 on error, 1 on success.
It's called by L<EVP_PKEY_print_public(3)>.

 int (*priv_decode) (EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf);
 int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk);
 int (*priv_print) (BIO *out, const EVP_PKEY *pkey, int indent,
                    ASN1_PCTX *pctx);

The priv_decode() and priv_encode() methods are called to decode /
encode B<PKCS8_PRIV_KEY_INFO> form private key to / from B<pk>.
They MUST return 0 on error, 1 on success.
They're called by L<EVP_PKCS82PKEY(3)> and L<EVP_PKEY2PKCS8(3)>.

The priv_print() method is called to print a private key in humanly
readable text to B<out>, indented B<indent> spaces.
It MUST return 0 on error, 1 on success.
It's called by L<EVP_PKEY_print_private(3)>.

 int (*pkey_size) (const EVP_PKEY *pk);
 int (*pkey_bits) (const EVP_PKEY *pk);
 int (*pkey_security_bits) (const EVP_PKEY *pk);

The pkey_size() method returns the key size in bytes.
It's called by L<EVP_PKEY_size(3)>.

The pkey_bits() method returns the key size in bits.
It's called by L<EVP_PKEY_bits(3)>.

 int (*param_decode) (EVP_PKEY *pkey,
                      const unsigned char **pder, int derlen);
 int (*param_encode) (const EVP_PKEY *pkey, unsigned char **pder);
 int (*param_missing) (const EVP_PKEY *pk);
 int (*param_copy) (EVP_PKEY *to, const EVP_PKEY *from);
 int (*param_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);
 int (*param_print) (BIO *out, const EVP_PKEY *pkey, int indent,
                     ASN1_PCTX *pctx);

The param_decode() and param_encode() methods are called to decode /
encode DER formatted parameters to / from B<pk>.
They MUST return 0 on error, 1 on success.
They're called by L<PEM_read_bio_Parameters(3)> and the B<file:>
L<OSSL_STORE_LOADER(3)>.

The param_missing() method returns 0 if a key parameter is missing,
otherwise 1.
It's called by L<EVP_PKEY_missing_parameters(3)>.

The param_copy() method copies key parameters from B<from> to B<to>.
It MUST return 0 on error, 1 on success.
It's called by L<EVP_PKEY_copy_parameters(3)>.

The param_cmp() method compares the parameters of keys B<a> and B<b>.
It MUST return 1 when the keys are equal, 0 when not equal, or a
negative number on error.
It's called by L<EVP_PKEY_cmp_parameters(3)>.

The param_print() method prints the private key parameters in humanly
readable text to B<out>, indented B<indent> spaces.
It MUST return 0 on error, 1 on success.
It's called by L<EVP_PKEY_print_params(3)>.

 int (*sig_print) (BIO *out,
                   const X509_ALGOR *sigalg, const ASN1_STRING *sig,
                   int indent, ASN1_PCTX *pctx);

The sig_print() method prints a signature in humanly readable text to
B<out>, indented B<indent> spaces.
B<sigalg> contains the exact signature algorithm.
If the signature in B<sig> doesn't correspond to what this method
expects, X509_signature_dump() must be used as a last resort.
It MUST return 0 on error, 1 on success.
It's called by L<X509_signature_print(3)>.

 void (*pkey_free) (EVP_PKEY *pkey);

The pkey_free() method helps freeing the internals of B<pkey>.
It's called by L<EVP_PKEY_free(3)>, L<EVP_PKEY_set_type(3)>,
L<EVP_PKEY_set_type_str(3)>, and L<EVP_PKEY_assign(3)>.

 int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);

The pkey_ctrl() method adds extra algorithm specific control.
It's called by L<EVP_PKEY_get_default_digest_nid(3)>,
L<EVP_PKEY_set1_tls_encodedpoint(3)>,
L<EVP_PKEY_get1_tls_encodedpoint(3)>, L<PKCS7_SIGNER_INFO_set(3)>,
L<PKCS7_RECIP_INFO_set(3)>, ...

 int (*old_priv_decode) (EVP_PKEY *pkey,
                         const unsigned char **pder, int derlen);
 int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder);

The old_priv_decode() and old_priv_encode() methods decode / encode
they private key B<pkey> from / to a DER formatted array.
These are exclusively used to help decoding / encoding older (pre
PKCS#8) PEM formatted encrypted private keys.
old_priv_decode() MUST return 0 on error, 1 on success.
old_priv_encode() MUST the return same kind of values as
i2d_PrivateKey().
They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>.

 int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
                     X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey);
 int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
                   X509_ALGOR *alg1, X509_ALGOR *alg2,
                   ASN1_BIT_STRING *sig);

The item_sign() and  item_verify() methods make it possible to have
algorithm specific signatures and verification of them.

item_sign() MUST return one of:

=over 4

=item <=0

error

=item Z<>1

item_sign() did everything, OpenSSL internals just needs to pass the
signature length back.

=item Z<>2

item_sign() did nothing, OpenSSL internal standard routines are
expected to continue with the default signature production.

=item Z<>3

item_sign() set the algorithm identifier B<algor1> and B<algor2>,
OpenSSL internals should just sign using those algorithms.

=back

item_verify() MUST return one of:

=over 4

=item <=0

error

=item Z<>1

item_sign() did everything, OpenSSL internals just needs to pass the
signature length back.

=item Z<>2

item_sign() did nothing, OpenSSL internal standard routines are
expected to continue with the default signature production.

=back

item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and
L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>,
L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ...

 int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
                    const ASN1_STRING *sig);

The siginf_set() method is used to set custom B<X509_SIG_INFO>
parameters.
It MUST return 0 on error, or 1 on success.
It's called as part of L<X509_check_purpose(3)>, L<X509_check_ca(3)>
and L<X509_check_issued(3)>.

 int (*pkey_check) (const EVP_PKEY *pk);
 int (*pkey_public_check) (const EVP_PKEY *pk);
 int (*pkey_param_check) (const EVP_PKEY *pk);

The pkey_check(), pkey_public_check() and pkey_param_check() methods are used
to check the validity of B<pk> for key-pair, public component and parameters,
respectively.
They MUST return 0 for an invalid key, or 1 for a valid key.
They are called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
L<EVP_PKEY_param_check(3)> respectively.

 int (*set_priv_key) (EVP_PKEY *pk, const unsigned char *priv, size_t len);
 int (*set_pub_key) (EVP_PKEY *pk, const unsigned char *pub, size_t len);

The set_priv_key() and set_pub_key() methods are used to set the raw private and
public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success.
They are called by L<EVP_PKEY_new_raw_private_key(3)>, and
L<EVP_PKEY_new_raw_public_key(3)> respectively.

=head2 Functions

EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD>
object, and associates the given B<id>, B<flags>, B<pem_str> and
B<info>.
B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a
descriptive string.
The following B<flags> are supported:

 ASN1_PKEY_SIGPARAM_NULL

If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm
parameters are given the type B<V_ASN1_NULL> by default, otherwise
they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is
omitted).
See L<X509_ALGOR_set0(3)> for more information.

EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from
B<src> to B<dst>.
This function is not thread safe, it's recommended to only use this
when initializing the application.

EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
by B<ameth>.

EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of
methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is
already there.
This function is not thread safe, it's recommended to only use this
when initializing the application.

EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the
B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another
B<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.

EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(),
EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key() and
EVP_PKEY_asn1_set_set_pub_key() set the diverse methods of the given
B<EVP_PKEY_ASN1_METHOD> object.

EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated
with the key B<pkey>.

=head1 RETURN VALUES

EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
B<EVP_PKEY_ASN1_METHOD> object otherwise.

EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
or 1 on success.

EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
B<EVP_PKEY_ASN1_METHOD> object otherwise.

=head1 COPYRIGHT

Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
751148e2 RL	1	=pod
	2
	3	=head1 NAME
	4
	5	EVP_PKEY_ASN1_METHOD,
287f5551 RL	6	EVP_PKEY_asn1_new,
	7	EVP_PKEY_asn1_copy,
	8	EVP_PKEY_asn1_free,
	9	EVP_PKEY_asn1_add0,
	10	EVP_PKEY_asn1_add_alias,
	11	EVP_PKEY_asn1_set_public,
	12	EVP_PKEY_asn1_set_private,
	13	EVP_PKEY_asn1_set_param,
	14	EVP_PKEY_asn1_set_free,
	15	EVP_PKEY_asn1_set_ctrl,
	16	EVP_PKEY_asn1_set_item,
	17	EVP_PKEY_asn1_set_siginf,
	18	EVP_PKEY_asn1_set_check,
b0004708 PY	19	EVP_PKEY_asn1_set_public_check,
b0004708 PY	20	EVP_PKEY_asn1_set_param_check,
287f5551	21	EVP_PKEY_asn1_set_security_bits,
e8f9f08f MC	22	EVP_PKEY_asn1_set_set_priv_key,
e8f9f08f MC	23	EVP_PKEY_asn1_set_set_pub_key,
287f5551	24	EVP_PKEY_get0_asn1
751148e2 RL	25	- manipulating and registering EVP_PKEY_ASN1_METHOD structure
	26
	27	=head1 SYNOPSIS
	28
	29	#include <openssl/evp.h>
	30
	31	typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;
	32
	33	EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags,
	34	const char *pem_str,
	35	const char *info);
	36	void EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst,
	37	const EVP_PKEY_ASN1_METHOD *src);
	38	void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth);
	39	int EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth);
	40	int EVP_PKEY_asn1_add_alias(int to, int from);
	41
	42	void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,
	43	int (pub_decode) (EVP_PKEY pk,
	44	X509_PUBKEY *pub),
	45	int (pub_encode) (X509_PUBKEY pub,
	46	const EVP_PKEY *pk),
	47	int (pub_cmp) (const EVP_PKEY a,
	48	const EVP_PKEY *b),
	49	int (pub_print) (BIO out,
	50	const EVP_PKEY *pkey,
	51	int indent, ASN1_PCTX *pctx),
	52	int (pkey_size) (const EVP_PKEY pk),
	53	int (pkey_bits) (const EVP_PKEY pk));
	54	void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth,
	55	int (priv_decode) (EVP_PKEY pk,
	56	const PKCS8_PRIV_KEY_INFO
	57	*p8inf),
	58	int (priv_encode) (PKCS8_PRIV_KEY_INFO p8,
	59	const EVP_PKEY *pk),
	60	int (priv_print) (BIO out,
	61	const EVP_PKEY *pkey,
	62	int indent,
	63	ASN1_PCTX *pctx));
	64	void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth,
	65	int (param_decode) (EVP_PKEY pkey,
	66	const unsigned char **pder,
	67	int derlen),
	68	int (param_encode) (const EVP_PKEY pkey,
	69	unsigned char **pder),
	70	int (param_missing) (const EVP_PKEY pk),
	71	int (param_copy) (EVP_PKEY to,
	72	const EVP_PKEY *from),
	73	int (param_cmp) (const EVP_PKEY a,
	74	const EVP_PKEY *b),
	75	int (param_print) (BIO out,
	76	const EVP_PKEY *pkey,
	77	int indent,
	78	ASN1_PCTX *pctx));
	79
	80	void EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth,
	81	void (pkey_free) (EVP_PKEY pkey));
	82	void EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth,
	83	int (pkey_ctrl) (EVP_PKEY pkey, int op,
	84	long arg1, void *arg2));
	85	void EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth,
	86	int (item_verify) (EVP_MD_CTX ctx,
	87	const ASN1_ITEM *it,
	88	void *asn,
89	X509_ALGOR *a,
90	ASN1_BIT_STRING *sig,
91	EVP_PKEY *pkey),
92	int (item_sign) (EVP_MD_CTX ctx,
93	const ASN1_ITEM *it,
94	void *asn,
95	X509_ALGOR *alg1,
96	X509_ALGOR *alg2,
97	ASN1_BIT_STRING *sig));
98
99	void EVP_PKEY_asn1_set_siginf(EVP_PKEY_ASN1_METHOD *ameth,
100	int (siginf_set) (X509_SIG_INFO siginf,
101	const X509_ALGOR *alg,
102	const ASN1_STRING *sig));
103
104	void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,
105	int (pkey_check) (const EVP_PKEY pk));
106
b0004708 PY	107	void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,
	108	int (pkey_pub_check) (const EVP_PKEY pk));
	109
	110	void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,
	111	int (pkey_param_check) (const EVP_PKEY pk));
	112
751148e2 RL	113	void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
	114	int (*pkey_security_bits) (const EVP_PKEY
	115	*pk));
	116
e8f9f08f MC	117	void EVP_PKEY_asn1_set_set_priv_key(EVP_PKEY_ASN1_METHOD *ameth,
	118	int (set_priv_key) (EVP_PKEY pk,
	119	const unsigned char
	120	*priv,
	121	size_t len));
	122
	123	void EVP_PKEY_asn1_set_set_pub_key(EVP_PKEY_ASN1_METHOD *ameth,
	124	int (set_pub_key) (EVP_PKEY pk,
	125	const unsigned char *pub,
	126	size_t len));
	127
751148e2 RL	128	const EVP_PKEY_ASN1_METHOD EVP_PKEY_get0_asn1(const EVP_PKEY pkey);
	129
	130	=head1 DESCRIPTION
	131
	132	B<EVP_PKEY_ASN1_METHOD> is a structure which holds a set of ASN.1
	133	conversion, printing and information methods for a specific public key
	134	algorithm.
	135
	136	There are two places where the B<EVP_PKEY_ASN1_METHOD> objects are
	137	stored: one is a built-in array representing the standard methods for
	138	different algorithms, and the other one is a stack of user-defined
	139	application-specific methods, which can be manipulated by using
	140	L<EVP_PKEY_asn1_add0(3)>.
	141
	142	=head2 Methods
	143
	144	The methods are the underlying implementations of a particular public
	145	key algorithm present by the B<EVP_PKEY> object.
	146
	147	int (pub_decode) (EVP_PKEY pk, X509_PUBKEY *pub);
	148	int (pub_encode) (X509_PUBKEY pub, const EVP_PKEY *pk);
	149	int (pub_cmp) (const EVP_PKEY a, const EVP_PKEY *b);
	150	int (pub_print) (BIO out, const EVP_PKEY *pkey, int indent,
	151	ASN1_PCTX *pctx);
	152
	153	The pub_decode() and pub_encode() methods are called to decode /
	154	encode B<X509_PUBKEY> ASN.1 parameters to / from B<pk>.
	155	They MUST return 0 on error, 1 on success.
	156	They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>.
	157
	158	The pub_cmp() method is called when two public keys are to be
	159	compared.
	160	It MUST return 1 when the keys are equal, 0 otherwise.
	161	It's called by L<EVP_PKEY_cmp(3)>.
	162
	163	The pub_print() method is called to print a public key in humanly
	164	readable text to B<out>, indented B<indent> spaces.
	165	It MUST return 0 on error, 1 on success.
	166	It's called by L<EVP_PKEY_print_public(3)>.
	167
	168	int (priv_decode) (EVP_PKEY pk, const PKCS8_PRIV_KEY_INFO *p8inf);
	169	int (priv_encode) (PKCS8_PRIV_KEY_INFO p8, const EVP_PKEY *pk);
	170	int (priv_print) (BIO out, const EVP_PKEY *pkey, int indent,
	171	ASN1_PCTX *pctx);
	172
	173	The priv_decode() and priv_encode() methods are called to decode /
	174	encode B<PKCS8_PRIV_KEY_INFO> form private key to / from B<pk>.
	175	They MUST return 0 on error, 1 on success.
	176	They're called by L<EVP_PKCS82PKEY(3)> and L<EVP_PKEY2PKCS8(3)>.
	177
	178	The priv_print() method is called to print a private key in humanly
	179	readable text to B<out>, indented B<indent> spaces.
	180	It MUST return 0 on error, 1 on success.
	181	It's called by L<EVP_PKEY_print_private(3)>.
	182
	183	int (pkey_size) (const EVP_PKEY pk);
	184	int (pkey_bits) (const EVP_PKEY pk);
	185	int (pkey_security_bits) (const EVP_PKEY pk);
	186
	187	The pkey_size() method returns the key size in bytes.
	188	It's called by L<EVP_PKEY_size(3)>.
	189
	190	The pkey_bits() method returns the key size in bits.
	191	It's called by L<EVP_PKEY_bits(3)>.
192
193	int (param_decode) (EVP_PKEY pkey,
194	const unsigned char **pder, int derlen);
195	int (param_encode) (const EVP_PKEY pkey, unsigned char **pder);
196	int (param_missing) (const EVP_PKEY pk);
197	int (param_copy) (EVP_PKEY to, const EVP_PKEY *from);
198	int (param_cmp) (const EVP_PKEY a, const EVP_PKEY *b);
199	int (param_print) (BIO out, const EVP_PKEY *pkey, int indent,
200	ASN1_PCTX *pctx);
201
202	The param_decode() and param_encode() methods are called to decode /
203	encode DER formatted parameters to / from B<pk>.
204	They MUST return 0 on error, 1 on success.
205	They're called by L<PEM_read_bio_Parameters(3)> and the B<file:>
206	L<OSSL_STORE_LOADER(3)>.
207
208	The param_missing() method returns 0 if a key parameter is missing,
209	otherwise 1.
210	It's called by L<EVP_PKEY_missing_parameters(3)>.
211
212	The param_copy() method copies key parameters from B<from> to B<to>.
213	It MUST return 0 on error, 1 on success.
214	It's called by L<EVP_PKEY_copy_parameters(3)>.
215
216	The param_cmp() method compares the parameters of keys B<a> and B<b>.
217	It MUST return 1 when the keys are equal, 0 when not equal, or a
218	negative number on error.
219	It's called by L<EVP_PKEY_cmp_parameters(3)>.
220
221	The param_print() method prints the private key parameters in humanly
222	readable text to B<out>, indented B<indent> spaces.
223	It MUST return 0 on error, 1 on success.
224	It's called by L<EVP_PKEY_print_params(3)>.
225
226	int (sig_print) (BIO out,
227	const X509_ALGOR sigalg, const ASN1_STRING sig,
228	int indent, ASN1_PCTX *pctx);
229
230	The sig_print() method prints a signature in humanly readable text to
231	B<out>, indented B<indent> spaces.
232	B<sigalg> contains the exact signature algorithm.
233	If the signature in B<sig> doesn't correspond to what this method
234	expects, X509_signature_dump() must be used as a last resort.
235	It MUST return 0 on error, 1 on success.
236	It's called by L<X509_signature_print(3)>.
237
238	void (pkey_free) (EVP_PKEY pkey);
239
240	The pkey_free() method helps freeing the internals of B<pkey>.
241	It's called by L<EVP_PKEY_free(3)>, L<EVP_PKEY_set_type(3)>,
242	L<EVP_PKEY_set_type_str(3)>, and L<EVP_PKEY_assign(3)>.
243
244	int (pkey_ctrl) (EVP_PKEY pkey, int op, long arg1, void *arg2);
245
246	The pkey_ctrl() method adds extra algorithm specific control.
247	It's called by L<EVP_PKEY_get_default_digest_nid(3)>,
248	L<EVP_PKEY_set1_tls_encodedpoint(3)>,
249	L<EVP_PKEY_get1_tls_encodedpoint(3)>, L<PKCS7_SIGNER_INFO_set(3)>,
250	L<PKCS7_RECIP_INFO_set(3)>, ...
251
252	int (old_priv_decode) (EVP_PKEY pkey,
253	const unsigned char **pder, int derlen);
254	int (old_priv_encode) (const EVP_PKEY pkey, unsigned char **pder);
255
256	The old_priv_decode() and old_priv_encode() methods decode / encode
257	they private key B<pkey> from / to a DER formatted array.
258	These are exclusively used to help decoding / encoding older (pre
259	PKCS#8) PEM formatted encrypted private keys.
260	old_priv_decode() MUST return 0 on error, 1 on success.
261	old_priv_encode() MUST the return same kind of values as
262	i2d_PrivateKey().
263	They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>.
264
265	int (item_verify) (EVP_MD_CTX ctx, const ASN1_ITEM it, void asn,
266	X509_ALGOR a, ASN1_BIT_STRING sig, EVP_PKEY *pkey);
267	int (item_sign) (EVP_MD_CTX ctx, const ASN1_ITEM it, void asn,
268	X509_ALGOR alg1, X509_ALGOR alg2,
269	ASN1_BIT_STRING *sig);
270
271	The item_sign() and item_verify() methods make it possible to have
272	algorithm specific signatures and verification of them.
273
274	item_sign() MUST return one of:
275
276	=over 4
277
278	=item <=0
279
280	error
281
287f5551	282	=item Z<>1
751148e2 RL	283
	284	item_sign() did everything, OpenSSL internals just needs to pass the
	285	signature length back.
	286
287f5551	287	=item Z<>2
751148e2 RL	288
	289	item_sign() did nothing, OpenSSL internal standard routines are
	290	expected to continue with the default signature production.
	291
287f5551	292	=item Z<>3
751148e2 RL	293
	294	item_sign() set the algorithm identifier B<algor1> and B<algor2>,
	295	OpenSSL internals should just sign using those algorithms.
	296
	297	=back
	298
	299	item_verify() MUST return one of:
	300
	301	=over 4
	302
	303	=item <=0
	304
	305	error
	306
287f5551	307	=item Z<>1
751148e2 RL	308
	309	item_sign() did everything, OpenSSL internals just needs to pass the
	310	signature length back.
	311
287f5551	312	=item Z<>2
751148e2 RL	313
	314	item_sign() did nothing, OpenSSL internal standard routines are
	315	expected to continue with the default signature production.
	316
	317	=back
	318
	319	item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and
	320	L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>,
	321	L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ...
	322
	323	int (siginf_set) (X509_SIG_INFO siginf, const X509_ALGOR *alg,
	324	const ASN1_STRING *sig);
	325
	326	The siginf_set() method is used to set custom B<X509_SIG_INFO>
	327	parameters.
	328	It MUST return 0 on error, or 1 on success.
	329	It's called as part of L<X509_check_purpose(3)>, L<X509_check_ca(3)>
	330	and L<X509_check_issued(3)>.
	331
	332	int (pkey_check) (const EVP_PKEY pk);
b0004708 PY	333	int (pkey_public_check) (const EVP_PKEY pk);
b0004708 PY	334	int (pkey_param_check) (const EVP_PKEY pk);
751148e2	335
b0004708 PY	336	The pkey_check(), pkey_public_check() and pkey_param_check() methods are used
	337	to check the validity of B<pk> for key-pair, public component and parameters,
	338	respectively.
	339	They MUST return 0 for an invalid key, or 1 for a valid key.
	340	They are called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
	341	L<EVP_PKEY_param_check(3)> respectively.
751148e2	342
e8f9f08f MC	343	int (set_priv_key) (EVP_PKEY pk, const unsigned char *priv, size_t len);
	344	int (set_pub_key) (EVP_PKEY pk, const unsigned char *pub, size_t len);
	345
	346	The set_priv_key() and set_pub_key() methods are used to set the raw private and
	347	public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success.
f929439f MC	348	They are called by L<EVP_PKEY_new_raw_private_key(3)>, and
f929439f MC	349	L<EVP_PKEY_new_raw_public_key(3)> respectively.
e8f9f08f	350
751148e2 RL	351	=head2 Functions
	352
	353	EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD>
	354	object, and associates the given B<id>, B<flags>, B<pem_str> and
	355	B<info>.
	356	B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a
	357	descriptive string.
	358	The following B<flags> are supported:
	359
	360	ASN1_PKEY_SIGPARAM_NULL
	361
	362	If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm
	363	parameters are given the type B<V_ASN1_NULL> by default, otherwise
	364	they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is
	365	omitted).
	366	See L<X509_ALGOR_set0(3)> for more information.
	367
	368	EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from
	369	B<src> to B<dst>.
	370	This function is not thread safe, it's recommended to only use this
	371	when initializing the application.
	372
	373	EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
	374	by B<ameth>.
	375
	376	EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of
	377	methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is
	378	already there.
	379	This function is not thread safe, it's recommended to only use this
	380	when initializing the application.
	381
	382	EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the
	383	B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another
	384	B<EVP_PKEY_ASN1_METHOD> with the same NID is already added.
	385	This function is not thread safe, it's recommended to only use this
	386	when initializing the application.
	387
	388	EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
	389	EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
	390	EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
b0004708	391	EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
e8f9f08f MC	392	EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(),
	393	EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key() and
	394	EVP_PKEY_asn1_set_set_pub_key() set the diverse methods of the given
751148e2 RL	395	B<EVP_PKEY_ASN1_METHOD> object.
	396
	397	EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated
	398	with the key B<pkey>.
	399
	400	=head1 RETURN VALUES
	401
	402	EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
	403	B<EVP_PKEY_ASN1_METHOD> object otherwise.
	404
	405	EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
	406	or 1 on success.
	407
	408	EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
	409	B<EVP_PKEY_ASN1_METHOD> object otherwise.
	410
	411	=head1 COPYRIGHT
	412
b0edda11	413	Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
751148e2 RL	414
	415	Licensed under the OpenSSL license (the "License"). You may not use
	416	this file except in compliance with the License. You can obtain a copy
	417	in the file LICENSE in the source distribution or at
	418	L<https://www.openssl.org/source/license.html>.
	419
	420	=cut