doc/man3/EVP_PKEY_ASN1_METHOD.pod

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