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