1EVP_PKEY_ASN1_METHOD(3ossl) OpenSSL EVP_PKEY_ASN1_METHOD(3ossl)
2
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
19 #include <openssl/evp.h>
20 typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;
22 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 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 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 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 void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,
95 int (*pkey_check) (const EVP_PKEY *pk));
96 void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,
98 int (*pkey_pub_check) (const EVP_PKEY *pk));
99 void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,
101 int (*pkey_param_check) (const EVP_PKEY *pk));
102 void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
104 int (*pkey_security_bits) (const EVP_PKEY
105 *pk));
106 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 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 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 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 const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);
129
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 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 Methods
142 The methods are the underlying implementations of a particular public
143 key algorithm present by the EVP_PKEY object.
144 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 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 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 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 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 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 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 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 The pkey_size() method returns the key size in bytes. It's called by
183 EVP_PKEY_get_size(3).
184 The pkey_bits() method returns the key size in bits. It's called by
186 EVP_PKEY_get_bits(3).
187 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 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 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 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 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 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 int (*sig_print) (BIO *out,
218 const X509_ALGOR *sigalg, const ASN1_STRING *sig,
219 int indent, ASN1_PCTX *pctx);
220 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 void (*pkey_free) (EVP_PKEY *pkey);
229 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 int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);
235 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 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 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 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 The item_sign() and item_verify() methods make it possible to have
261 algorithm specific signatures and verification of them.
262 item_sign() MUST return one of:
264 <=0 error
266 1 item_sign() did everything, OpenSSL internals just needs to pass
268 the signature length back.
269 2 item_sign() did nothing, OpenSSL internal standard routines are
271 expected to continue with the default signature production.
272 3 item_sign() set the algorithm identifier algor1 and algor2, OpenSSL
274 internals should just sign using those algorithms.
275 item_verify() MUST return one of:
277 <=0 error
279 1 item_sign() did everything, OpenSSL internals just needs to pass
281 the signature length back.
282 2 item_sign() did nothing, OpenSSL internal standard routines are
284 expected to continue with the default signature production.
285 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 int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
291 const ASN1_STRING *sig);
292 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 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 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 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 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 size_t (*dirty) (const EVP_PKEY *pk);
317 void *(*export_to) (const EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
318 dirty_cnt() returns the internal key's dirty count. This can be used
320 to synchronise different copies of the same keys.
321 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 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 ASN1_PKEY_SIGPARAM_NULL
333 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 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 EVP_PKEY_asn1_free() frees an existing EVP_PKEY_ASN1_METHOD pointed by
344 ameth.
345 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 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 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 EVP_PKEY_get0_asn1() finds the EVP_PKEY_ASN1_METHOD associated with the
367 key pkey.
368
370 EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
371 EVP_PKEY_ASN1_METHOD object otherwise.
372 EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
374 or 1 on success.
375 EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
377 EVP_PKEY_ASN1_METHOD object otherwise.
378
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 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>.
3913.1.1 2023-08-31 EVP_PKEY_ASN1_METHOD(3ossl)