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