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