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