doc/man3/EVP_PKEY_meth_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy, EVP_PKEY_meth_find,
   6 EVP_PKEY_meth_add0, EVP_PKEY_METHOD,
   7 EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup,
   8 EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign,
   9 EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx,
  10 EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt,
  11 EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, EVP_PKEY_meth_set_check,
  12 EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup,
  13 EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign,
  14 EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx,
  15 EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt,
  16 EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check
  17 - manipulating EVP_PKEY_METHOD structure
  18
  19 =head1 SYNOPSIS
  20
  21  #include <openssl/evp.h>
  22
  23  typedef struct evp_pkey_method_st EVP_PKEY_METHOD;
  24
  25  EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags);
  26  void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth);
  27  void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src);
  28  const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type);
  29  int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth);
  30
  31  void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth,
  32                              int (*init) (EVP_PKEY_CTX *ctx));
  33  void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth,
  34                              int (*copy) (EVP_PKEY_CTX *dst,
  35                                           EVP_PKEY_CTX *src));
  36  void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth,
  37                                 void (*cleanup) (EVP_PKEY_CTX *ctx));
  38  void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth,
  39                                  int (*paramgen_init) (EVP_PKEY_CTX *ctx),
  40                                  int (*paramgen) (EVP_PKEY_CTX *ctx,
  41                                                   EVP_PKEY *pkey));
  42  void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth,
  43                                int (*keygen_init) (EVP_PKEY_CTX *ctx),
  44                                int (*keygen) (EVP_PKEY_CTX *ctx,
  45                                               EVP_PKEY *pkey));
  46  void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth,
  47                              int (*sign_init) (EVP_PKEY_CTX *ctx),
  48                              int (*sign) (EVP_PKEY_CTX *ctx,
  49                                           unsigned char *sig, size_t *siglen,
  50                                           const unsigned char *tbs,
  51                                           size_t tbslen));
  52  void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth,
  53                                int (*verify_init) (EVP_PKEY_CTX *ctx),
  54                                int (*verify) (EVP_PKEY_CTX *ctx,
  55                                               const unsigned char *sig,
  56                                               size_t siglen,
  57                                               const unsigned char *tbs,
  58                                               size_t tbslen));
  59  void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,
  60                                        int (*verify_recover_init) (EVP_PKEY_CTX
  61                                                                    *ctx),
  62                                        int (*verify_recover) (EVP_PKEY_CTX
  63                                                               *ctx,
  64                                                               unsigned char
  65                                                               *sig,
  66                                                               size_t *siglen,
  67                                                               const unsigned
  68                                                               char *tbs,
  69                                                               size_t tbslen));
  70  void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,
  71                                 int (*signctx_init) (EVP_PKEY_CTX *ctx,
  72                                                      EVP_MD_CTX *mctx),
  73                                 int (*signctx) (EVP_PKEY_CTX *ctx,
  74                                                 unsigned char *sig,
  75                                                 size_t *siglen,
  76                                                 EVP_MD_CTX *mctx));
  77  void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,
  78                                   int (*verifyctx_init) (EVP_PKEY_CTX *ctx,
  79                                                          EVP_MD_CTX *mctx),
  80                                   int (*verifyctx) (EVP_PKEY_CTX *ctx,
  81                                                     const unsigned char *sig,
  82                                                     int siglen,
  83                                                     EVP_MD_CTX *mctx));
  84  void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth,
  85                                 int (*encrypt_init) (EVP_PKEY_CTX *ctx),
  86                                 int (*encryptfn) (EVP_PKEY_CTX *ctx,
  87                                                   unsigned char *out,
  88                                                   size_t *outlen,
  89                                                   const unsigned char *in,
  90                                                   size_t inlen));
  91  void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth,
  92                                 int (*decrypt_init) (EVP_PKEY_CTX *ctx),
  93                                 int (*decrypt) (EVP_PKEY_CTX *ctx,
  94                                                 unsigned char *out,
  95                                                 size_t *outlen,
  96                                                 const unsigned char *in,
  97                                                 size_t inlen));
  98  void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth,
  99                                int (*derive_init) (EVP_PKEY_CTX *ctx),
 100                                int (*derive) (EVP_PKEY_CTX *ctx,
 101                                               unsigned char *key,
 102                                               size_t *keylen));
 103  void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,
 104                              int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
 105                                           void *p2),
 106                              int (*ctrl_str) (EVP_PKEY_CTX *ctx,
 107                                               const char *type,
 108                                               const char *value));
 109  void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,
 110                               int (*check) (EVP_PKEY *pkey));
 111
 112  void EVP_PKEY_meth_get_init(EVP_PKEY_METHOD *pmeth,
 113                              int (**pinit) (EVP_PKEY_CTX *ctx));
 114  void EVP_PKEY_meth_get_copy(EVP_PKEY_METHOD *pmeth,
 115                              int (**pcopy) (EVP_PKEY_CTX *dst,
 116                                             EVP_PKEY_CTX *src));
 117  void EVP_PKEY_meth_get_cleanup(EVP_PKEY_METHOD *pmeth,
 118                                 void (**pcleanup) (EVP_PKEY_CTX *ctx));
 119  void EVP_PKEY_meth_get_paramgen(EVP_PKEY_METHOD *pmeth,
 120                                  int (**pparamgen_init) (EVP_PKEY_CTX *ctx),
 121                                  int (**pparamgen) (EVP_PKEY_CTX *ctx,
 122                                                     EVP_PKEY *pkey));
 123  void EVP_PKEY_meth_get_keygen(EVP_PKEY_METHOD *pmeth,
 124                                int (**pkeygen_init) (EVP_PKEY_CTX *ctx),
 125                                int (**pkeygen) (EVP_PKEY_CTX *ctx,
 126                                                 EVP_PKEY *pkey));
 127  void EVP_PKEY_meth_get_sign(EVP_PKEY_METHOD *pmeth,
 128                              int (**psign_init) (EVP_PKEY_CTX *ctx),
 129                              int (**psign) (EVP_PKEY_CTX *ctx,
 130                                             unsigned char *sig, size_t *siglen,
 131                                             const unsigned char *tbs,
 132                                             size_t tbslen));
 133  void EVP_PKEY_meth_get_verify(EVP_PKEY_METHOD *pmeth,
 134                                int (**pverify_init) (EVP_PKEY_CTX *ctx),
 135                                int (**pverify) (EVP_PKEY_CTX *ctx,
 136                                                 const unsigned char *sig,
 137                                                 size_t siglen,
 138                                                 const unsigned char *tbs,
 139                                                 size_t tbslen));
 140  void EVP_PKEY_meth_get_verify_recover(EVP_PKEY_METHOD *pmeth,
 141                                        int (**pverify_recover_init) (EVP_PKEY_CTX
 142                                                                      *ctx),
 143                                        int (**pverify_recover) (EVP_PKEY_CTX
 144                                                                 *ctx,
 145                                                                 unsigned char
 146                                                                 *sig,
 147                                                                 size_t *siglen,
 148                                                                 const unsigned
 149                                                                 char *tbs,
 150                                                                 size_t tbslen));
 151  void EVP_PKEY_meth_get_signctx(EVP_PKEY_METHOD *pmeth,
 152                                 int (**psignctx_init) (EVP_PKEY_CTX *ctx,
 153                                                        EVP_MD_CTX *mctx),
 154                                 int (**psignctx) (EVP_PKEY_CTX *ctx,
 155                                                   unsigned char *sig,
 156                                                   size_t *siglen,
 157                                                   EVP_MD_CTX *mctx));
 158  void EVP_PKEY_meth_get_verifyctx(EVP_PKEY_METHOD *pmeth,
 159                                   int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,
 160                                                            EVP_MD_CTX *mctx),
 161                                   int (**pverifyctx) (EVP_PKEY_CTX *ctx,
 162                                                       const unsigned char *sig,
 163                                                       int siglen,
 164                                                       EVP_MD_CTX *mctx));
 165  void EVP_PKEY_meth_get_encrypt(EVP_PKEY_METHOD *pmeth,
 166                                 int (**pencrypt_init) (EVP_PKEY_CTX *ctx),
 167                                 int (**pencryptfn) (EVP_PKEY_CTX *ctx,
 168                                                     unsigned char *out,
 169                                                     size_t *outlen,
 170                                                     const unsigned char *in,
 171                                                     size_t inlen));
 172  void EVP_PKEY_meth_get_decrypt(EVP_PKEY_METHOD *pmeth,
 173                                 int (**pdecrypt_init) (EVP_PKEY_CTX *ctx),
 174                                 int (**pdecrypt) (EVP_PKEY_CTX *ctx,
 175                                                   unsigned char *out,
 176                                                   size_t *outlen,
 177                                                   const unsigned char *in,
 178                                                   size_t inlen));
 179  void EVP_PKEY_meth_get_derive(EVP_PKEY_METHOD *pmeth,
 180                                int (**pderive_init) (EVP_PKEY_CTX *ctx),
 181                                int (**pderive) (EVP_PKEY_CTX *ctx,
 182                                                 unsigned char *key,
 183                                                 size_t *keylen));
 184  void EVP_PKEY_meth_get_ctrl(EVP_PKEY_METHOD *pmeth,
 185                              int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
 186                                             void *p2),
 187                              int (**pctrl_str) (EVP_PKEY_CTX *ctx,
 188                                                 const char *type,
 189                                                 const char *value));
 190  void EVP_PKEY_meth_get_check(EVP_PKEY_METHOD *pmeth,
 191                               int (**pcheck) (EVP_PKEY *pkey));
 192
 193 =head1 DESCRIPTION
 194
 195 B<EVP_PKEY_METHOD> is a structure which holds a set of methods for a
 196 specific public key cryptographic algorithm. Those methods are usually
 197 used to perform different jobs, such as generating a key, signing or
 198 verifying, encrypting or decrypting, etc.
 199
 200 There are two places where the B<EVP_PKEY_METHOD> objects are stored: one
 201 is a built-in static array representing the standard methods for different
 202 algorithms, and the other one is a stack of user-defined application-specific
 203 methods, which can be manipulated by using L<EVP_PKEY_meth_add0(3)>.
 204
 205 The B<EVP_PKEY_METHOD> objects are usually referenced by B<EVP_PKEY_CTX>
 206 objects.
 207
 208 =head2 Methods
 209
 210 The methods are the underlying implementations of a particular public key
 211 algorithm present by the B<EVP_PKEY_CTX> object.
 212
 213  int (*init) (EVP_PKEY_CTX *ctx);
 214  int (*copy) (EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src);
 215  void (*cleanup) (EVP_PKEY_CTX *ctx);
 216
 217 The init() method is called to initialize algorithm-specific data when a new
 218 B<EVP_PKEY_CTX> is created. As opposed to init(), the cleanup() method is called
 219 when an B<EVP_PKEY_CTX> is freed. The copy() method is called when an B<EVP_PKEY_CTX>
 220 is being duplicated. Refer to L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_id(3)>,
 221 L<EVP_PKEY_CTX_free(3)> and L<EVP_PKEY_CTX_dup(3)>.
 222
 223  int (*paramgen_init) (EVP_PKEY_CTX *ctx);
 224  int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
 225
 226 The paramgen_init() and paramgen() methods deal with key parameter generation.
 227 They are called by L<EVP_PKEY_paramgen_init(3)> and L<EVP_PKEY_paramgen(3)> to
 228 handle the parameter generation process.
 229
 230  int (*keygen_init) (EVP_PKEY_CTX *ctx);
 231  int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
 232
 233 The keygen_init() and keygen() methods are used to generate the actual key for
 234 the specified algorithm. They are called by L<EVP_PKEY_keygen_init(3)> and
 235 L<EVP_PKEY_keygen(3)>.
 236
 237  int (*sign_init) (EVP_PKEY_CTX *ctx);
 238  int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
 239               const unsigned char *tbs, size_t tbslen);
 240
 241 The sign_init() and sign() methods are used to generate the signature of a
 242 piece of data using a private key. They are called by L<EVP_PKEY_sign_init(3)>
 243 and L<EVP_PKEY_sign(3)>.
 244
 245  int (*verify_init) (EVP_PKEY_CTX *ctx);
 246  int (*verify) (EVP_PKEY_CTX *ctx,
 247                 const unsigned char *sig, size_t siglen,
 248                 const unsigned char *tbs, size_t tbslen);
 249
 250 The verify_init() and verify() methods are used to verify whether a signature is
 251 valid. They are called by L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
 252
 253  int (*verify_recover_init) (EVP_PKEY_CTX *ctx);
 254  int (*verify_recover) (EVP_PKEY_CTX *ctx,
 255                         unsigned char *rout, size_t *routlen,
 256                         const unsigned char *sig, size_t siglen);
 257
 258 The verify_recover_init() and verify_recover() methods are used to verify a
 259 signature and then recover the digest from the signature (for instance, a
 260 signature that was generated by RSA signing algorithm). They are called by
 261 L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
 262
 263  int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
 264  int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
 265                  EVP_MD_CTX *mctx);
 266
 267 The signctx_init() and signctx() methods are used to sign a digest present by
 268 a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See
 269 L<EVP_DigestSignInit(3)> for detail.
 270
 271  int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
 272  int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen,
 273                    EVP_MD_CTX *mctx);
 274
 275 The verifyctx_init() and verifyctx() methods are used to verify a signature
 276 against the data in a B<EVP_MD_CTX> object. They are called by the various
 277 EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for detail.
 278
 279  int (*encrypt_init) (EVP_PKEY_CTX *ctx);
 280  int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
 281                  const unsigned char *in, size_t inlen);
 282
 283 The encrypt_init() and encrypt() methods are used to encrypt a piece of data.
 284 They are called by L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)>.
 285
 286  int (*decrypt_init) (EVP_PKEY_CTX *ctx);
 287  int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
 288                  const unsigned char *in, size_t inlen);
 289
 290 The decrypt_init() and decrypt() methods are used to decrypt a piece of data.
 291 They are called by L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
 292
 293  int (*derive_init) (EVP_PKEY_CTX *ctx);
 294  int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
 295
 296 The derive_init() and derive() methods are used to derive the shared secret
 297 from a public key algorithm (for instance, the DH algorithm). They are called by
 298 L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>.
 299
 300  int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2);
 301  int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value);
 302
 303 The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
 304 settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail.
 305
 306  int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen,
 307                     const unsigned char *tbs, size_t tbslen);
 308  int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig,
 309                       size_t siglen, const unsigned char *tbs,
 310                       size_t tbslen);
 311
 312 The digestsign() and digestverify() methods are used to generate or verify
 313 a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)>
 314 and L<EVP_DigestVerify(3)>.
 315
 316  int (*check) (EVP_PKEY *pkey);
 317
 318 The check() method is used to validate a key-pair for a given B<pkey>. It
 319 could be called by L<EVP_PKEY_check(3)>.
 320
 321 =head2 Functions
 322
 323 EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object,
 324 and associates the given B<id> and B<flags>. The following flags are
 325 supported:
 326
 327  EVP_PKEY_FLAG_AUTOARGLEN
 328  EVP_PKEY_FLAG_SIGCTX_CUSTOM
 329
 330 If an B<EVP_PKEY_METHOD> is set with the B<EVP_PKEY_FLAG_AUTOARGLEN> flag, the
 331 maximum size of the output buffer will be automatically calculated or checked
 332 in corresponding EVP methods by the EVP framework. Thus the implementations of
 333 these methods don't need to care about handling the case of returning output
 334 buffer size by themselves. For details on the output buffer size, refer to
 335 L<EVP_PKEY_sign(3)>.
 336
 337 The B<EVP_PKEY_FLAG_SIGCTX_CUSTOM> is used to indicate the signctx() method
 338 of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a
 339 digest signing operation by calling L<EVP_DigestSignFinal(3)>.
 340
 341 EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by
 342 B<pmeth>.
 343
 344 EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src>
 345 to B<dst>.
 346
 347 EVP_PKEY_meth_find() finds an B<EVP_PKEY_METHOD> object with the B<id>.
 348 This function first searches through the user-defined method objects and
 349 then the built-in objects.
 350
 351 EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods.
 352
 353 The EVP_PKEY_meth_set functions set the corresponding fields of
 354 B<EVP_PKEY_METHOD> structure with the arguments passed.
 355
 356 The EVP_PKEY_meth_get functions get the corresponding fields of
 357 B<EVP_PKEY_METHOD> structure to the arguments provided.
 358
 359 =head1 RETURN VALUES
 360
 361 EVP_PKEY_meth_new() returns a pointer to a new B<EVP_PKEY_METHOD>
 362 object or returns NULL on error.
 363
 364 EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.
 365
 366 EVP_PKEY_meth_find() returns a pointer to the found B<EVP_PKEY_METHOD>
 367 object or returns NULL if not found.
 368
 369 EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0
 370 if an error occurred.
 371
 372 All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return
 373 values. For the 'get' functions, function pointers are returned by
 374 arguments.
 375
 376 =head1 COPYRIGHT
 377
 378 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
 379
 380 Licensed under the OpenSSL license (the "License").  You may not use
 381 this file except in compliance with the License.  You can obtain a copy
 382 in the file LICENSE in the source distribution or at
 383 L<https://www.openssl.org/source/license.html>.
 384
 385 =cut