doc/man3/EVP_PKEY_ASN1_METHOD.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_ASN1_METHOD,
   6 EVP_PKEY_asn1_new,
   7 EVP_PKEY_asn1_copy,
   8 EVP_PKEY_asn1_free,
   9 EVP_PKEY_asn1_add0,
  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_get0_asn1
  25 - manipulating and registering EVP_PKEY_ASN1_METHOD structure
  26
  27 =head1 SYNOPSIS
  28
  29  #include <openssl/evp.h>
  30
  31  typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;
  32
  33  EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags,
  34                                          const char *pem_str,
  35                                          const char *info);
  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);
  41
  42  void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,
  43                                int (*pub_decode) (EVP_PKEY *pk,
  44                                                   X509_PUBKEY *pub),
  45                                int (*pub_encode) (X509_PUBKEY *pub,
  46                                                   const EVP_PKEY *pk),
  47                                int (*pub_cmp) (const EVP_PKEY *a,
  48                                                const EVP_PKEY *b),
  49                                int (*pub_print) (BIO *out,
  50                                                  const EVP_PKEY *pkey,
  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
  57                                                     *p8inf),
  58                                 int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8,
  59                                                     const EVP_PKEY *pk),
  60                                 int (*priv_print) (BIO *out,
  61                                                    const EVP_PKEY *pkey,
  62                                                    int indent,
  63                                                    ASN1_PCTX *pctx));
  64  void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth,
  65                               int (*param_decode) (EVP_PKEY *pkey,
  66                                                    const unsigned char **pder,
  67                                                    int derlen),
  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,
  74                                                 const EVP_PKEY *b),
  75                               int (*param_print) (BIO *out,
  76                                                   const EVP_PKEY *pkey,
  77                                                   int indent,
  78                                                   ASN1_PCTX *pctx));
  79
  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,
  87                                                  const ASN1_ITEM *it,
  88                                                  void *asn,
  89                                                  X509_ALGOR *a,
  90                                                  ASN1_BIT_STRING *sig,
  91                                                  EVP_PKEY *pkey),
  92                              int (*item_sign) (EVP_MD_CTX *ctx,
  93                                                const ASN1_ITEM *it,
  94                                                void *asn,
  95                                                X509_ALGOR *alg1,
  96                                                X509_ALGOR *alg2,
  97                                                ASN1_BIT_STRING *sig));
  98
  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));
 103
 104  void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,
 105                               int (*pkey_check) (const EVP_PKEY *pk));
 106
 107  void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,
 108                                      int (*pkey_pub_check) (const EVP_PKEY *pk));
 109
 110  void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,
 111                                     int (*pkey_param_check) (const EVP_PKEY *pk));
 112
 113  void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
 114                                       int (*pkey_security_bits) (const EVP_PKEY
 115                                                                  *pk));
 116
 117  void EVP_PKEY_asn1_set_set_priv_key(EVP_PKEY_ASN1_METHOD *ameth,
 118                                      int (*set_priv_key) (EVP_PKEY *pk,
 119                                                           const unsigned char
 120                                                              *priv,
 121                                                           size_t len));
 122
 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,
 126                                                         size_t len));
 127
 128  const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);
 129
 130 =head1 DESCRIPTION
 131
 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
 134 algorithm.
 135
 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)>.
 141
 142 =head2 Methods
 143
 144 The methods are the underlying implementations of a particular public
 145 key algorithm present by the B<EVP_PKEY> object.
 146
 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,
 151                    ASN1_PCTX *pctx);
 152
 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)>.
 157
 158 The pub_cmp() method is called when two public keys are to be
 159 compared.
 160 It MUST return 1 when the keys are equal, 0 otherwise.
 161 It's called by L<EVP_PKEY_cmp(3)>.
 162
 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)>.
 167
 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,
 171                     ASN1_PCTX *pctx);
 172
 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)>.
 177
 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)>.
 182
 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);
 186
 187 The pkey_size() method returns the key size in bytes.
 188 It's called by L<EVP_PKEY_size(3)>.
 189
 190 The pkey_bits() method returns the key size in bits.
 191 It's called by L<EVP_PKEY_bits(3)>.
 192
 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,
 200                      ASN1_PCTX *pctx);
 201
 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)>.
 207
 208 The param_missing() method returns 0 if a key parameter is missing,
 209 otherwise 1.
 210 It's called by L<EVP_PKEY_missing_parameters(3)>.
 211
 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)>.
 215
 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)>.
 220
 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)>.
 225
 226  int (*sig_print) (BIO *out,
 227                    const X509_ALGOR *sigalg, const ASN1_STRING *sig,
 228                    int indent, ASN1_PCTX *pctx);
 229
 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)>.
 237
 238  void (*pkey_free) (EVP_PKEY *pkey);
 239
 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)>.
 243
 244  int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);
 245
 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)>, ...
 251
 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);
 255
 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
 262 i2d_PrivateKey().
 263 They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>.
 264
 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);
 270
 271 The item_sign() and  item_verify() methods make it possible to have
 272 algorithm specific signatures and verification of them.
 273
 274 item_sign() MUST return one of:
 275
 276 =over 4
 277
 278 =item <=0
 279
 280 error
 281
 282 =item Z<>1
 283
 284 item_sign() did everything, OpenSSL internals just needs to pass the
 285 signature length back.
 286
 287 =item Z<>2
 288
 289 item_sign() did nothing, OpenSSL internal standard routines are
 290 expected to continue with the default signature production.
 291
 292 =item Z<>3
 293
 294 item_sign() set the algorithm identifier B<algor1> and B<algor2>,
 295 OpenSSL internals should just sign using those algorithms.
 296
 297 =back
 298
 299 item_verify() MUST return one of:
 300
 301 =over 4
 302
 303 =item <=0
 304
 305 error
 306
 307 =item Z<>1
 308
 309 item_sign() did everything, OpenSSL internals just needs to pass the
 310 signature length back.
 311
 312 =item Z<>2
 313
 314 item_sign() did nothing, OpenSSL internal standard routines are
 315 expected to continue with the default signature production.
 316
 317 =back
 318
 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)>, ...
 322
 323  int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
 324                     const ASN1_STRING *sig);
 325
 326 The siginf_set() method is used to set custom B<X509_SIG_INFO>
 327 parameters.
 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)>.
 331
 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);
 335
 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,
 338 respectively.
 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.
 342
 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);
 345
 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_private_key(3)>, and
 349 L<EVP_PKEY_new_public_key(3)> respectively.
 350
 351 =head2 Functions
 352
 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
 355 B<info>.
 356 B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a
 357 descriptive string.
 358 The following B<flags> are supported:
 359
 360  ASN1_PKEY_SIGPARAM_NULL
 361
 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
 365 omitted).
 366 See L<X509_ALGOR_set0(3)> for more information.
 367
 368 EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from
 369 B<src> to B<dst>.
 370 This function is not thread safe, it's recommended to only use this
 371 when initializing the application.
 372
 373 EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
 374 by B<ameth>.
 375
 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
 378 already there.
 379 This function is not thread safe, it's recommended to only use this
 380 when initializing the application.
 381
 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.
 387
 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.
 396
 397 EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated
 398 with the key B<pkey>.
 399
 400 =head1 RETURN VALUES
 401
 402 EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
 403 B<EVP_PKEY_ASN1_METHOD> object otherwise.
 404
 405 EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
 406 or 1 on success.
 407
 408 EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
 409 B<EVP_PKEY_ASN1_METHOD> object otherwise.
 410
 411 =head1 COPYRIGHT
 412
 413 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
 414
 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>.
 419
 420 =cut