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
