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_set_digest_custom,
14 EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup,
15 EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign,
16 EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx,
17 EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt,
18 EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check,
19 EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check,
20 EVP_PKEY_meth_get_digest_custom,
22 - manipulating EVP_PKEY_METHOD structure
26 #include <openssl/evp.h>
28 typedef struct evp_pkey_method_st EVP_PKEY_METHOD;
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);
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,
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,
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,
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,
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,
63 const unsigned char *tbs,
65 void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,
66 int (*verify_recover_init) (EVP_PKEY_CTX
68 int (*verify_recover) (EVP_PKEY_CTX
76 void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,
77 int (*signctx_init) (EVP_PKEY_CTX *ctx,
79 int (*signctx) (EVP_PKEY_CTX *ctx,
83 void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,
84 int (*verifyctx_init) (EVP_PKEY_CTX *ctx,
86 int (*verifyctx) (EVP_PKEY_CTX *ctx,
87 const unsigned char *sig,
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,
95 const unsigned char *in,
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,
102 const unsigned char *in,
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,
109 void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,
110 int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
112 int (*ctrl_str) (EVP_PKEY_CTX *ctx,
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,
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,
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,
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,
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,
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,
151 const unsigned char *tbs,
153 void EVP_PKEY_meth_get_verify_recover(const EVP_PKEY_METHOD *pmeth,
154 int (**pverify_recover_init) (EVP_PKEY_CTX
156 int (**pverify_recover) (EVP_PKEY_CTX
164 void EVP_PKEY_meth_get_signctx(const EVP_PKEY_METHOD *pmeth,
165 int (**psignctx_init) (EVP_PKEY_CTX *ctx,
167 int (**psignctx) (EVP_PKEY_CTX *ctx,
171 void EVP_PKEY_meth_get_verifyctx(const EVP_PKEY_METHOD *pmeth,
172 int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,
174 int (**pverifyctx) (EVP_PKEY_CTX *ctx,
175 const unsigned char *sig,
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,
183 const unsigned char *in,
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,
190 const unsigned char *in,
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,
197 void EVP_PKEY_meth_get_ctrl(const EVP_PKEY_METHOD *pmeth,
198 int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
200 int (**pctrl_str) (EVP_PKEY_CTX *ctx,
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,
215 B<EVP_PKEY_METHOD> is a structure which holds a set of methods for a
216 specific public key cryptographic algorithm. Those methods are usually
217 used to perform different jobs, such as generating a key, signing or
218 verifying, encrypting or decrypting, etc.
220 There are two places where the B<EVP_PKEY_METHOD> objects are stored: one
221 is a built-in static array representing the standard methods for different
222 algorithms, and the other one is a stack of user-defined application-specific
223 methods, which can be manipulated by using L<EVP_PKEY_meth_add0(3)>.
225 The B<EVP_PKEY_METHOD> objects are usually referenced by B<EVP_PKEY_CTX>
230 The methods are the underlying implementations of a particular public key
231 algorithm present by the B<EVP_PKEY_CTX> object.
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);
237 The init() method is called to initialize algorithm-specific data when a new
238 B<EVP_PKEY_CTX> is created. As opposed to init(), the cleanup() method is called
239 when an B<EVP_PKEY_CTX> is freed. The copy() method is called when an B<EVP_PKEY_CTX>
240 is being duplicated. Refer to L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_id(3)>,
241 L<EVP_PKEY_CTX_free(3)> and L<EVP_PKEY_CTX_dup(3)>.
243 int (*paramgen_init) (EVP_PKEY_CTX *ctx);
244 int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
246 The paramgen_init() and paramgen() methods deal with key parameter generation.
247 They are called by L<EVP_PKEY_paramgen_init(3)> and L<EVP_PKEY_paramgen(3)> to
248 handle the parameter generation process.
250 int (*keygen_init) (EVP_PKEY_CTX *ctx);
251 int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
253 The keygen_init() and keygen() methods are used to generate the actual key for
254 the specified algorithm. They are called by L<EVP_PKEY_keygen_init(3)> and
255 L<EVP_PKEY_keygen(3)>.
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);
261 The sign_init() and sign() methods are used to generate the signature of a
262 piece of data using a private key. They are called by L<EVP_PKEY_sign_init(3)>
263 and L<EVP_PKEY_sign(3)>.
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);
270 The verify_init() and verify() methods are used to verify whether a signature is
271 valid. They are called by L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
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);
278 The verify_recover_init() and verify_recover() methods are used to verify a
279 signature and then recover the digest from the signature (for instance, a
280 signature that was generated by RSA signing algorithm). They are called by
281 L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
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,
287 The signctx_init() and signctx() methods are used to sign a digest present by
288 a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See
289 L<EVP_DigestSignInit(3)> for details.
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,
295 The verifyctx_init() and verifyctx() methods are used to verify a signature
296 against the data in a B<EVP_MD_CTX> object. They are called by the various
297 EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for details.
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);
303 The encrypt_init() and encrypt() methods are used to encrypt a piece of data.
304 They are called by L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)>.
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);
310 The decrypt_init() and decrypt() methods are used to decrypt a piece of data.
311 They are called by L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
313 int (*derive_init) (EVP_PKEY_CTX *ctx);
314 int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
316 The derive_init() and derive() methods are used to derive the shared secret
317 from a public key algorithm (for instance, the DH algorithm). They are called by
318 L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>.
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);
323 The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
324 settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for details.
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,
332 The digestsign() and digestverify() methods are used to generate or verify
333 a signature in a one-shot mode. They could be called by L<EVP_DigestSign(3)>
334 and L<EVP_DigestVerify(3)>.
336 int (*check) (EVP_PKEY *pkey);
337 int (*public_check) (EVP_PKEY *pkey);
338 int (*param_check) (EVP_PKEY *pkey);
340 The check(), public_check() and param_check() methods are used to validate a
341 key-pair, the public component and parameters respectively for a given B<pkey>.
342 They could be called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
343 L<EVP_PKEY_param_check(3)> respectively.
345 int (*digest_custom) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
347 The digest_custom() method is used to generate customized digest content before
348 the real message is passed to functions like L<EVP_DigestSignUpdate(3)> or
349 L<EVP_DigestVerifyInit(3)>. This is usually required by some public key
350 signature algorithms like SM2 which requires a hashed prefix to the message to
351 be signed. The digest_custom() function will be called by L<EVP_DigestSignInit(3)>
352 and L<EVP_DigestVerifyInit(3)>.
356 EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object,
357 and associates the given B<id> and B<flags>. The following flags are
360 EVP_PKEY_FLAG_AUTOARGLEN
361 EVP_PKEY_FLAG_SIGCTX_CUSTOM
363 If an B<EVP_PKEY_METHOD> is set with the B<EVP_PKEY_FLAG_AUTOARGLEN> flag, the
364 maximum size of the output buffer will be automatically calculated or checked
365 in corresponding EVP methods by the EVP framework. Thus the implementations of
366 these methods don't need to care about handling the case of returning output
367 buffer size by themselves. For details on the output buffer size, refer to
370 The B<EVP_PKEY_FLAG_SIGCTX_CUSTOM> is used to indicate the signctx() method
371 of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a
372 digest signing operation by calling L<EVP_DigestSignFinal(3)>.
374 EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by
377 EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src>
380 EVP_PKEY_meth_find() finds an B<EVP_PKEY_METHOD> object with the B<id>.
381 This function first searches through the user-defined method objects and
382 then the built-in objects.
384 EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods.
386 EVP_PKEY_meth_remove() removes an B<EVP_PKEY_METHOD> object added by
387 EVP_PKEY_meth_add0().
389 The EVP_PKEY_meth_set functions set the corresponding fields of
390 B<EVP_PKEY_METHOD> structure with the arguments passed.
392 The EVP_PKEY_meth_get functions get the corresponding fields of
393 B<EVP_PKEY_METHOD> structure to the arguments provided.
397 EVP_PKEY_meth_new() returns a pointer to a new B<EVP_PKEY_METHOD>
398 object or returns NULL on error.
400 EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.
402 EVP_PKEY_meth_find() returns a pointer to the found B<EVP_PKEY_METHOD>
403 object or returns NULL if not found.
405 EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0
406 if an error occurred.
408 EVP_PKEY_meth_remove() returns 1 if method is removed successfully or
409 0 if an error occurred.
411 All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return
412 values. For the 'get' functions, function pointers are returned by
417 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
419 Licensed under the Apache License 2.0 (the "License"). You may not use
420 this file except in compliance with the License. You can obtain a copy
421 in the file LICENSE in the source distribution or at
422 L<https://www.openssl.org/source/license.html>.