xref: /openssl/doc/man3/EVP_PKEY_ASN1_METHOD.pod (revision 7ed6de99)
1=pod
2
3=head1 NAME
4
5EVP_PKEY_ASN1_METHOD,
6EVP_PKEY_asn1_new,
7EVP_PKEY_asn1_copy,
8EVP_PKEY_asn1_free,
9EVP_PKEY_asn1_add0,
10EVP_PKEY_asn1_add_alias,
11EVP_PKEY_asn1_set_public,
12EVP_PKEY_asn1_set_private,
13EVP_PKEY_asn1_set_param,
14EVP_PKEY_asn1_set_free,
15EVP_PKEY_asn1_set_ctrl,
16EVP_PKEY_asn1_set_item,
17EVP_PKEY_asn1_set_siginf,
18EVP_PKEY_asn1_set_check,
19EVP_PKEY_asn1_set_public_check,
20EVP_PKEY_asn1_set_param_check,
21EVP_PKEY_asn1_set_security_bits,
22EVP_PKEY_asn1_set_set_priv_key,
23EVP_PKEY_asn1_set_set_pub_key,
24EVP_PKEY_asn1_set_get_priv_key,
25EVP_PKEY_asn1_set_get_pub_key,
26EVP_PKEY_get0_asn1
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,
46                                                  const X509_PUBKEY *pub),
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
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
115 void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
116                                      int (*pkey_security_bits) (const EVP_PKEY
117                                                                 *pk));
118
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
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
140 const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);
141
142=head1 DESCRIPTION
143
144B<EVP_PKEY_ASN1_METHOD> is a structure which holds a set of ASN.1
145conversion, printing and information methods for a specific public key
146algorithm.
147
148There are two places where the B<EVP_PKEY_ASN1_METHOD> objects are
149stored: one is a built-in array representing the standard methods for
150different algorithms, and the other one is a stack of user-defined
151application-specific methods, which can be manipulated by using
152L<EVP_PKEY_asn1_add0(3)>.
153
154=head2 Methods
155
156The methods are the underlying implementations of a particular public
157key algorithm present by the B<EVP_PKEY> object.
158
159 int (*pub_decode) (EVP_PKEY *pk, const 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
165The pub_decode() and pub_encode() methods are called to decode /
166encode B<X509_PUBKEY> ASN.1 parameters to / from B<pk>.
167They MUST return 0 on error, 1 on success.
168They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>.
169
170The pub_cmp() method is called when two public keys are to be
171compared.
172It MUST return 1 when the keys are equal, 0 otherwise.
173It's called by L<EVP_PKEY_eq(3)>.
174
175The pub_print() method is called to print a public key in humanly
176readable text to B<out>, indented B<indent> spaces.
177It MUST return 0 on error, 1 on success.
178It'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
185The priv_decode() and priv_encode() methods are called to decode /
186encode B<PKCS8_PRIV_KEY_INFO> form private key to / from B<pk>.
187They MUST return 0 on error, 1 on success.
188They're called by L<EVP_PKCS82PKEY(3)> and L<EVP_PKEY2PKCS8(3)>.
189
190The priv_print() method is called to print a private key in humanly
191readable text to B<out>, indented B<indent> spaces.
192It MUST return 0 on error, 1 on success.
193It'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
199The pkey_size() method returns the key size in bytes.
200It's called by L<EVP_PKEY_get_size(3)>.
201
202The pkey_bits() method returns the key size in bits.
203It's called by L<EVP_PKEY_get_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
214The param_decode() and param_encode() methods are called to decode /
215encode DER formatted parameters to / from B<pk>.
216They MUST return 0 on error, 1 on success.
217They're called by L<PEM_read_bio_Parameters(3)> and the B<file:>
218L<OSSL_STORE_LOADER(3)>.
219
220The param_missing() method returns 0 if a key parameter is missing,
221otherwise 1.
222It's called by L<EVP_PKEY_missing_parameters(3)>.
223
224The param_copy() method copies key parameters from B<from> to B<to>.
225It MUST return 0 on error, 1 on success.
226It's called by L<EVP_PKEY_copy_parameters(3)>.
227
228The param_cmp() method compares the parameters of keys B<a> and B<b>.
229It MUST return 1 when the keys are equal, 0 when not equal, or a
230negative number on error.
231It's called by L<EVP_PKEY_parameters_eq(3)>.
232
233The param_print() method prints the private key parameters in humanly
234readable text to B<out>, indented B<indent> spaces.
235It MUST return 0 on error, 1 on success.
236It'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
242The sig_print() method prints a signature in humanly readable text to
243B<out>, indented B<indent> spaces.
244B<sigalg> contains the exact signature algorithm.
245If the signature in B<sig> doesn't correspond to what this method
246expects, X509_signature_dump() must be used as a last resort.
247It MUST return 0 on error, 1 on success.
248It's called by L<X509_signature_print(3)>.
249
250 void (*pkey_free) (EVP_PKEY *pkey);
251
252The pkey_free() method helps freeing the internals of B<pkey>.
253It's called by L<EVP_PKEY_free(3)>, L<EVP_PKEY_set_type(3)>,
254L<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
258The pkey_ctrl() method adds extra algorithm specific control.
259It's called by L<EVP_PKEY_get_default_digest_nid(3)>,
260L<EVP_PKEY_set1_encoded_public_key(3)>,
261L<EVP_PKEY_get1_encoded_public_key(3)>, L<PKCS7_SIGNER_INFO_set(3)>,
262L<PKCS7_RECIP_INFO_set(3)>, ...
263
264 int (*old_priv_decode) (EVP_PKEY *pkey,
265                         const unsigned char **pder, int derlen);
266 int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder);
267
268The old_priv_decode() and old_priv_encode() methods decode / encode
269they private key B<pkey> from / to a DER formatted array.
270These are exclusively used to help decoding / encoding older (pre
271PKCS#8) PEM formatted encrypted private keys.
272old_priv_decode() MUST return 0 on error, 1 on success.
273old_priv_encode() MUST the return same kind of values as
274i2d_PrivateKey().
275They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>.
276
277 int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
278                     X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey);
279 int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
280                   X509_ALGOR *alg1, X509_ALGOR *alg2,
281                   ASN1_BIT_STRING *sig);
282
283The item_sign() and  item_verify() methods make it possible to have
284algorithm specific signatures and verification of them.
285
286item_sign() MUST return one of:
287
288=over 4
289
290=item <=0
291
292error
293
294=item Z<>1
295
296item_sign() did everything, OpenSSL internals just needs to pass the
297signature length back.
298
299=item Z<>2
300
301item_sign() did nothing, OpenSSL internal standard routines are
302expected to continue with the default signature production.
303
304=item Z<>3
305
306item_sign() set the algorithm identifier B<algor1> and B<algor2>,
307OpenSSL internals should just sign using those algorithms.
308
309=back
310
311item_verify() MUST return one of:
312
313=over 4
314
315=item <=0
316
317error
318
319=item Z<>1
320
321item_sign() did everything, OpenSSL internals just needs to pass the
322signature length back.
323
324=item Z<>2
325
326item_sign() did nothing, OpenSSL internal standard routines are
327expected to continue with the default signature production.
328
329=back
330
331item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and
332L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>,
333L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ...
334
335 int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
336                    const ASN1_STRING *sig);
337
338The siginf_set() method is used to set custom B<X509_SIG_INFO>
339parameters.
340It MUST return 0 on error, or 1 on success.
341It's called as part of L<X509_check_purpose(3)>, L<X509_check_ca(3)>
342and L<X509_check_issued(3)>.
343
344 int (*pkey_check) (const EVP_PKEY *pk);
345 int (*pkey_public_check) (const EVP_PKEY *pk);
346 int (*pkey_param_check) (const EVP_PKEY *pk);
347
348The pkey_check(), pkey_public_check() and pkey_param_check() methods are used
349to check the validity of B<pk> for key-pair, public component and parameters,
350respectively.
351They MUST return 0 for an invalid key, or 1 for a valid key.
352They are called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
353L<EVP_PKEY_param_check(3)> respectively.
354
355 int (*set_priv_key) (EVP_PKEY *pk, const unsigned char *priv, size_t len);
356 int (*set_pub_key) (EVP_PKEY *pk, const unsigned char *pub, size_t len);
357
358The set_priv_key() and set_pub_key() methods are used to set the raw private and
359public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success.
360They are called by L<EVP_PKEY_new_raw_private_key(3)>, and
361L<EVP_PKEY_new_raw_public_key(3)> respectively.
362
363 size_t (*dirty) (const EVP_PKEY *pk);
364 void *(*export_to) (const EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
365
366dirty_cnt() returns the internal key's dirty count.
367This can be used to synchronise different copies of the same keys.
368
369The export_to() method exports the key material from the given key to
370a provider, through the L<EVP_KEYMGMT(3)> interface, if that provider
371supports importing key material.
372
373=head2 Functions
374
375EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD>
376object, and associates the given B<id>, B<flags>, B<pem_str> and
377B<info>.
378B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a
379descriptive string.
380The following B<flags> are supported:
381
382 ASN1_PKEY_SIGPARAM_NULL
383
384If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm
385parameters are given the type B<V_ASN1_NULL> by default, otherwise
386they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is
387omitted).
388See L<X509_ALGOR_set0(3)> for more information.
389
390EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from
391B<src> to B<dst>.
392This function is not thread safe, it's recommended to only use this
393when initializing the application.
394
395EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
396by B<ameth>. If the argument is NULL, nothing is done.
397
398EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of
399methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is
400already there.
401This function is not thread safe, it's recommended to only use this
402when initializing the application.
403
404EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the
405B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another
406B<EVP_PKEY_ASN1_METHOD> with the same NID is already added.
407This function is not thread safe, it's recommended to only use this
408when initializing the application.
409
410EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
411EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
412EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
413EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
414EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(),
415EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key(),
416EVP_PKEY_asn1_set_set_pub_key(), EVP_PKEY_asn1_set_get_priv_key() and
417EVP_PKEY_asn1_set_get_pub_key() set the diverse methods of the given
418B<EVP_PKEY_ASN1_METHOD> object.
419
420EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated
421with the key B<pkey>.
422
423=head1 RETURN VALUES
424
425EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
426B<EVP_PKEY_ASN1_METHOD> object otherwise.
427
428EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
429or 1 on success.
430
431EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
432B<EVP_PKEY_ASN1_METHOD> object otherwise.
433
434=head1 HISTORY
435
436The signature of the I<pub_decode> functional argument of
437EVP_PKEY_asn1_set_public() has changed in OpenSSL 3.0 so its I<pub>
438parameter is now constified.
439
440=head1 COPYRIGHT
441
442Copyright 2017-2024 The OpenSSL Project Authors. All Rights Reserved.
443
444Licensed under the Apache License 2.0 (the "License").  You may not use
445this file except in compliance with the License.  You can obtain a copy
446in the file LICENSE in the source distribution or at
447L<https://www.openssl.org/source/license.html>.
448
449=cut
450