[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_asn1_set_get_priv_key,
EVP_PKEY_asn1_set_get_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,
                                                  const 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));

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

 void EVP_PKEY_asn1_set_get_pub_key(EVP_PKEY_ASN1_METHOD *ameth,
                                    int (*get_pub_key) (const EVP_PKEY *pk,
                                                        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_eq(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_parameters_eq(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_supports_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.

 size_t (*dirty) (const EVP_PKEY *pk);
 void *(*export_to) (const EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);

dirty_cnt() returns the internal key's dirty count.
This can be used to synchronise different copies of the same keys.

The export_to() method exports the key material from the given key to
a provider, through the L<EVP_KEYMGMT(3)> interface, if that provider
supports importing key material.

=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(),
EVP_PKEY_asn1_set_set_pub_key(), EVP_PKEY_asn1_set_get_priv_key() and
EVP_PKEY_asn1_set_get_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-2020 The OpenSSL Project Authors. All Rights Reserved.

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