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