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