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 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, 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_cmp(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_size(3)>. 201 202The pkey_bits() method returns the key size in bits. 203It's called by L<EVP_PKEY_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_cmp_parameters(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_tls_encodedpoint(3)>, 261L<EVP_PKEY_get1_tls_encodedpoint(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=head2 Functions 364 365EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD> 366object, and associates the given B<id>, B<flags>, B<pem_str> and 367B<info>. 368B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a 369descriptive string. 370The following B<flags> are supported: 371 372 ASN1_PKEY_SIGPARAM_NULL 373 374If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm 375parameters are given the type B<V_ASN1_NULL> by default, otherwise 376they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is 377omitted). 378See L<X509_ALGOR_set0(3)> for more information. 379 380EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from 381B<src> to B<dst>. 382This function is not thread safe, it's recommended to only use this 383when initializing the application. 384 385EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed 386by B<ameth>. 387 388EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of 389methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is 390already there. 391This function is not thread safe, it's recommended to only use this 392when initializing the application. 393 394EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the 395B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another 396B<EVP_PKEY_ASN1_METHOD> with the same NID is already added. 397This function is not thread safe, it's recommended to only use this 398when initializing the application. 399 400EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(), 401EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(), 402EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(), 403EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(), 404EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(), 405EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key(), 406EVP_PKEY_asn1_set_set_pub_key(), EVP_PKEY_asn1_set_get_priv_key() and 407EVP_PKEY_asn1_set_get_pub_key() set the diverse methods of the given 408B<EVP_PKEY_ASN1_METHOD> object. 409 410EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated 411with the key B<pkey>. 412 413=head1 RETURN VALUES 414 415EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an 416B<EVP_PKEY_ASN1_METHOD> object otherwise. 417 418EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error, 419or 1 on success. 420 421EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant 422B<EVP_PKEY_ASN1_METHOD> object otherwise. 423 424=head1 COPYRIGHT 425 426Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. 427 428Licensed under the OpenSSL license (the "License"). You may not use 429this file except in compliance with the License. You can obtain a copy 430in the file LICENSE in the source distribution or at 431L<https://www.openssl.org/source/license.html>. 432 433=cut 434