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