1EVP_PKEY_ASN1_METHOD(3)             OpenSSL            EVP_PKEY_ASN1_METHOD(3)
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                                                         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, 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_cmp(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_size(3).
184
185       The pkey_bits() method returns the key size in bits.  It's called by
186       EVP_PKEY_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_cmp_parameters(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_tls_encodedpoint(3), EVP_PKEY_get1_tls_encodedpoint(3),
239       PKCS7_SIGNER_INFO_set(3), PKCS7_RECIP_INFO_set(3), ...
240
241        int (*old_priv_decode) (EVP_PKEY *pkey,
242                                const unsigned char **pder, int derlen);
243        int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder);
244
245       The old_priv_decode() and old_priv_encode() methods decode / encode
246       they private key pkey from / to a DER formatted array.  These are
247       exclusively used to help decoding / encoding older (pre PKCS#8) PEM
248       formatted encrypted private keys.  old_priv_decode() MUST return 0 on
249       error, 1 on success.  old_priv_encode() MUST the return same kind of
250       values as i2d_PrivateKey().  They're called by d2i_PrivateKey(3) and
251       i2d_PrivateKey(3).
252
253        int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
254                            X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey);
255        int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
256                          X509_ALGOR *alg1, X509_ALGOR *alg2,
257                          ASN1_BIT_STRING *sig);
258
259       The item_sign() and  item_verify() methods make it possible to have
260       algorithm specific signatures and verification of them.
261
262       item_sign() MUST return one of:
263
264       <=0 error
265
266       1   item_sign() did everything, OpenSSL internals just needs to pass
267           the signature length back.
268
269       2   item_sign() did nothing, OpenSSL internal standard routines are
270           expected to continue with the default signature production.
271
272       3   item_sign() set the algorithm identifier algor1 and algor2, OpenSSL
273           internals should just sign using those algorithms.
274
275       item_verify() MUST return one of:
276
277       <=0 error
278
279       1   item_sign() did everything, OpenSSL internals just needs to pass
280           the signature length back.
281
282       2   item_sign() did nothing, OpenSSL internal standard routines are
283           expected to continue with the default signature production.
284
285       item_verify() and item_sign() are called by ASN1_item_verify(3) and
286       ASN1_item_sign(3), and by extension, X509_verify(3),
287       X509_REQ_verify(3), X509_sign(3), X509_REQ_sign(3), ...
288
289        int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
290                           const ASN1_STRING *sig);
291
292       The siginf_set() method is used to set custom X509_SIG_INFO parameters.
293       It MUST return 0 on error, or 1 on success.  It's called as part of
294       X509_check_purpose(3), X509_check_ca(3) and X509_check_issued(3).
295
296        int (*pkey_check) (const EVP_PKEY *pk);
297        int (*pkey_public_check) (const EVP_PKEY *pk);
298        int (*pkey_param_check) (const EVP_PKEY *pk);
299
300       The pkey_check(), pkey_public_check() and pkey_param_check() methods
301       are used to check the validity of pk for key-pair, public component and
302       parameters, respectively.  They MUST return 0 for an invalid key, or 1
303       for a valid key.  They are called by EVP_PKEY_check(3),
304       EVP_PKEY_public_check(3) and EVP_PKEY_param_check(3) respectively.
305
306        int (*set_priv_key) (EVP_PKEY *pk, const unsigned char *priv, size_t len);
307        int (*set_pub_key) (EVP_PKEY *pk, const unsigned char *pub, size_t len);
308
309       The set_priv_key() and set_pub_key() methods are used to set the raw
310       private and public key data for an EVP_PKEY. They MUST return 0 on
311       error, or 1 on success.  They are called by
312       EVP_PKEY_new_raw_private_key(3), and EVP_PKEY_new_raw_public_key(3)
313       respectively.
314
315   Functions
316       EVP_PKEY_asn1_new() creates and returns a new EVP_PKEY_ASN1_METHOD
317       object, and associates the given id, flags, pem_str and info.  id is a
318       NID, pem_str is the PEM type string, info is a descriptive string.  The
319       following flags are supported:
320
321        ASN1_PKEY_SIGPARAM_NULL
322
323       If ASN1_PKEY_SIGPARAM_NULL is set, then the signature algorithm
324       parameters are given the type V_ASN1_NULL by default, otherwise they
325       will be given the type V_ASN1_UNDEF (i.e. the parameter is omitted).
326       See X509_ALGOR_set0(3) for more information.
327
328       EVP_PKEY_asn1_copy() copies an EVP_PKEY_ASN1_METHOD object from src to
329       dst.  This function is not thread safe, it's recommended to only use
330       this when initializing the application.
331
332       EVP_PKEY_asn1_free() frees an existing EVP_PKEY_ASN1_METHOD pointed by
333       ameth.
334
335       EVP_PKEY_asn1_add0() adds ameth to the user defined stack of methods
336       unless another EVP_PKEY_ASN1_METHOD with the same NID is already there.
337       This function is not thread safe, it's recommended to only use this
338       when initializing the application.
339
340       EVP_PKEY_asn1_add_alias() creates an alias with the NID to for the
341       EVP_PKEY_ASN1_METHOD with NID from unless another EVP_PKEY_ASN1_METHOD
342       with the same NID is already added.  This function is not thread safe,
343       it's recommended to only use this when initializing the application.
344
345       EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
346       EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
347       EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
348       EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
349       EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(),
350       EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key(),
351       EVP_PKEY_asn1_set_set_pub_key(), EVP_PKEY_asn1_set_get_priv_key() and
352       EVP_PKEY_asn1_set_get_pub_key() set the diverse methods of the given
353       EVP_PKEY_ASN1_METHOD object.
354
355       EVP_PKEY_get0_asn1() finds the EVP_PKEY_ASN1_METHOD associated with the
356       key pkey.
357

RETURN VALUES

359       EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
360       EVP_PKEY_ASN1_METHOD object otherwise.
361
362       EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
363       or 1 on success.
364
365       EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
366       EVP_PKEY_ASN1_METHOD object otherwise.
367
369       Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
370
371       Licensed under the OpenSSL license (the "License").  You may not use
372       this file except in compliance with the License.  You can obtain a copy
373       in the file LICENSE in the source distribution or at
374       <https://www.openssl.org/source/license.html>.
375
376
377
3781.1.1c                            2019-05-28           EVP_PKEY_ASN1_METHOD(3)
Impressum