10 EVP_PKEY_asn1_add_alias,
11 EVP_PKEY_asn1_set_public,
12 EVP_PKEY_asn1_set_private,
13 EVP_PKEY_asn1_set_param,
14 EVP_PKEY_asn1_set_free,
15 EVP_PKEY_asn1_set_ctrl,
16 EVP_PKEY_asn1_set_item,
17 EVP_PKEY_asn1_set_siginf,
18 EVP_PKEY_asn1_set_check,
19 EVP_PKEY_asn1_set_public_check,
20 EVP_PKEY_asn1_set_param_check,
21 EVP_PKEY_asn1_set_security_bits,
22 EVP_PKEY_asn1_set_set_priv_key,
23 EVP_PKEY_asn1_set_set_pub_key,
24 EVP_PKEY_asn1_set_get_priv_key,
25 EVP_PKEY_asn1_set_get_pub_key,
27 - manipulating and registering EVP_PKEY_ASN1_METHOD structure
31 #include <openssl/evp.h>
33 typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;
35 EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags,
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);
44 void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,
45 int (*pub_decode) (EVP_PKEY *pk,
47 int (*pub_encode) (X509_PUBKEY *pub,
49 int (*pub_cmp) (const EVP_PKEY *a,
51 int (*pub_print) (BIO *out,
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
60 int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8,
62 int (*priv_print) (BIO *out,
66 void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth,
67 int (*param_decode) (EVP_PKEY *pkey,
68 const unsigned char **pder,
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,
77 int (*param_print) (BIO *out,
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,
94 int (*item_sign) (EVP_MD_CTX *ctx,
99 ASN1_BIT_STRING *sig));
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));
106 void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,
107 int (*pkey_check) (const EVP_PKEY *pk));
109 void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,
110 int (*pkey_pub_check) (const EVP_PKEY *pk));
112 void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,
113 int (*pkey_param_check) (const EVP_PKEY *pk));
115 void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
116 int (*pkey_security_bits) (const EVP_PKEY
119 void EVP_PKEY_asn1_set_set_priv_key(EVP_PKEY_ASN1_METHOD *ameth,
120 int (*set_priv_key) (EVP_PKEY *pk,
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,
130 void EVP_PKEY_asn1_set_get_priv_key(EVP_PKEY_ASN1_METHOD *ameth,
131 int (*get_priv_key) (const EVP_PKEY *pk,
135 void EVP_PKEY_asn1_set_get_pub_key(EVP_PKEY_ASN1_METHOD *ameth,
136 int (*get_pub_key) (const EVP_PKEY *pk,
140 const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);
144 B<EVP_PKEY_ASN1_METHOD> is a structure which holds a set of ASN.1
145 conversion, printing and information methods for a specific public key
148 There are two places where the B<EVP_PKEY_ASN1_METHOD> objects are
149 stored: one is a built-in array representing the standard methods for
150 different algorithms, and the other one is a stack of user-defined
151 application-specific methods, which can be manipulated by using
152 L<EVP_PKEY_asn1_add0(3)>.
156 The methods are the underlying implementations of a particular public
157 key algorithm present by the B<EVP_PKEY> object.
159 int (*pub_decode) (EVP_PKEY *pk, 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,
165 The pub_decode() and pub_encode() methods are called to decode /
166 encode B<X509_PUBKEY> ASN.1 parameters to / from B<pk>.
167 They MUST return 0 on error, 1 on success.
168 They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>.
170 The pub_cmp() method is called when two public keys are to be
172 It MUST return 1 when the keys are equal, 0 otherwise.
173 It's called by L<EVP_PKEY_cmp(3)>.
175 The pub_print() method is called to print a public key in humanly
176 readable text to B<out>, indented B<indent> spaces.
177 It MUST return 0 on error, 1 on success.
178 It's called by L<EVP_PKEY_print_public(3)>.
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,
185 The priv_decode() and priv_encode() methods are called to decode /
186 encode B<PKCS8_PRIV_KEY_INFO> form private key to / from B<pk>.
187 They MUST return 0 on error, 1 on success.
188 They're called by L<EVP_PKCS82PKEY(3)> and L<EVP_PKEY2PKCS8(3)>.
190 The priv_print() method is called to print a private key in humanly
191 readable text to B<out>, indented B<indent> spaces.
192 It MUST return 0 on error, 1 on success.
193 It's called by L<EVP_PKEY_print_private(3)>.
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);
199 The pkey_size() method returns the key size in bytes.
200 It's called by L<EVP_PKEY_size(3)>.
202 The pkey_bits() method returns the key size in bits.
203 It's called by L<EVP_PKEY_bits(3)>.
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,
214 The param_decode() and param_encode() methods are called to decode /
215 encode DER formatted parameters to / from B<pk>.
216 They MUST return 0 on error, 1 on success.
217 They're called by L<PEM_read_bio_Parameters(3)> and the B<file:>
218 L<OSSL_STORE_LOADER(3)>.
220 The param_missing() method returns 0 if a key parameter is missing,
222 It's called by L<EVP_PKEY_missing_parameters(3)>.
224 The param_copy() method copies key parameters from B<from> to B<to>.
225 It MUST return 0 on error, 1 on success.
226 It's called by L<EVP_PKEY_copy_parameters(3)>.
228 The param_cmp() method compares the parameters of keys B<a> and B<b>.
229 It MUST return 1 when the keys are equal, 0 when not equal, or a
230 negative number on error.
231 It's called by L<EVP_PKEY_cmp_parameters(3)>.
233 The param_print() method prints the private key parameters in humanly
234 readable text to B<out>, indented B<indent> spaces.
235 It MUST return 0 on error, 1 on success.
236 It's called by L<EVP_PKEY_print_params(3)>.
238 int (*sig_print) (BIO *out,
239 const X509_ALGOR *sigalg, const ASN1_STRING *sig,
240 int indent, ASN1_PCTX *pctx);
242 The sig_print() method prints a signature in humanly readable text to
243 B<out>, indented B<indent> spaces.
244 B<sigalg> contains the exact signature algorithm.
245 If the signature in B<sig> doesn't correspond to what this method
246 expects, X509_signature_dump() must be used as a last resort.
247 It MUST return 0 on error, 1 on success.
248 It's called by L<X509_signature_print(3)>.
250 void (*pkey_free) (EVP_PKEY *pkey);
252 The pkey_free() method helps freeing the internals of B<pkey>.
253 It's called by L<EVP_PKEY_free(3)>, L<EVP_PKEY_set_type(3)>,
254 L<EVP_PKEY_set_type_str(3)>, and L<EVP_PKEY_assign(3)>.
256 int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);
258 The pkey_ctrl() method adds extra algorithm specific control.
259 It's called by L<EVP_PKEY_get_default_digest_nid(3)>,
260 L<EVP_PKEY_set1_tls_encodedpoint(3)>,
261 L<EVP_PKEY_get1_tls_encodedpoint(3)>, L<PKCS7_SIGNER_INFO_set(3)>,
262 L<PKCS7_RECIP_INFO_set(3)>, ...
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);
268 The old_priv_decode() and old_priv_encode() methods decode / encode
269 they private key B<pkey> from / to a DER formatted array.
270 These are exclusively used to help decoding / encoding older (pre
271 PKCS#8) PEM formatted encrypted private keys.
272 old_priv_decode() MUST return 0 on error, 1 on success.
273 old_priv_encode() MUST the return same kind of values as
275 They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>.
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);
283 The item_sign() and item_verify() methods make it possible to have
284 algorithm specific signatures and verification of them.
286 item_sign() MUST return one of:
296 item_sign() did everything, OpenSSL internals just needs to pass the
297 signature length back.
301 item_sign() did nothing, OpenSSL internal standard routines are
302 expected to continue with the default signature production.
306 item_sign() set the algorithm identifier B<algor1> and B<algor2>,
307 OpenSSL internals should just sign using those algorithms.
311 item_verify() MUST return one of:
321 item_sign() did everything, OpenSSL internals just needs to pass the
322 signature length back.
326 item_sign() did nothing, OpenSSL internal standard routines are
327 expected to continue with the default signature production.
331 item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and
332 L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>,
333 L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ...
335 int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
336 const ASN1_STRING *sig);
338 The siginf_set() method is used to set custom B<X509_SIG_INFO>
340 It MUST return 0 on error, or 1 on success.
341 It's called as part of L<X509_check_purpose(3)>, L<X509_check_ca(3)>
342 and L<X509_check_issued(3)>.
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);
348 The pkey_check(), pkey_public_check() and pkey_param_check() methods are used
349 to check the validity of B<pk> for key-pair, public component and parameters,
351 They MUST return 0 for an invalid key, or 1 for a valid key.
352 They are called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
353 L<EVP_PKEY_param_check(3)> respectively.
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);
358 The set_priv_key() and set_pub_key() methods are used to set the raw private and
359 public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success.
360 They are called by L<EVP_PKEY_new_raw_private_key(3)>, and
361 L<EVP_PKEY_new_raw_public_key(3)> respectively.
365 EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD>
366 object, and associates the given B<id>, B<flags>, B<pem_str> and
368 B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a
370 The following B<flags> are supported:
372 ASN1_PKEY_SIGPARAM_NULL
374 If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm
375 parameters are given the type B<V_ASN1_NULL> by default, otherwise
376 they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is
378 See L<X509_ALGOR_set0(3)> for more information.
380 EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from
382 This function is not thread safe, it's recommended to only use this
383 when initializing the application.
385 EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
388 EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of
389 methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is
391 This function is not thread safe, it's recommended to only use this
392 when initializing the application.
394 EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the
395 B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another
396 B<EVP_PKEY_ASN1_METHOD> with the same NID is already added.
397 This function is not thread safe, it's recommended to only use this
398 when initializing the application.
400 EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
401 EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
402 EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
403 EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
404 EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(),
405 EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key(),
406 EVP_PKEY_asn1_set_set_pub_key(), EVP_PKEY_asn1_set_get_priv_key() and
407 EVP_PKEY_asn1_set_get_pub_key() set the diverse methods of the given
408 B<EVP_PKEY_ASN1_METHOD> object.
410 EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated
411 with the key B<pkey>.
415 EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
416 B<EVP_PKEY_ASN1_METHOD> object otherwise.
418 EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
421 EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
422 B<EVP_PKEY_ASN1_METHOD> object otherwise.
426 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
428 Licensed under the OpenSSL license (the "License"). You may not use
429 this file except in compliance with the License. You can obtain a copy
430 in the file LICENSE in the source distribution or at
431 L<https://www.openssl.org/source/license.html>.