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_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, EVP_PKEY_meth_get_check,
18 - manipulating EVP_PKEY_METHOD structure
22 #include <openssl/evp.h>
24 typedef struct evp_pkey_method_st EVP_PKEY_METHOD;
26 EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags);
27 void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth);
28 void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src);
29 const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type);
30 int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth);
31 int EVP_PKEY_meth_remove(const EVP_PKEY_METHOD *pmeth);
33 void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth,
34 int (*init) (EVP_PKEY_CTX *ctx));
35 void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth,
36 int (*copy) (EVP_PKEY_CTX *dst,
38 void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth,
39 void (*cleanup) (EVP_PKEY_CTX *ctx));
40 void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth,
41 int (*paramgen_init) (EVP_PKEY_CTX *ctx),
42 int (*paramgen) (EVP_PKEY_CTX *ctx,
44 void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth,
45 int (*keygen_init) (EVP_PKEY_CTX *ctx),
46 int (*keygen) (EVP_PKEY_CTX *ctx,
48 void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth,
49 int (*sign_init) (EVP_PKEY_CTX *ctx),
50 int (*sign) (EVP_PKEY_CTX *ctx,
51 unsigned char *sig, size_t *siglen,
52 const unsigned char *tbs,
54 void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth,
55 int (*verify_init) (EVP_PKEY_CTX *ctx),
56 int (*verify) (EVP_PKEY_CTX *ctx,
57 const unsigned char *sig,
59 const unsigned char *tbs,
61 void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,
62 int (*verify_recover_init) (EVP_PKEY_CTX
64 int (*verify_recover) (EVP_PKEY_CTX
72 void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,
73 int (*signctx_init) (EVP_PKEY_CTX *ctx,
75 int (*signctx) (EVP_PKEY_CTX *ctx,
79 void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,
80 int (*verifyctx_init) (EVP_PKEY_CTX *ctx,
82 int (*verifyctx) (EVP_PKEY_CTX *ctx,
83 const unsigned char *sig,
86 void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth,
87 int (*encrypt_init) (EVP_PKEY_CTX *ctx),
88 int (*encryptfn) (EVP_PKEY_CTX *ctx,
91 const unsigned char *in,
93 void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth,
94 int (*decrypt_init) (EVP_PKEY_CTX *ctx),
95 int (*decrypt) (EVP_PKEY_CTX *ctx,
98 const unsigned char *in,
100 void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth,
101 int (*derive_init) (EVP_PKEY_CTX *ctx),
102 int (*derive) (EVP_PKEY_CTX *ctx,
105 void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,
106 int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
108 int (*ctrl_str) (EVP_PKEY_CTX *ctx,
111 void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,
112 int (*check) (EVP_PKEY *pkey));
114 void EVP_PKEY_meth_get_init(EVP_PKEY_METHOD *pmeth,
115 int (**pinit) (EVP_PKEY_CTX *ctx));
116 void EVP_PKEY_meth_get_copy(EVP_PKEY_METHOD *pmeth,
117 int (**pcopy) (EVP_PKEY_CTX *dst,
119 void EVP_PKEY_meth_get_cleanup(EVP_PKEY_METHOD *pmeth,
120 void (**pcleanup) (EVP_PKEY_CTX *ctx));
121 void EVP_PKEY_meth_get_paramgen(EVP_PKEY_METHOD *pmeth,
122 int (**pparamgen_init) (EVP_PKEY_CTX *ctx),
123 int (**pparamgen) (EVP_PKEY_CTX *ctx,
125 void EVP_PKEY_meth_get_keygen(EVP_PKEY_METHOD *pmeth,
126 int (**pkeygen_init) (EVP_PKEY_CTX *ctx),
127 int (**pkeygen) (EVP_PKEY_CTX *ctx,
129 void EVP_PKEY_meth_get_sign(EVP_PKEY_METHOD *pmeth,
130 int (**psign_init) (EVP_PKEY_CTX *ctx),
131 int (**psign) (EVP_PKEY_CTX *ctx,
132 unsigned char *sig, size_t *siglen,
133 const unsigned char *tbs,
135 void EVP_PKEY_meth_get_verify(EVP_PKEY_METHOD *pmeth,
136 int (**pverify_init) (EVP_PKEY_CTX *ctx),
137 int (**pverify) (EVP_PKEY_CTX *ctx,
138 const unsigned char *sig,
140 const unsigned char *tbs,
142 void EVP_PKEY_meth_get_verify_recover(EVP_PKEY_METHOD *pmeth,
143 int (**pverify_recover_init) (EVP_PKEY_CTX
145 int (**pverify_recover) (EVP_PKEY_CTX
153 void EVP_PKEY_meth_get_signctx(EVP_PKEY_METHOD *pmeth,
154 int (**psignctx_init) (EVP_PKEY_CTX *ctx,
156 int (**psignctx) (EVP_PKEY_CTX *ctx,
160 void EVP_PKEY_meth_get_verifyctx(EVP_PKEY_METHOD *pmeth,
161 int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,
163 int (**pverifyctx) (EVP_PKEY_CTX *ctx,
164 const unsigned char *sig,
167 void EVP_PKEY_meth_get_encrypt(EVP_PKEY_METHOD *pmeth,
168 int (**pencrypt_init) (EVP_PKEY_CTX *ctx),
169 int (**pencryptfn) (EVP_PKEY_CTX *ctx,
172 const unsigned char *in,
174 void EVP_PKEY_meth_get_decrypt(EVP_PKEY_METHOD *pmeth,
175 int (**pdecrypt_init) (EVP_PKEY_CTX *ctx),
176 int (**pdecrypt) (EVP_PKEY_CTX *ctx,
179 const unsigned char *in,
181 void EVP_PKEY_meth_get_derive(EVP_PKEY_METHOD *pmeth,
182 int (**pderive_init) (EVP_PKEY_CTX *ctx),
183 int (**pderive) (EVP_PKEY_CTX *ctx,
186 void EVP_PKEY_meth_get_ctrl(EVP_PKEY_METHOD *pmeth,
187 int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
189 int (**pctrl_str) (EVP_PKEY_CTX *ctx,
192 void EVP_PKEY_meth_get_check(EVP_PKEY_METHOD *pmeth,
193 int (**pcheck) (EVP_PKEY *pkey));
197 B<EVP_PKEY_METHOD> is a structure which holds a set of methods for a
198 specific public key cryptographic algorithm. Those methods are usually
199 used to perform different jobs, such as generating a key, signing or
200 verifying, encrypting or decrypting, etc.
202 There are two places where the B<EVP_PKEY_METHOD> objects are stored: one
203 is a built-in static array representing the standard methods for different
204 algorithms, and the other one is a stack of user-defined application-specific
205 methods, which can be manipulated by using L<EVP_PKEY_meth_add0(3)>.
207 The B<EVP_PKEY_METHOD> objects are usually referenced by B<EVP_PKEY_CTX>
212 The methods are the underlying implementations of a particular public key
213 algorithm present by the B<EVP_PKEY_CTX> object.
215 int (*init) (EVP_PKEY_CTX *ctx);
216 int (*copy) (EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src);
217 void (*cleanup) (EVP_PKEY_CTX *ctx);
219 The init() method is called to initialize algorithm-specific data when a new
220 B<EVP_PKEY_CTX> is created. As opposed to init(), the cleanup() method is called
221 when an B<EVP_PKEY_CTX> is freed. The copy() method is called when an B<EVP_PKEY_CTX>
222 is being duplicated. Refer to L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_id(3)>,
223 L<EVP_PKEY_CTX_free(3)> and L<EVP_PKEY_CTX_dup(3)>.
225 int (*paramgen_init) (EVP_PKEY_CTX *ctx);
226 int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
228 The paramgen_init() and paramgen() methods deal with key parameter generation.
229 They are called by L<EVP_PKEY_paramgen_init(3)> and L<EVP_PKEY_paramgen(3)> to
230 handle the parameter generation process.
232 int (*keygen_init) (EVP_PKEY_CTX *ctx);
233 int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
235 The keygen_init() and keygen() methods are used to generate the actual key for
236 the specified algorithm. They are called by L<EVP_PKEY_keygen_init(3)> and
237 L<EVP_PKEY_keygen(3)>.
239 int (*sign_init) (EVP_PKEY_CTX *ctx);
240 int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
241 const unsigned char *tbs, size_t tbslen);
243 The sign_init() and sign() methods are used to generate the signature of a
244 piece of data using a private key. They are called by L<EVP_PKEY_sign_init(3)>
245 and L<EVP_PKEY_sign(3)>.
247 int (*verify_init) (EVP_PKEY_CTX *ctx);
248 int (*verify) (EVP_PKEY_CTX *ctx,
249 const unsigned char *sig, size_t siglen,
250 const unsigned char *tbs, size_t tbslen);
252 The verify_init() and verify() methods are used to verify whether a signature is
253 valid. They are called by L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
255 int (*verify_recover_init) (EVP_PKEY_CTX *ctx);
256 int (*verify_recover) (EVP_PKEY_CTX *ctx,
257 unsigned char *rout, size_t *routlen,
258 const unsigned char *sig, size_t siglen);
260 The verify_recover_init() and verify_recover() methods are used to verify a
261 signature and then recover the digest from the signature (for instance, a
262 signature that was generated by RSA signing algorithm). They are called by
263 L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
265 int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
266 int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
269 The signctx_init() and signctx() methods are used to sign a digest present by
270 a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See
271 L<EVP_DigestSignInit(3)> for detail.
273 int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
274 int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen,
277 The verifyctx_init() and verifyctx() methods are used to verify a signature
278 against the data in a B<EVP_MD_CTX> object. They are called by the various
279 EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for detail.
281 int (*encrypt_init) (EVP_PKEY_CTX *ctx);
282 int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
283 const unsigned char *in, size_t inlen);
285 The encrypt_init() and encrypt() methods are used to encrypt a piece of data.
286 They are called by L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)>.
288 int (*decrypt_init) (EVP_PKEY_CTX *ctx);
289 int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
290 const unsigned char *in, size_t inlen);
292 The decrypt_init() and decrypt() methods are used to decrypt a piece of data.
293 They are called by L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
295 int (*derive_init) (EVP_PKEY_CTX *ctx);
296 int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
298 The derive_init() and derive() methods are used to derive the shared secret
299 from a public key algorithm (for instance, the DH algorithm). They are called by
300 L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>.
302 int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2);
303 int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value);
305 The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
306 settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail.
308 int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen,
309 const unsigned char *tbs, size_t tbslen);
310 int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig,
311 size_t siglen, const unsigned char *tbs,
314 The digestsign() and digestverify() methods are used to generate or verify
315 a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)>
316 and L<EVP_DigestVerify(3)>.
318 int (*check) (EVP_PKEY *pkey);
320 The check() method is used to validate a key-pair for a given B<pkey>. It
321 could be called by L<EVP_PKEY_check(3)>.
325 EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object,
326 and associates the given B<id> and B<flags>. The following flags are
329 EVP_PKEY_FLAG_AUTOARGLEN
330 EVP_PKEY_FLAG_SIGCTX_CUSTOM
332 If an B<EVP_PKEY_METHOD> is set with the B<EVP_PKEY_FLAG_AUTOARGLEN> flag, the
333 maximum size of the output buffer will be automatically calculated or checked
334 in corresponding EVP methods by the EVP framework. Thus the implementations of
335 these methods don't need to care about handling the case of returning output
336 buffer size by themselves. For details on the output buffer size, refer to
339 The B<EVP_PKEY_FLAG_SIGCTX_CUSTOM> is used to indicate the signctx() method
340 of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a
341 digest signing operation by calling L<EVP_DigestSignFinal(3)>.
343 EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by
346 EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src>
349 EVP_PKEY_meth_find() finds an B<EVP_PKEY_METHOD> object with the B<id>.
350 This function first searches through the user-defined method objects and
351 then the built-in objects.
353 EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods.
355 EVP_PKEY_meth_remove() removes an B<EVP_PKEY_METHOD> object added by
356 EVP_PKEY_meth_add0().
358 The EVP_PKEY_meth_set functions set the corresponding fields of
359 B<EVP_PKEY_METHOD> structure with the arguments passed.
361 The EVP_PKEY_meth_get functions get the corresponding fields of
362 B<EVP_PKEY_METHOD> structure to the arguments provided.
366 EVP_PKEY_meth_new() returns a pointer to a new B<EVP_PKEY_METHOD>
367 object or returns NULL on error.
369 EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.
371 EVP_PKEY_meth_find() returns a pointer to the found B<EVP_PKEY_METHOD>
372 object or returns NULL if not found.
374 EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0
375 if an error occurred.
377 EVP_PKEY_meth_remove() returns 1 if method is removed successfully or
378 0 if an error occurred.
380 All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return
381 values. For the 'get' functions, function pointers are returned by
386 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
388 Licensed under the OpenSSL license (the "License"). You may not use
389 this file except in compliance with the License. You can obtain a copy
390 in the file LICENSE in the source distribution or at
391 L<https://www.openssl.org/source/license.html>.