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,
25 - manipulating and registering EVP_PKEY_ASN1_METHOD structure
29 #include <openssl/evp.h>
31 typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;
33 EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags,
36 void EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst,
37 const EVP_PKEY_ASN1_METHOD *src);
38 void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth);
39 int EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth);
40 int EVP_PKEY_asn1_add_alias(int to, int from);
42 void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,
43 int (*pub_decode) (EVP_PKEY *pk,
45 int (*pub_encode) (X509_PUBKEY *pub,
47 int (*pub_cmp) (const EVP_PKEY *a,
49 int (*pub_print) (BIO *out,
51 int indent, ASN1_PCTX *pctx),
52 int (*pkey_size) (const EVP_PKEY *pk),
53 int (*pkey_bits) (const EVP_PKEY *pk));
54 void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth,
55 int (*priv_decode) (EVP_PKEY *pk,
56 const PKCS8_PRIV_KEY_INFO
58 int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8,
60 int (*priv_print) (BIO *out,
64 void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth,
65 int (*param_decode) (EVP_PKEY *pkey,
66 const unsigned char **pder,
68 int (*param_encode) (const EVP_PKEY *pkey,
69 unsigned char **pder),
70 int (*param_missing) (const EVP_PKEY *pk),
71 int (*param_copy) (EVP_PKEY *to,
72 const EVP_PKEY *from),
73 int (*param_cmp) (const EVP_PKEY *a,
75 int (*param_print) (BIO *out,
80 void EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth,
81 void (*pkey_free) (EVP_PKEY *pkey));
82 void EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth,
83 int (*pkey_ctrl) (EVP_PKEY *pkey, int op,
84 long arg1, void *arg2));
85 void EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth,
86 int (*item_verify) (EVP_MD_CTX *ctx,
92 int (*item_sign) (EVP_MD_CTX *ctx,
97 ASN1_BIT_STRING *sig));
99 void EVP_PKEY_asn1_set_siginf(EVP_PKEY_ASN1_METHOD *ameth,
100 int (*siginf_set) (X509_SIG_INFO *siginf,
101 const X509_ALGOR *alg,
102 const ASN1_STRING *sig));
104 void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,
105 int (*pkey_check) (const EVP_PKEY *pk));
107 void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,
108 int (*pkey_pub_check) (const EVP_PKEY *pk));
110 void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,
111 int (*pkey_param_check) (const EVP_PKEY *pk));
113 void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
114 int (*pkey_security_bits) (const EVP_PKEY
117 void EVP_PKEY_asn1_set_set_priv_key(EVP_PKEY_ASN1_METHOD *ameth,
118 int (*set_priv_key) (EVP_PKEY *pk,
123 void EVP_PKEY_asn1_set_set_pub_key(EVP_PKEY_ASN1_METHOD *ameth,
124 int (*set_pub_key) (EVP_PKEY *pk,
125 const unsigned char *pub,
128 const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);
132 B<EVP_PKEY_ASN1_METHOD> is a structure which holds a set of ASN.1
133 conversion, printing and information methods for a specific public key
136 There are two places where the B<EVP_PKEY_ASN1_METHOD> objects are
137 stored: one is a built-in array representing the standard methods for
138 different algorithms, and the other one is a stack of user-defined
139 application-specific methods, which can be manipulated by using
140 L<EVP_PKEY_asn1_add0(3)>.
144 The methods are the underlying implementations of a particular public
145 key algorithm present by the B<EVP_PKEY> object.
147 int (*pub_decode) (EVP_PKEY *pk, X509_PUBKEY *pub);
148 int (*pub_encode) (X509_PUBKEY *pub, const EVP_PKEY *pk);
149 int (*pub_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);
150 int (*pub_print) (BIO *out, const EVP_PKEY *pkey, int indent,
153 The pub_decode() and pub_encode() methods are called to decode /
154 encode B<X509_PUBKEY> ASN.1 parameters to / from B<pk>.
155 They MUST return 0 on error, 1 on success.
156 They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>.
158 The pub_cmp() method is called when two public keys are to be
160 It MUST return 1 when the keys are equal, 0 otherwise.
161 It's called by L<EVP_PKEY_cmp(3)>.
163 The pub_print() method is called to print a public key in humanly
164 readable text to B<out>, indented B<indent> spaces.
165 It MUST return 0 on error, 1 on success.
166 It's called by L<EVP_PKEY_print_public(3)>.
168 int (*priv_decode) (EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf);
169 int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk);
170 int (*priv_print) (BIO *out, const EVP_PKEY *pkey, int indent,
173 The priv_decode() and priv_encode() methods are called to decode /
174 encode B<PKCS8_PRIV_KEY_INFO> form private key to / from B<pk>.
175 They MUST return 0 on error, 1 on success.
176 They're called by L<EVP_PKCS82PKEY(3)> and L<EVP_PKEY2PKCS8(3)>.
178 The priv_print() method is called to print a private key in humanly
179 readable text to B<out>, indented B<indent> spaces.
180 It MUST return 0 on error, 1 on success.
181 It's called by L<EVP_PKEY_print_private(3)>.
183 int (*pkey_size) (const EVP_PKEY *pk);
184 int (*pkey_bits) (const EVP_PKEY *pk);
185 int (*pkey_security_bits) (const EVP_PKEY *pk);
187 The pkey_size() method returns the key size in bytes.
188 It's called by L<EVP_PKEY_size(3)>.
190 The pkey_bits() method returns the key size in bits.
191 It's called by L<EVP_PKEY_bits(3)>.
193 int (*param_decode) (EVP_PKEY *pkey,
194 const unsigned char **pder, int derlen);
195 int (*param_encode) (const EVP_PKEY *pkey, unsigned char **pder);
196 int (*param_missing) (const EVP_PKEY *pk);
197 int (*param_copy) (EVP_PKEY *to, const EVP_PKEY *from);
198 int (*param_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);
199 int (*param_print) (BIO *out, const EVP_PKEY *pkey, int indent,
202 The param_decode() and param_encode() methods are called to decode /
203 encode DER formatted parameters to / from B<pk>.
204 They MUST return 0 on error, 1 on success.
205 They're called by L<PEM_read_bio_Parameters(3)> and the B<file:>
206 L<OSSL_STORE_LOADER(3)>.
208 The param_missing() method returns 0 if a key parameter is missing,
210 It's called by L<EVP_PKEY_missing_parameters(3)>.
212 The param_copy() method copies key parameters from B<from> to B<to>.
213 It MUST return 0 on error, 1 on success.
214 It's called by L<EVP_PKEY_copy_parameters(3)>.
216 The param_cmp() method compares the parameters of keys B<a> and B<b>.
217 It MUST return 1 when the keys are equal, 0 when not equal, or a
218 negative number on error.
219 It's called by L<EVP_PKEY_cmp_parameters(3)>.
221 The param_print() method prints the private key parameters in humanly
222 readable text to B<out>, indented B<indent> spaces.
223 It MUST return 0 on error, 1 on success.
224 It's called by L<EVP_PKEY_print_params(3)>.
226 int (*sig_print) (BIO *out,
227 const X509_ALGOR *sigalg, const ASN1_STRING *sig,
228 int indent, ASN1_PCTX *pctx);
230 The sig_print() method prints a signature in humanly readable text to
231 B<out>, indented B<indent> spaces.
232 B<sigalg> contains the exact signature algorithm.
233 If the signature in B<sig> doesn't correspond to what this method
234 expects, X509_signature_dump() must be used as a last resort.
235 It MUST return 0 on error, 1 on success.
236 It's called by L<X509_signature_print(3)>.
238 void (*pkey_free) (EVP_PKEY *pkey);
240 The pkey_free() method helps freeing the internals of B<pkey>.
241 It's called by L<EVP_PKEY_free(3)>, L<EVP_PKEY_set_type(3)>,
242 L<EVP_PKEY_set_type_str(3)>, and L<EVP_PKEY_assign(3)>.
244 int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);
246 The pkey_ctrl() method adds extra algorithm specific control.
247 It's called by L<EVP_PKEY_get_default_digest_nid(3)>,
248 L<EVP_PKEY_set1_tls_encodedpoint(3)>,
249 L<EVP_PKEY_get1_tls_encodedpoint(3)>, L<PKCS7_SIGNER_INFO_set(3)>,
250 L<PKCS7_RECIP_INFO_set(3)>, ...
252 int (*old_priv_decode) (EVP_PKEY *pkey,
253 const unsigned char **pder, int derlen);
254 int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder);
256 The old_priv_decode() and old_priv_encode() methods decode / encode
257 they private key B<pkey> from / to a DER formatted array.
258 These are exclusively used to help decoding / encoding older (pre
259 PKCS#8) PEM formatted encrypted private keys.
260 old_priv_decode() MUST return 0 on error, 1 on success.
261 old_priv_encode() MUST the return same kind of values as
263 They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>.
265 int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
266 X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey);
267 int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
268 X509_ALGOR *alg1, X509_ALGOR *alg2,
269 ASN1_BIT_STRING *sig);
271 The item_sign() and item_verify() methods make it possible to have
272 algorithm specific signatures and verification of them.
274 item_sign() MUST return one of:
284 item_sign() did everything, OpenSSL internals just needs to pass the
285 signature length back.
289 item_sign() did nothing, OpenSSL internal standard routines are
290 expected to continue with the default signature production.
294 item_sign() set the algorithm identifier B<algor1> and B<algor2>,
295 OpenSSL internals should just sign using those algorithms.
299 item_verify() MUST return one of:
309 item_sign() did everything, OpenSSL internals just needs to pass the
310 signature length back.
314 item_sign() did nothing, OpenSSL internal standard routines are
315 expected to continue with the default signature production.
319 item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and
320 L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>,
321 L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ...
323 int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
324 const ASN1_STRING *sig);
326 The siginf_set() method is used to set custom B<X509_SIG_INFO>
328 It MUST return 0 on error, or 1 on success.
329 It's called as part of L<X509_check_purpose(3)>, L<X509_check_ca(3)>
330 and L<X509_check_issued(3)>.
332 int (*pkey_check) (const EVP_PKEY *pk);
333 int (*pkey_public_check) (const EVP_PKEY *pk);
334 int (*pkey_param_check) (const EVP_PKEY *pk);
336 The pkey_check(), pkey_public_check() and pkey_param_check() methods are used
337 to check the validity of B<pk> for key-pair, public component and parameters,
339 They MUST return 0 for an invalid key, or 1 for a valid key.
340 They are called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
341 L<EVP_PKEY_param_check(3)> respectively.
343 int (*set_priv_key) (EVP_PKEY *pk, const unsigned char *priv, size_t len);
344 int (*set_pub_key) (EVP_PKEY *pk, const unsigned char *pub, size_t len);
346 The set_priv_key() and set_pub_key() methods are used to set the raw private and
347 public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success.
348 They are called by L<EVP_PKEY_new_raw_private_key(3)>, and
349 L<EVP_PKEY_new_raw_public_key(3)> respectively.
353 EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD>
354 object, and associates the given B<id>, B<flags>, B<pem_str> and
356 B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a
358 The following B<flags> are supported:
360 ASN1_PKEY_SIGPARAM_NULL
362 If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm
363 parameters are given the type B<V_ASN1_NULL> by default, otherwise
364 they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is
366 See L<X509_ALGOR_set0(3)> for more information.
368 EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from
370 This function is not thread safe, it's recommended to only use this
371 when initializing the application.
373 EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
376 EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of
377 methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is
379 This function is not thread safe, it's recommended to only use this
380 when initializing the application.
382 EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the
383 B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another
384 B<EVP_PKEY_ASN1_METHOD> with the same NID is already added.
385 This function is not thread safe, it's recommended to only use this
386 when initializing the application.
388 EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
389 EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
390 EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
391 EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
392 EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(),
393 EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key() and
394 EVP_PKEY_asn1_set_set_pub_key() set the diverse methods of the given
395 B<EVP_PKEY_ASN1_METHOD> object.
397 EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated
398 with the key B<pkey>.
402 EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
403 B<EVP_PKEY_ASN1_METHOD> object otherwise.
405 EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
408 EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
409 B<EVP_PKEY_ASN1_METHOD> object otherwise.
413 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
415 Licensed under the OpenSSL license (the "License"). You may not use
416 this file except in compliance with the License. You can obtain a copy
417 in the file LICENSE in the source distribution or at
418 L<https://www.openssl.org/source/license.html>.