1EVP_PKEY_ASN1_METHOD(3ossl)         OpenSSL        EVP_PKEY_ASN1_METHOD(3ossl)
2
3
4

NAME

6       EVP_PKEY_ASN1_METHOD, EVP_PKEY_asn1_new, EVP_PKEY_asn1_copy,
7       EVP_PKEY_asn1_free, EVP_PKEY_asn1_add0, EVP_PKEY_asn1_add_alias,
8       EVP_PKEY_asn1_set_public, EVP_PKEY_asn1_set_private,
9       EVP_PKEY_asn1_set_param, EVP_PKEY_asn1_set_free,
10       EVP_PKEY_asn1_set_ctrl, EVP_PKEY_asn1_set_item,
11       EVP_PKEY_asn1_set_siginf, EVP_PKEY_asn1_set_check,
12       EVP_PKEY_asn1_set_public_check, EVP_PKEY_asn1_set_param_check,
13       EVP_PKEY_asn1_set_security_bits, EVP_PKEY_asn1_set_set_priv_key,
14       EVP_PKEY_asn1_set_set_pub_key, EVP_PKEY_asn1_set_get_priv_key,
15       EVP_PKEY_asn1_set_get_pub_key, EVP_PKEY_get0_asn1 - manipulating and
16       registering EVP_PKEY_ASN1_METHOD structure
17

SYNOPSIS

19        #include <openssl/evp.h>
20
21        typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;
22
23        EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags,
24                                                const char *pem_str,
25                                                const char *info);
26        void EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst,
27                                const EVP_PKEY_ASN1_METHOD *src);
28        void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth);
29        int EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth);
30        int EVP_PKEY_asn1_add_alias(int to, int from);
31
32        void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,
33                                      int (*pub_decode) (EVP_PKEY *pk,
34                                                         const X509_PUBKEY *pub),
35                                      int (*pub_encode) (X509_PUBKEY *pub,
36                                                         const EVP_PKEY *pk),
37                                      int (*pub_cmp) (const EVP_PKEY *a,
38                                                      const EVP_PKEY *b),
39                                      int (*pub_print) (BIO *out,
40                                                        const EVP_PKEY *pkey,
41                                                        int indent, ASN1_PCTX *pctx),
42                                      int (*pkey_size) (const EVP_PKEY *pk),
43                                      int (*pkey_bits) (const EVP_PKEY *pk));
44        void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth,
45                                       int (*priv_decode) (EVP_PKEY *pk,
46                                                           const PKCS8_PRIV_KEY_INFO
47                                                           *p8inf),
48                                       int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8,
49                                                           const EVP_PKEY *pk),
50                                       int (*priv_print) (BIO *out,
51                                                          const EVP_PKEY *pkey,
52                                                          int indent,
53                                                          ASN1_PCTX *pctx));
54        void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth,
55                                     int (*param_decode) (EVP_PKEY *pkey,
56                                                          const unsigned char **pder,
57                                                          int derlen),
58                                     int (*param_encode) (const EVP_PKEY *pkey,
59                                                          unsigned char **pder),
60                                     int (*param_missing) (const EVP_PKEY *pk),
61                                     int (*param_copy) (EVP_PKEY *to,
62                                                        const EVP_PKEY *from),
63                                     int (*param_cmp) (const EVP_PKEY *a,
64                                                       const EVP_PKEY *b),
65                                     int (*param_print) (BIO *out,
66                                                         const EVP_PKEY *pkey,
67                                                         int indent,
68                                                         ASN1_PCTX *pctx));
69
70        void EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth,
71                                    void (*pkey_free) (EVP_PKEY *pkey));
72        void EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth,
73                                    int (*pkey_ctrl) (EVP_PKEY *pkey, int op,
74                                                      long arg1, void *arg2));
75        void EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth,
76                                    int (*item_verify) (EVP_MD_CTX *ctx,
77                                                        const ASN1_ITEM *it,
78                                                        void *asn,
79                                                        X509_ALGOR *a,
80                                                        ASN1_BIT_STRING *sig,
81                                                        EVP_PKEY *pkey),
82                                    int (*item_sign) (EVP_MD_CTX *ctx,
83                                                      const ASN1_ITEM *it,
84                                                      void *asn,
85                                                      X509_ALGOR *alg1,
86                                                      X509_ALGOR *alg2,
87                                                      ASN1_BIT_STRING *sig));
88
89        void EVP_PKEY_asn1_set_siginf(EVP_PKEY_ASN1_METHOD *ameth,
90                                      int (*siginf_set) (X509_SIG_INFO *siginf,
91                                                         const X509_ALGOR *alg,
92                                                         const ASN1_STRING *sig));
93
94        void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,
95                                     int (*pkey_check) (const EVP_PKEY *pk));
96
97        void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,
98                                            int (*pkey_pub_check) (const EVP_PKEY *pk));
99
100        void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,
101                                           int (*pkey_param_check) (const EVP_PKEY *pk));
102
103        void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
104                                             int (*pkey_security_bits) (const EVP_PKEY
105                                                                        *pk));
106
107        void EVP_PKEY_asn1_set_set_priv_key(EVP_PKEY_ASN1_METHOD *ameth,
108                                            int (*set_priv_key) (EVP_PKEY *pk,
109                                                                 const unsigned char
110                                                                    *priv,
111                                                                 size_t len));
112
113        void EVP_PKEY_asn1_set_set_pub_key(EVP_PKEY_ASN1_METHOD *ameth,
114                                           int (*set_pub_key) (EVP_PKEY *pk,
115                                                               const unsigned char *pub,
116                                                               size_t len));
117
118        void EVP_PKEY_asn1_set_get_priv_key(EVP_PKEY_ASN1_METHOD *ameth,
119                                            int (*get_priv_key) (const EVP_PKEY *pk,
120                                                                 unsigned char *priv,
121                                                                 size_t *len));
122
123        void EVP_PKEY_asn1_set_get_pub_key(EVP_PKEY_ASN1_METHOD *ameth,
124                                           int (*get_pub_key) (const EVP_PKEY *pk,
125                                                               unsigned char *pub,
126                                                               size_t *len));
127
128        const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);
129

DESCRIPTION

131       EVP_PKEY_ASN1_METHOD is a structure which holds a set of ASN.1
132       conversion, printing and information methods for a specific public key
133       algorithm.
134
135       There are two places where the EVP_PKEY_ASN1_METHOD objects are stored:
136       one is a built-in array representing the standard methods for different
137       algorithms, and the other one is a stack of user-defined application-
138       specific methods, which can be manipulated by using
139       EVP_PKEY_asn1_add0(3).
140
141   Methods
142       The methods are the underlying implementations of a particular public
143       key algorithm present by the EVP_PKEY object.
144
145        int (*pub_decode) (EVP_PKEY *pk, const X509_PUBKEY *pub);
146        int (*pub_encode) (X509_PUBKEY *pub, const EVP_PKEY *pk);
147        int (*pub_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);
148        int (*pub_print) (BIO *out, const EVP_PKEY *pkey, int indent,
149                          ASN1_PCTX *pctx);
150
151       The pub_decode() and pub_encode() methods are called to decode / encode
152       X509_PUBKEY ASN.1 parameters to / from pk.  They MUST return 0 on
153       error, 1 on success.  They're called by X509_PUBKEY_get0(3) and
154       X509_PUBKEY_set(3).
155
156       The pub_cmp() method is called when two public keys are to be compared.
157       It MUST return 1 when the keys are equal, 0 otherwise.  It's called by
158       EVP_PKEY_eq(3).
159
160       The pub_print() method is called to print a public key in humanly
161       readable text to out, indented indent spaces.  It MUST return 0 on
162       error, 1 on success.  It's called by EVP_PKEY_print_public(3).
163
164        int (*priv_decode) (EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf);
165        int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk);
166        int (*priv_print) (BIO *out, const EVP_PKEY *pkey, int indent,
167                           ASN1_PCTX *pctx);
168
169       The priv_decode() and priv_encode() methods are called to decode /
170       encode PKCS8_PRIV_KEY_INFO form private key to / from pk.  They MUST
171       return 0 on error, 1 on success.  They're called by EVP_PKCS82PKEY(3)
172       and EVP_PKEY2PKCS8(3).
173
174       The priv_print() method is called to print a private key in humanly
175       readable text to out, indented indent spaces.  It MUST return 0 on
176       error, 1 on success.  It's called by EVP_PKEY_print_private(3).
177
178        int (*pkey_size) (const EVP_PKEY *pk);
179        int (*pkey_bits) (const EVP_PKEY *pk);
180        int (*pkey_security_bits) (const EVP_PKEY *pk);
181
182       The pkey_size() method returns the key size in bytes.  It's called by
183       EVP_PKEY_get_size(3).
184
185       The pkey_bits() method returns the key size in bits.  It's called by
186       EVP_PKEY_get_bits(3).
187
188        int (*param_decode) (EVP_PKEY *pkey,
189                             const unsigned char **pder, int derlen);
190        int (*param_encode) (const EVP_PKEY *pkey, unsigned char **pder);
191        int (*param_missing) (const EVP_PKEY *pk);
192        int (*param_copy) (EVP_PKEY *to, const EVP_PKEY *from);
193        int (*param_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);
194        int (*param_print) (BIO *out, const EVP_PKEY *pkey, int indent,
195                            ASN1_PCTX *pctx);
196
197       The param_decode() and param_encode() methods are called to decode /
198       encode DER formatted parameters to / from pk.  They MUST return 0 on
199       error, 1 on success.  They're called by PEM_read_bio_Parameters(3) and
200       the file: OSSL_STORE_LOADER(3).
201
202       The param_missing() method returns 0 if a key parameter is missing,
203       otherwise 1.  It's called by EVP_PKEY_missing_parameters(3).
204
205       The param_copy() method copies key parameters from from to to.  It MUST
206       return 0 on error, 1 on success.  It's called by
207       EVP_PKEY_copy_parameters(3).
208
209       The param_cmp() method compares the parameters of keys a and b.  It
210       MUST return 1 when the keys are equal, 0 when not equal, or a negative
211       number on error.  It's called by EVP_PKEY_parameters_eq(3).
212
213       The param_print() method prints the private key parameters in humanly
214       readable text to out, indented indent spaces.  It MUST return 0 on
215       error, 1 on success.  It's called by EVP_PKEY_print_params(3).
216
217        int (*sig_print) (BIO *out,
218                          const X509_ALGOR *sigalg, const ASN1_STRING *sig,
219                          int indent, ASN1_PCTX *pctx);
220
221       The sig_print() method prints a signature in humanly readable text to
222       out, indented indent spaces.  sigalg contains the exact signature
223       algorithm.  If the signature in sig doesn't correspond to what this
224       method expects, X509_signature_dump() must be used as a last resort.
225       It MUST return 0 on error, 1 on success.  It's called by
226       X509_signature_print(3).
227
228        void (*pkey_free) (EVP_PKEY *pkey);
229
230       The pkey_free() method helps freeing the internals of pkey.  It's
231       called by EVP_PKEY_free(3), EVP_PKEY_set_type(3),
232       EVP_PKEY_set_type_str(3), and EVP_PKEY_assign(3).
233
234        int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);
235
236       The pkey_ctrl() method adds extra algorithm specific control.  It's
237       called by EVP_PKEY_get_default_digest_nid(3),
238       EVP_PKEY_set1_encoded_public_key(3),
239       EVP_PKEY_get1_encoded_public_key(3), PKCS7_SIGNER_INFO_set(3),
240       PKCS7_RECIP_INFO_set(3), ...
241
242        int (*old_priv_decode) (EVP_PKEY *pkey,
243                                const unsigned char **pder, int derlen);
244        int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder);
245
246       The old_priv_decode() and old_priv_encode() methods decode / encode
247       they private key pkey from / to a DER formatted array.  These are
248       exclusively used to help decoding / encoding older (pre PKCS#8) PEM
249       formatted encrypted private keys.  old_priv_decode() MUST return 0 on
250       error, 1 on success.  old_priv_encode() MUST the return same kind of
251       values as i2d_PrivateKey().  They're called by d2i_PrivateKey(3) and
252       i2d_PrivateKey(3).
253
254        int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
255                            X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey);
256        int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
257                          X509_ALGOR *alg1, X509_ALGOR *alg2,
258                          ASN1_BIT_STRING *sig);
259
260       The item_sign() and  item_verify() methods make it possible to have
261       algorithm specific signatures and verification of them.
262
263       item_sign() MUST return one of:
264
265       <=0 error
266
267       1   item_sign() did everything, OpenSSL internals just needs to pass
268           the signature length back.
269
270       2   item_sign() did nothing, OpenSSL internal standard routines are
271           expected to continue with the default signature production.
272
273       3   item_sign() set the algorithm identifier algor1 and algor2, OpenSSL
274           internals should just sign using those algorithms.
275
276       item_verify() MUST return one of:
277
278       <=0 error
279
280       1   item_sign() did everything, OpenSSL internals just needs to pass
281           the signature length back.
282
283       2   item_sign() did nothing, OpenSSL internal standard routines are
284           expected to continue with the default signature production.
285
286       item_verify() and item_sign() are called by ASN1_item_verify(3) and
287       ASN1_item_sign(3), and by extension, X509_verify(3),
288       X509_REQ_verify(3), X509_sign(3), X509_REQ_sign(3), ...
289
290        int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
291                           const ASN1_STRING *sig);
292
293       The siginf_set() method is used to set custom X509_SIG_INFO parameters.
294       It MUST return 0 on error, or 1 on success.  It's called as part of
295       X509_check_purpose(3), X509_check_ca(3) and X509_check_issued(3).
296
297        int (*pkey_check) (const EVP_PKEY *pk);
298        int (*pkey_public_check) (const EVP_PKEY *pk);
299        int (*pkey_param_check) (const EVP_PKEY *pk);
300
301       The pkey_check(), pkey_public_check() and pkey_param_check() methods
302       are used to check the validity of pk for key-pair, public component and
303       parameters, respectively.  They MUST return 0 for an invalid key, or 1
304       for a valid key.  They are called by EVP_PKEY_check(3),
305       EVP_PKEY_public_check(3) and EVP_PKEY_param_check(3) respectively.
306
307        int (*set_priv_key) (EVP_PKEY *pk, const unsigned char *priv, size_t len);
308        int (*set_pub_key) (EVP_PKEY *pk, const unsigned char *pub, size_t len);
309
310       The set_priv_key() and set_pub_key() methods are used to set the raw
311       private and public key data for an EVP_PKEY. They MUST return 0 on
312       error, or 1 on success.  They are called by
313       EVP_PKEY_new_raw_private_key(3), and EVP_PKEY_new_raw_public_key(3)
314       respectively.
315
316        size_t (*dirty) (const EVP_PKEY *pk);
317        void *(*export_to) (const EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
318
319       dirty_cnt() returns the internal key's dirty count.  This can be used
320       to synchronise different copies of the same keys.
321
322       The export_to() method exports the key material from the given key to a
323       provider, through the EVP_KEYMGMT(3) interface, if that provider
324       supports importing key material.
325
326   Functions
327       EVP_PKEY_asn1_new() creates and returns a new EVP_PKEY_ASN1_METHOD
328       object, and associates the given id, flags, pem_str and info.  id is a
329       NID, pem_str is the PEM type string, info is a descriptive string.  The
330       following flags are supported:
331
332        ASN1_PKEY_SIGPARAM_NULL
333
334       If ASN1_PKEY_SIGPARAM_NULL is set, then the signature algorithm
335       parameters are given the type V_ASN1_NULL by default, otherwise they
336       will be given the type V_ASN1_UNDEF (i.e. the parameter is omitted).
337       See X509_ALGOR_set0(3) for more information.
338
339       EVP_PKEY_asn1_copy() copies an EVP_PKEY_ASN1_METHOD object from src to
340       dst.  This function is not thread safe, it's recommended to only use
341       this when initializing the application.
342
343       EVP_PKEY_asn1_free() frees an existing EVP_PKEY_ASN1_METHOD pointed by
344       ameth.
345
346       EVP_PKEY_asn1_add0() adds ameth to the user defined stack of methods
347       unless another EVP_PKEY_ASN1_METHOD with the same NID is already there.
348       This function is not thread safe, it's recommended to only use this
349       when initializing the application.
350
351       EVP_PKEY_asn1_add_alias() creates an alias with the NID to for the
352       EVP_PKEY_ASN1_METHOD with NID from unless another EVP_PKEY_ASN1_METHOD
353       with the same NID is already added.  This function is not thread safe,
354       it's recommended to only use this when initializing the application.
355
356       EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
357       EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
358       EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
359       EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
360       EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(),
361       EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key(),
362       EVP_PKEY_asn1_set_set_pub_key(), EVP_PKEY_asn1_set_get_priv_key() and
363       EVP_PKEY_asn1_set_get_pub_key() set the diverse methods of the given
364       EVP_PKEY_ASN1_METHOD object.
365
366       EVP_PKEY_get0_asn1() finds the EVP_PKEY_ASN1_METHOD associated with the
367       key pkey.
368

RETURN VALUES

370       EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
371       EVP_PKEY_ASN1_METHOD object otherwise.
372
373       EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
374       or 1 on success.
375
376       EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
377       EVP_PKEY_ASN1_METHOD object otherwise.
378

HISTORY

380       The signature of the pub_decode functional argument of
381       EVP_PKEY_asn1_set_public() has changed in OpenSSL 3.0 so its pub
382       parameter is now constified.
383
385       Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved.
386
387       Licensed under the Apache License 2.0 (the "License").  You may not use
388       this file except in compliance with the License.  You can obtain a copy
389       in the file LICENSE in the source distribution or at
390       <https://www.openssl.org/source/license.html>.
391
392
393
3943.1.1                             2023-08-31       EVP_PKEY_ASN1_METHOD(3ossl)
Impressum