1EVP_PKEY_ASN1_METHOD(3) OpenSSL EVP_PKEY_ASN1_METHOD(3)
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 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, 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_cmp(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_size(3).
184 The pkey_bits() method returns the key size in bits. It's called by
186 EVP_PKEY_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_cmp_parameters(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_tls_encodedpoint(3), EVP_PKEY_get1_tls_encodedpoint(3),
239 PKCS7_SIGNER_INFO_set(3), PKCS7_RECIP_INFO_set(3), ...
240 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 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 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 The item_sign() and item_verify() methods make it possible to have
260 algorithm specific signatures and verification of them.
261 item_sign() MUST return one of:
263 <=0 error
265 1 item_sign() did everything, OpenSSL internals just needs to pass
267 the signature length back.
268 2 item_sign() did nothing, OpenSSL internal standard routines are
270 expected to continue with the default signature production.
271 3 item_sign() set the algorithm identifier algor1 and algor2, OpenSSL
273 internals should just sign using those algorithms.
274 item_verify() MUST return one of:
276 <=0 error
278 1 item_sign() did everything, OpenSSL internals just needs to pass
280 the signature length back.
281 2 item_sign() did nothing, OpenSSL internal standard routines are
283 expected to continue with the default signature production.
284 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 int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
290 const ASN1_STRING *sig);
291 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 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 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 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 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 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 ASN1_PKEY_SIGPARAM_NULL
322 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 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 EVP_PKEY_asn1_free() frees an existing EVP_PKEY_ASN1_METHOD pointed by
333 ameth.
334 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 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 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 EVP_PKEY_get0_asn1() finds the EVP_PKEY_ASN1_METHOD associated with the
356 key pkey.
357
359 EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
360 EVP_PKEY_ASN1_METHOD object otherwise.
361 EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
363 or 1 on success.
364 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 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>.
3751.1.1q 2023-07-20 EVP_PKEY_ASN1_METHOD(3)