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,
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
17 - manipulating EVP_PKEY_METHOD structure
21 #include <openssl/evp.h>
23 typedef struct evp_pkey_method_st EVP_PKEY_METHOD;
25 EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags);
26 void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth);
27 void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src);
28 const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type);
29 int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth);
31 void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth,
32 int (*init) (EVP_PKEY_CTX *ctx));
33 void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth,
34 int (*copy) (EVP_PKEY_CTX *dst,
36 void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth,
37 void (*cleanup) (EVP_PKEY_CTX *ctx));
38 void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth,
39 int (*paramgen_init) (EVP_PKEY_CTX *ctx),
40 int (*paramgen) (EVP_PKEY_CTX *ctx,
42 void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth,
43 int (*keygen_init) (EVP_PKEY_CTX *ctx),
44 int (*keygen) (EVP_PKEY_CTX *ctx,
46 void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth,
47 int (*sign_init) (EVP_PKEY_CTX *ctx),
48 int (*sign) (EVP_PKEY_CTX *ctx,
49 unsigned char *sig, size_t *siglen,
50 const unsigned char *tbs,
52 void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth,
53 int (*verify_init) (EVP_PKEY_CTX *ctx),
54 int (*verify) (EVP_PKEY_CTX *ctx,
55 const unsigned char *sig,
57 const unsigned char *tbs,
59 void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,
60 int (*verify_recover_init) (EVP_PKEY_CTX
62 int (*verify_recover) (EVP_PKEY_CTX
70 void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,
71 int (*signctx_init) (EVP_PKEY_CTX *ctx,
73 int (*signctx) (EVP_PKEY_CTX *ctx,
77 void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,
78 int (*verifyctx_init) (EVP_PKEY_CTX *ctx,
80 int (*verifyctx) (EVP_PKEY_CTX *ctx,
81 const unsigned char *sig,
84 void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth,
85 int (*encrypt_init) (EVP_PKEY_CTX *ctx),
86 int (*encryptfn) (EVP_PKEY_CTX *ctx,
89 const unsigned char *in,
91 void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth,
92 int (*decrypt_init) (EVP_PKEY_CTX *ctx),
93 int (*decrypt) (EVP_PKEY_CTX *ctx,
96 const unsigned char *in,
98 void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth,
99 int (*derive_init) (EVP_PKEY_CTX *ctx),
100 int (*derive) (EVP_PKEY_CTX *ctx,
103 void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,
104 int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
106 int (*ctrl_str) (EVP_PKEY_CTX *ctx,
110 void EVP_PKEY_meth_get_init(EVP_PKEY_METHOD *pmeth,
111 int (**pinit) (EVP_PKEY_CTX *ctx));
112 void EVP_PKEY_meth_get_copy(EVP_PKEY_METHOD *pmeth,
113 int (**pcopy) (EVP_PKEY_CTX *dst,
115 void EVP_PKEY_meth_get_cleanup(EVP_PKEY_METHOD *pmeth,
116 void (**pcleanup) (EVP_PKEY_CTX *ctx));
117 void EVP_PKEY_meth_get_paramgen(EVP_PKEY_METHOD *pmeth,
118 int (**pparamgen_init) (EVP_PKEY_CTX *ctx),
119 int (**pparamgen) (EVP_PKEY_CTX *ctx,
121 void EVP_PKEY_meth_get_keygen(EVP_PKEY_METHOD *pmeth,
122 int (**pkeygen_init) (EVP_PKEY_CTX *ctx),
123 int (**pkeygen) (EVP_PKEY_CTX *ctx,
125 void EVP_PKEY_meth_get_sign(EVP_PKEY_METHOD *pmeth,
126 int (**psign_init) (EVP_PKEY_CTX *ctx),
127 int (**psign) (EVP_PKEY_CTX *ctx,
128 unsigned char *sig, size_t *siglen,
129 const unsigned char *tbs,
131 void EVP_PKEY_meth_get_verify(EVP_PKEY_METHOD *pmeth,
132 int (**pverify_init) (EVP_PKEY_CTX *ctx),
133 int (**pverify) (EVP_PKEY_CTX *ctx,
134 const unsigned char *sig,
136 const unsigned char *tbs,
138 void EVP_PKEY_meth_get_verify_recover(EVP_PKEY_METHOD *pmeth,
139 int (**pverify_recover_init) (EVP_PKEY_CTX
141 int (**pverify_recover) (EVP_PKEY_CTX
149 void EVP_PKEY_meth_get_signctx(EVP_PKEY_METHOD *pmeth,
150 int (**psignctx_init) (EVP_PKEY_CTX *ctx,
152 int (**psignctx) (EVP_PKEY_CTX *ctx,
156 void EVP_PKEY_meth_get_verifyctx(EVP_PKEY_METHOD *pmeth,
157 int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,
159 int (**pverifyctx) (EVP_PKEY_CTX *ctx,
160 const unsigned char *sig,
163 void EVP_PKEY_meth_get_encrypt(EVP_PKEY_METHOD *pmeth,
164 int (**pencrypt_init) (EVP_PKEY_CTX *ctx),
165 int (**pencryptfn) (EVP_PKEY_CTX *ctx,
168 const unsigned char *in,
170 void EVP_PKEY_meth_get_decrypt(EVP_PKEY_METHOD *pmeth,
171 int (**pdecrypt_init) (EVP_PKEY_CTX *ctx),
172 int (**pdecrypt) (EVP_PKEY_CTX *ctx,
175 const unsigned char *in,
177 void EVP_PKEY_meth_get_derive(EVP_PKEY_METHOD *pmeth,
178 int (**pderive_init) (EVP_PKEY_CTX *ctx),
179 int (**pderive) (EVP_PKEY_CTX *ctx,
182 void EVP_PKEY_meth_get_ctrl(EVP_PKEY_METHOD *pmeth,
183 int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
185 int (**pctrl_str) (EVP_PKEY_CTX *ctx,
191 B<EVP_PKEY_METHOD> is a structure which holds a set of methods for a
192 specific public key cryptographic algorithm. Those methods are usually
193 used to perform different jobs, such as generating a key, signing or
194 verifying, encrypting or decrypting, etc.
196 There are two places where the B<EVP_PKEY_METHOD> objects are stored: one
197 is a built-in static array representing the standard methods for different
198 algorithms, and the other one is a stack of user-defined application-specific
199 methods, which can be manipulated by using L<EVP_PKEY_meth_add0(3)>.
201 The B<EVP_PKEY_METHOD> objects are usually referenced by B<EVP_PKEY_CTX>
206 The methods are the underlying implementations of a particular public key
207 algorithm present by the B<EVP_PKEY_CTX> object.
209 int (*init) (EVP_PKEY_CTX *ctx);
210 int (*copy) (EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src);
211 void (*cleanup) (EVP_PKEY_CTX *ctx);
213 The init() method is called to initialize algorithm-specific data when a new
214 B<EVP_PKEY_CTX> is created. As opposed to init(), the cleanup() method is called
215 when an B<EVP_PKEY_CTX> is freed. The copy() method is called when an B<EVP_PKEY_CTX>
216 is being duplicated. Refer to L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_id(3)>,
217 L<EVP_PKEY_CTX_free(3)> and L<EVP_PKEY_CTX_dup(3)>.
219 int (*paramgen_init) (EVP_PKEY_CTX *ctx);
220 int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
222 The paramgen_init() and paramgen() methods deal with key parameter generation.
223 They are called by L<EVP_PKEY_paramgen_init(3)> and L<EVP_PKEY_paramgen(3)> to
224 handle the parameter generation process.
226 int (*keygen_init) (EVP_PKEY_CTX *ctx);
227 int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
229 The keygen_init() and keygen() methods are used to generate the actual key for
230 the specified algorithm. They are called by L<EVP_PKEY_keygen_init(3)> and
231 L<EVP_PKEY_keygen(3)>.
233 int (*sign_init) (EVP_PKEY_CTX *ctx);
234 int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
235 const unsigned char *tbs, size_t tbslen);
237 The sign_init() and sign() methods are used to generate the signature of a
238 piece of data using a private key. They are called by L<EVP_PKEY_sign_init(3)>
239 and L<EVP_PKEY_sign(3)>.
241 int (*verify_init) (EVP_PKEY_CTX *ctx);
242 int (*verify) (EVP_PKEY_CTX *ctx,
243 const unsigned char *sig, size_t siglen,
244 const unsigned char *tbs, size_t tbslen);
246 The verify_init() and verify() methods are used to verify whether a signature is
247 valid. They are called by L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
249 int (*verify_recover_init) (EVP_PKEY_CTX *ctx);
250 int (*verify_recover) (EVP_PKEY_CTX *ctx,
251 unsigned char *rout, size_t *routlen,
252 const unsigned char *sig, size_t siglen);
254 The verify_recover_init() and verify_recover() methods are used to verify a
255 signature and then recover the digest from the signature (for instance, a
256 signature that was generated by RSA signing algorithm). They are called by
257 L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
259 int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
260 int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
263 The signctx_init() and signctx() methods are used to sign a digest present by
264 a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See
265 L<EVP_DigestSignInit(3)> for detail.
267 int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
268 int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen,
271 The verifyctx_init() and verifyctx() methods are used to verify a signature
272 against the data in a B<EVP_MD_CTX> object. They are called by the various
273 EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for detail.
275 int (*encrypt_init) (EVP_PKEY_CTX *ctx);
276 int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
277 const unsigned char *in, size_t inlen);
279 The encrypt_init() and encrypt() methods are used to encrypt a piece of data.
280 They are called by L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)>.
282 int (*decrypt_init) (EVP_PKEY_CTX *ctx);
283 int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
284 const unsigned char *in, size_t inlen);
286 The decrypt_init() and decrypt() methods are used to decrypt a piece of data.
287 They are called by L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
289 int (*derive_init) (EVP_PKEY_CTX *ctx);
290 int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
292 The derive_init() and derive() methods are used to derive the shared secret
293 from a public key algorithm (for instance, the DH algorithm). They are called by
294 L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>.
296 int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2);
297 int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value);
299 The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
300 settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail.
302 int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen,
303 const unsigned char *tbs, size_t tbslen);
304 int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig,
305 size_t siglen, const unsigned char *tbs,
308 The digestsign() and digestverify() methods are used to generate or verify
309 a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)>
310 and L<EVP_DigestVerify(3)>.
314 EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object,
315 and associates the given B<id> and B<flags>. The following flags are
318 EVP_PKEY_FLAG_AUTOARGLEN
319 EVP_PKEY_FLAG_SIGCTX_CUSTOM
321 If an B<EVP_PKEY_METHOD> is set with the B<EVP_PKEY_FLAG_AUTOARGLEN> flag, the
322 maximum size of the output buffer will be automatically calculated or checked
323 in corresponding EVP methods by the EVP framework. Thus the implementations of
324 these methods don't need to care about handling the case of returning output
325 buffer size by themselves. For details on the output buffer size, refer to
328 The B<EVP_PKEY_FLAG_SIGCTX_CUSTOM> is used to indicate the signctx() method
329 of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a
330 digest signing operation by calling L<EVP_DigestSignFinal(3)>.
332 EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by
335 EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src>
338 EVP_PKEY_meth_find() finds an B<EVP_PKEY_METHOD> object with the B<id>.
339 This function first searches through the user-defined method objects and
340 then the built-in objects.
342 EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods.
344 The EVP_PKEY_meth_set functions set the corresponding fields of
345 B<EVP_PKEY_METHOD> structure with the arguments passed.
347 The EVP_PKEY_meth_get functions get the corresponding fields of
348 B<EVP_PKEY_METHOD> structure to the arguments provided.
352 EVP_PKEY_meth_new() returns a pointer to a new B<EVP_PKEY_METHOD>
353 object or returns NULL on error.
355 EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.
357 EVP_PKEY_meth_find() returns a pointer to the found B<EVP_PKEY_METHOD>
358 object or returns NULL if not found.
360 EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0
361 if an error occurred.
363 All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return
364 values. For the 'get' functions, function pointers are returned by
369 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
371 Licensed under the OpenSSL license (the "License"). You may not use
372 this file except in compliance with the License. You can obtain a copy
373 in the file LICENSE in the source distribution or at
374 L<https://www.openssl.org/source/license.html>.