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_get0_asn1
  23 - manipulating and registering EVP_PKEY_ASN1_METHOD structure
  24
  25 =head1 SYNOPSIS
  26
  27  #include <openssl/evp.h>
  28
  29  typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD;
  30
  31  EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags,
  32                                          const char *pem_str,
  33                                          const char *info);
  34  void EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst,
  35                          const EVP_PKEY_ASN1_METHOD *src);
  36  void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth);
  37  int EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth);
  38  int EVP_PKEY_asn1_add_alias(int to, int from);
  39
  40  void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth,
  41                                int (*pub_decode) (EVP_PKEY *pk,
  42                                                   X509_PUBKEY *pub),
  43                                int (*pub_encode) (X509_PUBKEY *pub,
  44                                                   const EVP_PKEY *pk),
  45                                int (*pub_cmp) (const EVP_PKEY *a,
  46                                                const EVP_PKEY *b),
  47                                int (*pub_print) (BIO *out,
  48                                                  const EVP_PKEY *pkey,
  49                                                  int indent, ASN1_PCTX *pctx),
  50                                int (*pkey_size) (const EVP_PKEY *pk),
  51                                int (*pkey_bits) (const EVP_PKEY *pk));
  52  void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth,
  53                                 int (*priv_decode) (EVP_PKEY *pk,
  54                                                     const PKCS8_PRIV_KEY_INFO
  55                                                     *p8inf),
  56                                 int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8,
  57                                                     const EVP_PKEY *pk),
  58                                 int (*priv_print) (BIO *out,
  59                                                    const EVP_PKEY *pkey,
  60                                                    int indent,
  61                                                    ASN1_PCTX *pctx));
  62  void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth,
  63                               int (*param_decode) (EVP_PKEY *pkey,
  64                                                    const unsigned char **pder,
  65                                                    int derlen),
  66                               int (*param_encode) (const EVP_PKEY *pkey,
  67                                                    unsigned char **pder),
  68                               int (*param_missing) (const EVP_PKEY *pk),
  69                               int (*param_copy) (EVP_PKEY *to,
  70                                                  const EVP_PKEY *from),
  71                               int (*param_cmp) (const EVP_PKEY *a,
  72                                                 const EVP_PKEY *b),
  73                               int (*param_print) (BIO *out,
  74                                                   const EVP_PKEY *pkey,
  75                                                   int indent,
  76                                                   ASN1_PCTX *pctx));
  77
  78  void EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth,
  79                              void (*pkey_free) (EVP_PKEY *pkey));
  80  void EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth,
  81                              int (*pkey_ctrl) (EVP_PKEY *pkey, int op,
  82                                                long arg1, void *arg2));
  83  void EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth,
  84                              int (*item_verify) (EVP_MD_CTX *ctx,
  85                                                  const ASN1_ITEM *it,
  86                                                  void *asn,
  87                                                  X509_ALGOR *a,
  88                                                  ASN1_BIT_STRING *sig,
  89                                                  EVP_PKEY *pkey),
  90                              int (*item_sign) (EVP_MD_CTX *ctx,
  91                                                const ASN1_ITEM *it,
  92                                                void *asn,
  93                                                X509_ALGOR *alg1,
  94                                                X509_ALGOR *alg2,
  95                                                ASN1_BIT_STRING *sig));
  96
  97  void EVP_PKEY_asn1_set_siginf(EVP_PKEY_ASN1_METHOD *ameth,
  98                                int (*siginf_set) (X509_SIG_INFO *siginf,
  99                                                   const X509_ALGOR *alg,
 100                                                   const ASN1_STRING *sig));
 101
 102  void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth,
 103                               int (*pkey_check) (const EVP_PKEY *pk));
 104
 105  void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth,
 106                                      int (*pkey_pub_check) (const EVP_PKEY *pk));
 107
 108  void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth,
 109                                     int (*pkey_param_check) (const EVP_PKEY *pk));
 110
 111  void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth,
 112                                       int (*pkey_security_bits) (const EVP_PKEY
 113                                                                  *pk));
 114
 115  const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey);
 116
 117 =head1 DESCRIPTION
 118
 119 B<EVP_PKEY_ASN1_METHOD> is a structure which holds a set of ASN.1
 120 conversion, printing and information methods for a specific public key
 121 algorithm.
 122
 123 There are two places where the B<EVP_PKEY_ASN1_METHOD> objects are
 124 stored: one is a built-in array representing the standard methods for
 125 different algorithms, and the other one is a stack of user-defined
 126 application-specific methods, which can be manipulated by using
 127 L<EVP_PKEY_asn1_add0(3)>.
 128
 129 =head2 Methods
 130
 131 The methods are the underlying implementations of a particular public
 132 key algorithm present by the B<EVP_PKEY> object.
 133
 134  int (*pub_decode) (EVP_PKEY *pk, X509_PUBKEY *pub);
 135  int (*pub_encode) (X509_PUBKEY *pub, const EVP_PKEY *pk);
 136  int (*pub_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);
 137  int (*pub_print) (BIO *out, const EVP_PKEY *pkey, int indent,
 138                    ASN1_PCTX *pctx);
 139
 140 The pub_decode() and pub_encode() methods are called to decode /
 141 encode B<X509_PUBKEY> ASN.1 parameters to / from B<pk>.
 142 They MUST return 0 on error, 1 on success.
 143 They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>.
 144
 145 The pub_cmp() method is called when two public keys are to be
 146 compared.
 147 It MUST return 1 when the keys are equal, 0 otherwise.
 148 It's called by L<EVP_PKEY_cmp(3)>.
 149
 150 The pub_print() method is called to print a public key in humanly
 151 readable text to B<out>, indented B<indent> spaces.
 152 It MUST return 0 on error, 1 on success.
 153 It's called by L<EVP_PKEY_print_public(3)>.
 154
 155  int (*priv_decode) (EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf);
 156  int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk);
 157  int (*priv_print) (BIO *out, const EVP_PKEY *pkey, int indent,
 158                     ASN1_PCTX *pctx);
 159
 160 The priv_decode() and priv_encode() methods are called to decode /
 161 encode B<PKCS8_PRIV_KEY_INFO> form private key to / from B<pk>.
 162 They MUST return 0 on error, 1 on success.
 163 They're called by L<EVP_PKCS82PKEY(3)> and L<EVP_PKEY2PKCS8(3)>.
 164
 165 The priv_print() method is called to print a private key in humanly
 166 readable text to B<out>, indented B<indent> spaces.
 167 It MUST return 0 on error, 1 on success.
 168 It's called by L<EVP_PKEY_print_private(3)>.
 169
 170  int (*pkey_size) (const EVP_PKEY *pk);
 171  int (*pkey_bits) (const EVP_PKEY *pk);
 172  int (*pkey_security_bits) (const EVP_PKEY *pk);
 173
 174 The pkey_size() method returns the key size in bytes.
 175 It's called by L<EVP_PKEY_size(3)>.
 176
 177 The pkey_bits() method returns the key size in bits.
 178 It's called by L<EVP_PKEY_bits(3)>.
 179
 180  int (*param_decode) (EVP_PKEY *pkey,
 181                       const unsigned char **pder, int derlen);
 182  int (*param_encode) (const EVP_PKEY *pkey, unsigned char **pder);
 183  int (*param_missing) (const EVP_PKEY *pk);
 184  int (*param_copy) (EVP_PKEY *to, const EVP_PKEY *from);
 185  int (*param_cmp) (const EVP_PKEY *a, const EVP_PKEY *b);
 186  int (*param_print) (BIO *out, const EVP_PKEY *pkey, int indent,
 187                      ASN1_PCTX *pctx);
 188
 189 The param_decode() and param_encode() methods are called to decode /
 190 encode DER formatted parameters to / from B<pk>.
 191 They MUST return 0 on error, 1 on success.
 192 They're called by L<PEM_read_bio_Parameters(3)> and the B<file:>
 193 L<OSSL_STORE_LOADER(3)>.
 194
 195 The param_missing() method returns 0 if a key parameter is missing,
 196 otherwise 1.
 197 It's called by L<EVP_PKEY_missing_parameters(3)>.
 198
 199 The param_copy() method copies key parameters from B<from> to B<to>.
 200 It MUST return 0 on error, 1 on success.
 201 It's called by L<EVP_PKEY_copy_parameters(3)>.
 202
 203 The param_cmp() method compares the parameters of keys B<a> and B<b>.
 204 It MUST return 1 when the keys are equal, 0 when not equal, or a
 205 negative number on error.
 206 It's called by L<EVP_PKEY_cmp_parameters(3)>.
 207
 208 The param_print() method prints the private key parameters in humanly
 209 readable text to B<out>, indented B<indent> spaces.
 210 It MUST return 0 on error, 1 on success.
 211 It's called by L<EVP_PKEY_print_params(3)>.
 212
 213  int (*sig_print) (BIO *out,
 214                    const X509_ALGOR *sigalg, const ASN1_STRING *sig,
 215                    int indent, ASN1_PCTX *pctx);
 216
 217 The sig_print() method prints a signature in humanly readable text to
 218 B<out>, indented B<indent> spaces.
 219 B<sigalg> contains the exact signature algorithm.
 220 If the signature in B<sig> doesn't correspond to what this method
 221 expects, X509_signature_dump() must be used as a last resort.
 222 It MUST return 0 on error, 1 on success.
 223 It's called by L<X509_signature_print(3)>.
 224
 225  void (*pkey_free) (EVP_PKEY *pkey);
 226
 227 The pkey_free() method helps freeing the internals of B<pkey>.
 228 It's called by L<EVP_PKEY_free(3)>, L<EVP_PKEY_set_type(3)>,
 229 L<EVP_PKEY_set_type_str(3)>, and L<EVP_PKEY_assign(3)>.
 230
 231  int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2);
 232
 233 The pkey_ctrl() method adds extra algorithm specific control.
 234 It's called by L<EVP_PKEY_get_default_digest_nid(3)>,
 235 L<EVP_PKEY_set1_tls_encodedpoint(3)>,
 236 L<EVP_PKEY_get1_tls_encodedpoint(3)>, L<PKCS7_SIGNER_INFO_set(3)>,
 237 L<PKCS7_RECIP_INFO_set(3)>, ...
 238
 239  int (*old_priv_decode) (EVP_PKEY *pkey,
 240                          const unsigned char **pder, int derlen);
 241  int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder);
 242
 243 The old_priv_decode() and old_priv_encode() methods decode / encode
 244 they private key B<pkey> from / to a DER formatted array.
 245 These are exclusively used to help decoding / encoding older (pre
 246 PKCS#8) PEM formatted encrypted private keys.
 247 old_priv_decode() MUST return 0 on error, 1 on success.
 248 old_priv_encode() MUST the return same kind of values as
 249 i2d_PrivateKey().
 250 They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>.
 251
 252  int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
 253                      X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey);
 254  int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn,
 255                    X509_ALGOR *alg1, X509_ALGOR *alg2,
 256                    ASN1_BIT_STRING *sig);
 257
 258 The item_sign() and  item_verify() methods make it possible to have
 259 algorithm specific signatures and verification of them.
 260
 261 item_sign() MUST return one of:
 262
 263 =over 4
 264
 265 =item <=0
 266
 267 error
 268
 269 =item Z<>1
 270
 271 item_sign() did everything, OpenSSL internals just needs to pass the
 272 signature length back.
 273
 274 =item Z<>2
 275
 276 item_sign() did nothing, OpenSSL internal standard routines are
 277 expected to continue with the default signature production.
 278
 279 =item Z<>3
 280
 281 item_sign() set the algorithm identifier B<algor1> and B<algor2>,
 282 OpenSSL internals should just sign using those algorithms.
 283
 284 =back
 285
 286 item_verify() MUST return one of:
 287
 288 =over 4
 289
 290 =item <=0
 291
 292 error
 293
 294 =item Z<>1
 295
 296 item_sign() did everything, OpenSSL internals just needs to pass the
 297 signature length back.
 298
 299 =item Z<>2
 300
 301 item_sign() did nothing, OpenSSL internal standard routines are
 302 expected to continue with the default signature production.
 303
 304 =back
 305
 306 item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and
 307 L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>,
 308 L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ...
 309
 310  int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg,
 311                     const ASN1_STRING *sig);
 312
 313 The siginf_set() method is used to set custom B<X509_SIG_INFO>
 314 parameters.
 315 It MUST return 0 on error, or 1 on success.
 316 It's called as part of L<X509_check_purpose(3)>, L<X509_check_ca(3)>
 317 and L<X509_check_issued(3)>.
 318
 319  int (*pkey_check) (const EVP_PKEY *pk);
 320  int (*pkey_public_check) (const EVP_PKEY *pk);
 321  int (*pkey_param_check) (const EVP_PKEY *pk);
 322
 323 The pkey_check(), pkey_public_check() and pkey_param_check() methods are used
 324 to check the validity of B<pk> for key-pair, public component and parameters,
 325 respectively.
 326 They MUST return 0 for an invalid key, or 1 for a valid key.
 327 They are called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
 328 L<EVP_PKEY_param_check(3)> respectively.
 329
 330 =head2 Functions
 331
 332 EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD>
 333 object, and associates the given B<id>, B<flags>, B<pem_str> and
 334 B<info>.
 335 B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a
 336 descriptive string.
 337 The following B<flags> are supported:
 338
 339  ASN1_PKEY_SIGPARAM_NULL
 340
 341 If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm
 342 parameters are given the type B<V_ASN1_NULL> by default, otherwise
 343 they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is
 344 omitted).
 345 See L<X509_ALGOR_set0(3)> for more information.
 346
 347 EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from
 348 B<src> to B<dst>.
 349 This function is not thread safe, it's recommended to only use this
 350 when initializing the application.
 351
 352 EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
 353 by B<ameth>.
 354
 355 EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of
 356 methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is
 357 already there.
 358 This function is not thread safe, it's recommended to only use this
 359 when initializing the application.
 360
 361 EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the
 362 B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another
 363 B<EVP_PKEY_ASN1_METHOD> with the same NID is already added.
 364 This function is not thread safe, it's recommended to only use this
 365 when initializing the application.
 366
 367 EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(),
 368 EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(),
 369 EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(),
 370 EVP_PKEY_asn1_set_siginf(), EVP_PKEY_asn1_set_check(),
 371 EVP_PKEY_asn1_set_public_check(), EVP_PKEY_asn1_set_param_check() and
 372 EVP_PKEY_asn1_set_security_bits() set the diverse methods of the given
 373 B<EVP_PKEY_ASN1_METHOD> object.
 374
 375 EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated
 376 with the key B<pkey>.
 377
 378 =head1 RETURN VALUES
 379
 380 EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an
 381 B<EVP_PKEY_ASN1_METHOD> object otherwise.
 382
 383 EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error,
 384 or 1 on success.
 385
 386 EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant
 387 B<EVP_PKEY_ASN1_METHOD> object otherwise.
 388
 389 =head1 COPYRIGHT
 390
 391 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
 392
 393 Licensed under the OpenSSL license (the "License").  You may not use
 394 this file except in compliance with the License.  You can obtain a copy
 395 in the file LICENSE in the source distribution or at
 396 L<https://www.openssl.org/source/license.html>.
 397
 398 =cut