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_asn1_set_get_priv_key,
  25 EVP_PKEY_asn1_set_get_pub_key,
  26 EVP_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
 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
 146 algorithm.
 147
 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)>.
 153
 154 =head2 Methods
 155
 156 The methods are the underlying implementations of a particular public
 157 key 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
 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)>.
 169
 170 The pub_cmp() method is called when two public keys are to be
 171 compared.
 172 It MUST return 1 when the keys are equal, 0 otherwise.
 173 It's called by L<EVP_PKEY_cmp(3)>.
 174
 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)>.
 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
 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)>.
 189
 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)>.
 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
 199 The pkey_size() method returns the key size in bytes.
 200 It's called by L<EVP_PKEY_size(3)>.
 201
 202 The pkey_bits() method returns the key size in bits.
 203 It'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
 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)>.
 219
 220 The param_missing() method returns 0 if a key parameter is missing,
 221 otherwise 1.
 222 It's called by L<EVP_PKEY_missing_parameters(3)>.
 223
 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)>.
 227
 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)>.
 232
 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)>.
 237
 238  int (*sig_print) (BIO *out,
 239                    const X509_ALGOR *sigalg, const ASN1_STRING *sig,
 240                    int indent, ASN1_PCTX *pctx);
 241
 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)>.
 249
 250  void (*pkey_free) (EVP_PKEY *pkey);
 251
 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)>.
 255
 256  int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);
 257
 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_supports_digest_nid(3)>,
 261 L<EVP_PKEY_set1_tls_encodedpoint(3)>,
 262 L<EVP_PKEY_get1_tls_encodedpoint(3)>, L<PKCS7_SIGNER_INFO_set(3)>,
 263 L<PKCS7_RECIP_INFO_set(3)>, ...
 264
 265  int (*old_priv_decode) (EVP_PKEY *pkey,
 266                          const unsigned char **pder, int derlen);
 267  int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder);
 268
 269 The old_priv_decode() and old_priv_encode() methods decode / encode
 270 they private key B<pkey> from / to a DER formatted array.
 271 These are exclusively used to help decoding / encoding older (pre
 272 PKCS#8) PEM formatted encrypted private keys.
 273 old_priv_decode() MUST return 0 on error, 1 on success.
 274 old_priv_encode() MUST the return same kind of values as
 275 i2d_PrivateKey().
 276 They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>.
 277
 278  int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
 279                      X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey);
 280  int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
 281                    X509_ALGOR *alg1, X509_ALGOR *alg2,
 282                    ASN1_BIT_STRING *sig);
 283
 284 The item_sign() and  item_verify() methods make it possible to have
 285 algorithm specific signatures and verification of them.
 286
 287 item_sign() MUST return one of:
 288
 289 =over 4
 290
 291 =item <=0
 292
 293 error
 294
 295 =item Z<>1
 296
 297 item_sign() did everything, OpenSSL internals just needs to pass the
 298 signature length back.
 299
 300 =item Z<>2
 301
 302 item_sign() did nothing, OpenSSL internal standard routines are
 303 expected to continue with the default signature production.
 304
 305 =item Z<>3
 306
 307 item_sign() set the algorithm identifier B<algor1> and B<algor2>,
 308 OpenSSL internals should just sign using those algorithms.
 309
 310 =back
 311
 312 item_verify() MUST return one of:
 313
 314 =over 4
 315
 316 =item <=0
 317
 318 error
 319
 320 =item Z<>1
 321
 322 item_sign() did everything, OpenSSL internals just needs to pass the
 323 signature length back.
 324
 325 =item Z<>2
 326
 327 item_sign() did nothing, OpenSSL internal standard routines are
 328 expected to continue with the default signature production.
 329
 330 =back
 331
 332 item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and
 333 L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>,
 334 L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ...
 335
 336  int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
 337                     const ASN1_STRING *sig);
 338
 339 The siginf_set() method is used to set custom B<X509_SIG_INFO>
 340 parameters.
 341 It MUST return 0 on error, or 1 on success.
 342 It's called as part of L<X509_check_purpose(3)>, L<X509_check_ca(3)>
 343 and L<X509_check_issued(3)>.
 344
 345  int (*pkey_check) (const EVP_PKEY *pk);
 346  int (*pkey_public_check) (const EVP_PKEY *pk);
 347  int (*pkey_param_check) (const EVP_PKEY *pk);
 348
 349 The pkey_check(), pkey_public_check() and pkey_param_check() methods are used
 350 to check the validity of B<pk> for key-pair, public component and parameters,
 351 respectively.
 352 They MUST return 0 for an invalid key, or 1 for a valid key.
 353 They are called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
 354 L<EVP_PKEY_param_check(3)> respectively.
 355
 356  int (*set_priv_key) (EVP_PKEY *pk, const unsigned char *priv, size_t len);
 357  int (*set_pub_key) (EVP_PKEY *pk, const unsigned char *pub, size_t len);
 358
 359 The set_priv_key() and set_pub_key() methods are used to set the raw private and
 360 public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success.
 361 They are called by L<EVP_PKEY_new_raw_private_key(3)>, and
 362 L<EVP_PKEY_new_raw_public_key(3)> respectively.
 363
 364  size_t (*dirty) (const EVP_PKEY *pk);
 365  void *(*export_to) (const EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
 366
 367 dirty_cnt() returns the internal key's dirty count.
 368 This can be used to synchronise different copies of the same keys.
 369
 370 The export_to() method exports the key material from the given key to
 371 a provider, through the L<EVP_KEYMGMT(3)> interface, if that provider
 372 supports importing key material.
 373
 374 =head2 Functions
 375
 376 EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD>
 377 object, and associates the given B<id>, B<flags>, B<pem_str> and
 378 B<info>.
 379 B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a
 380 descriptive string.
 381 The following B<flags> are supported:
 382
 383  ASN1_PKEY_SIGPARAM_NULL
 384
 385 If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm
 386 parameters are given the type B<V_ASN1_NULL> by default, otherwise
 387 they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is
 388 omitted).
 389 See L<X509_ALGOR_set0(3)> for more information.
 390
 391 EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from
 392 B<src> to B<dst>.
 393 This function is not thread safe, it's recommended to only use this
 394 when initializing the application.
 395
 396 EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
 397 by B<ameth>.
 398
 399 EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of
 400 methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is
 401 already there.
 402 This function is not thread safe, it's recommended to only use this
 403 when initializing the application.
 404
 405 EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the
 406 B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another
 407 B<EVP_PKEY_ASN1_METHOD> with the same NID is already added.
 408 This function is not thread safe, it's recommended to only use this
 409 when initializing the application.
 410
 411 EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
 412 EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
 413 EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
 414 EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
 415 EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check(),
 416 EVP_PKEY_asn1_set_security_bits(), EVP_PKEY_asn1_set_set_priv_key(),
 417 EVP_PKEY_asn1_set_set_pub_key(), EVP_PKEY_asn1_set_get_priv_key() and
 418 EVP_PKEY_asn1_set_get_pub_key() set the diverse methods of the given
 419 B<EVP_PKEY_ASN1_METHOD> object.
 420
 421 EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated
 422 with the key B<pkey>.
 423
 424 =head1 RETURN VALUES
 425
 426 EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
 427 B<EVP_PKEY_ASN1_METHOD> object otherwise.
 428
 429 EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
 430 or 1 on success.
 431
 432 EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
 433 B<EVP_PKEY_ASN1_METHOD> object otherwise.
 434
 435 =head1 COPYRIGHT
 436
 437 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
 438
 439 Licensed under the Apache License 2.0 (the "License").  You may not use
 440 this file except in compliance with the License.  You can obtain a copy
 441 in the file LICENSE in the source distribution or at
 442 L<https://www.openssl.org/source/license.html>.
 443
 444 =cut