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_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup,
14 EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign,
15 EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx,
16 EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt,
17 EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check,
18 EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check,
20 - manipulating EVP_PKEY_METHOD structure
24 #include <openssl/evp.h>
26 typedef struct evp_pkey_method_st EVP_PKEY_METHOD;
28 EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags);
29 void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth);
30 void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src);
31 const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type);
32 int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth);
33 int EVP_PKEY_meth_remove(const EVP_PKEY_METHOD *pmeth);
35 void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth,
36 int (*init) (EVP_PKEY_CTX *ctx));
37 void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth,
38 int (*copy) (EVP_PKEY_CTX *dst,
40 void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth,
41 void (*cleanup) (EVP_PKEY_CTX *ctx));
42 void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth,
43 int (*paramgen_init) (EVP_PKEY_CTX *ctx),
44 int (*paramgen) (EVP_PKEY_CTX *ctx,
46 void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth,
47 int (*keygen_init) (EVP_PKEY_CTX *ctx),
48 int (*keygen) (EVP_PKEY_CTX *ctx,
50 void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth,
51 int (*sign_init) (EVP_PKEY_CTX *ctx),
52 int (*sign) (EVP_PKEY_CTX *ctx,
53 unsigned char *sig, size_t *siglen,
54 const unsigned char *tbs,
56 void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth,
57 int (*verify_init) (EVP_PKEY_CTX *ctx),
58 int (*verify) (EVP_PKEY_CTX *ctx,
59 const unsigned char *sig,
61 const unsigned char *tbs,
63 void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,
64 int (*verify_recover_init) (EVP_PKEY_CTX
66 int (*verify_recover) (EVP_PKEY_CTX
74 void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,
75 int (*signctx_init) (EVP_PKEY_CTX *ctx,
77 int (*signctx) (EVP_PKEY_CTX *ctx,
81 void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,
82 int (*verifyctx_init) (EVP_PKEY_CTX *ctx,
84 int (*verifyctx) (EVP_PKEY_CTX *ctx,
85 const unsigned char *sig,
88 void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth,
89 int (*encrypt_init) (EVP_PKEY_CTX *ctx),
90 int (*encryptfn) (EVP_PKEY_CTX *ctx,
93 const unsigned char *in,
95 void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth,
96 int (*decrypt_init) (EVP_PKEY_CTX *ctx),
97 int (*decrypt) (EVP_PKEY_CTX *ctx,
100 const unsigned char *in,
102 void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth,
103 int (*derive_init) (EVP_PKEY_CTX *ctx),
104 int (*derive) (EVP_PKEY_CTX *ctx,
107 void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,
108 int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
110 int (*ctrl_str) (EVP_PKEY_CTX *ctx,
113 void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,
114 int (*check) (EVP_PKEY *pkey));
115 void EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth,
116 int (*check) (EVP_PKEY *pkey));
117 void EVP_PKEY_meth_set_param_check(EVP_PKEY_METHOD *pmeth,
118 int (*check) (EVP_PKEY *pkey));
120 void EVP_PKEY_meth_get_init(const EVP_PKEY_METHOD *pmeth,
121 int (**pinit) (EVP_PKEY_CTX *ctx));
122 void EVP_PKEY_meth_get_copy(const EVP_PKEY_METHOD *pmeth,
123 int (**pcopy) (EVP_PKEY_CTX *dst,
125 void EVP_PKEY_meth_get_cleanup(const EVP_PKEY_METHOD *pmeth,
126 void (**pcleanup) (EVP_PKEY_CTX *ctx));
127 void EVP_PKEY_meth_get_paramgen(const EVP_PKEY_METHOD *pmeth,
128 int (**pparamgen_init) (EVP_PKEY_CTX *ctx),
129 int (**pparamgen) (EVP_PKEY_CTX *ctx,
131 void EVP_PKEY_meth_get_keygen(const EVP_PKEY_METHOD *pmeth,
132 int (**pkeygen_init) (EVP_PKEY_CTX *ctx),
133 int (**pkeygen) (EVP_PKEY_CTX *ctx,
135 void EVP_PKEY_meth_get_sign(const EVP_PKEY_METHOD *pmeth,
136 int (**psign_init) (EVP_PKEY_CTX *ctx),
137 int (**psign) (EVP_PKEY_CTX *ctx,
138 unsigned char *sig, size_t *siglen,
139 const unsigned char *tbs,
141 void EVP_PKEY_meth_get_verify(const EVP_PKEY_METHOD *pmeth,
142 int (**pverify_init) (EVP_PKEY_CTX *ctx),
143 int (**pverify) (EVP_PKEY_CTX *ctx,
144 const unsigned char *sig,
146 const unsigned char *tbs,
148 void EVP_PKEY_meth_get_verify_recover(const EVP_PKEY_METHOD *pmeth,
149 int (**pverify_recover_init) (EVP_PKEY_CTX
151 int (**pverify_recover) (EVP_PKEY_CTX
159 void EVP_PKEY_meth_get_signctx(const EVP_PKEY_METHOD *pmeth,
160 int (**psignctx_init) (EVP_PKEY_CTX *ctx,
162 int (**psignctx) (EVP_PKEY_CTX *ctx,
166 void EVP_PKEY_meth_get_verifyctx(const EVP_PKEY_METHOD *pmeth,
167 int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,
169 int (**pverifyctx) (EVP_PKEY_CTX *ctx,
170 const unsigned char *sig,
173 void EVP_PKEY_meth_get_encrypt(const EVP_PKEY_METHOD *pmeth,
174 int (**pencrypt_init) (EVP_PKEY_CTX *ctx),
175 int (**pencryptfn) (EVP_PKEY_CTX *ctx,
178 const unsigned char *in,
180 void EVP_PKEY_meth_get_decrypt(const EVP_PKEY_METHOD *pmeth,
181 int (**pdecrypt_init) (EVP_PKEY_CTX *ctx),
182 int (**pdecrypt) (EVP_PKEY_CTX *ctx,
185 const unsigned char *in,
187 void EVP_PKEY_meth_get_derive(const EVP_PKEY_METHOD *pmeth,
188 int (**pderive_init) (EVP_PKEY_CTX *ctx),
189 int (**pderive) (EVP_PKEY_CTX *ctx,
192 void EVP_PKEY_meth_get_ctrl(const EVP_PKEY_METHOD *pmeth,
193 int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
195 int (**pctrl_str) (EVP_PKEY_CTX *ctx,
198 void EVP_PKEY_meth_get_check(const EVP_PKEY_METHOD *pmeth,
199 int (**pcheck) (EVP_PKEY *pkey));
200 void EVP_PKEY_meth_get_public_check(const EVP_PKEY_METHOD *pmeth,
201 int (**pcheck) (EVP_PKEY *pkey));
202 void EVP_PKEY_meth_get_param_check(const EVP_PKEY_METHOD *pmeth,
203 int (**pcheck) (EVP_PKEY *pkey));
207 B<EVP_PKEY_METHOD> is a structure which holds a set of methods for a
208 specific public key cryptographic algorithm. Those methods are usually
209 used to perform different jobs, such as generating a key, signing or
210 verifying, encrypting or decrypting, etc.
212 There are two places where the B<EVP_PKEY_METHOD> objects are stored: one
213 is a built-in static array representing the standard methods for different
214 algorithms, and the other one is a stack of user-defined application-specific
215 methods, which can be manipulated by using L<EVP_PKEY_meth_add0(3)>.
217 The B<EVP_PKEY_METHOD> objects are usually referenced by B<EVP_PKEY_CTX>
222 The methods are the underlying implementations of a particular public key
223 algorithm present by the B<EVP_PKEY_CTX> object.
225 int (*init) (EVP_PKEY_CTX *ctx);
226 int (*copy) (EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src);
227 void (*cleanup) (EVP_PKEY_CTX *ctx);
229 The init() method is called to initialize algorithm-specific data when a new
230 B<EVP_PKEY_CTX> is created. As opposed to init(), the cleanup() method is called
231 when an B<EVP_PKEY_CTX> is freed. The copy() method is called when an B<EVP_PKEY_CTX>
232 is being duplicated. Refer to L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_id(3)>,
233 L<EVP_PKEY_CTX_free(3)> and L<EVP_PKEY_CTX_dup(3)>.
235 int (*paramgen_init) (EVP_PKEY_CTX *ctx);
236 int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
238 The paramgen_init() and paramgen() methods deal with key parameter generation.
239 They are called by L<EVP_PKEY_paramgen_init(3)> and L<EVP_PKEY_paramgen(3)> to
240 handle the parameter generation process.
242 int (*keygen_init) (EVP_PKEY_CTX *ctx);
243 int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
245 The keygen_init() and keygen() methods are used to generate the actual key for
246 the specified algorithm. They are called by L<EVP_PKEY_keygen_init(3)> and
247 L<EVP_PKEY_keygen(3)>.
249 int (*sign_init) (EVP_PKEY_CTX *ctx);
250 int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
251 const unsigned char *tbs, size_t tbslen);
253 The sign_init() and sign() methods are used to generate the signature of a
254 piece of data using a private key. They are called by L<EVP_PKEY_sign_init(3)>
255 and L<EVP_PKEY_sign(3)>.
257 int (*verify_init) (EVP_PKEY_CTX *ctx);
258 int (*verify) (EVP_PKEY_CTX *ctx,
259 const unsigned char *sig, size_t siglen,
260 const unsigned char *tbs, size_t tbslen);
262 The verify_init() and verify() methods are used to verify whether a signature is
263 valid. They are called by L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
265 int (*verify_recover_init) (EVP_PKEY_CTX *ctx);
266 int (*verify_recover) (EVP_PKEY_CTX *ctx,
267 unsigned char *rout, size_t *routlen,
268 const unsigned char *sig, size_t siglen);
270 The verify_recover_init() and verify_recover() methods are used to verify a
271 signature and then recover the digest from the signature (for instance, a
272 signature that was generated by RSA signing algorithm). They are called by
273 L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
275 int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
276 int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
279 The signctx_init() and signctx() methods are used to sign a digest present by
280 a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See
281 L<EVP_DigestSignInit(3)> for detail.
283 int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
284 int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen,
287 The verifyctx_init() and verifyctx() methods are used to verify a signature
288 against the data in a B<EVP_MD_CTX> object. They are called by the various
289 EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for detail.
291 int (*encrypt_init) (EVP_PKEY_CTX *ctx);
292 int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
293 const unsigned char *in, size_t inlen);
295 The encrypt_init() and encrypt() methods are used to encrypt a piece of data.
296 They are called by L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)>.
298 int (*decrypt_init) (EVP_PKEY_CTX *ctx);
299 int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
300 const unsigned char *in, size_t inlen);
302 The decrypt_init() and decrypt() methods are used to decrypt a piece of data.
303 They are called by L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
305 int (*derive_init) (EVP_PKEY_CTX *ctx);
306 int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
308 The derive_init() and derive() methods are used to derive the shared secret
309 from a public key algorithm (for instance, the DH algorithm). They are called by
310 L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>.
312 int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2);
313 int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value);
315 The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
316 settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail.
318 int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen,
319 const unsigned char *tbs, size_t tbslen);
320 int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig,
321 size_t siglen, const unsigned char *tbs,
324 The digestsign() and digestverify() methods are used to generate or verify
325 a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)>
326 and L<EVP_DigestVerify(3)>.
328 int (*check) (EVP_PKEY *pkey);
329 int (*public_check) (EVP_PKEY *pkey);
330 int (*param_check) (EVP_PKEY *pkey);
332 The check(), public_check() and param_check() methods are used to validate a
333 key-pair, the public component and parameters respectively for a given B<pkey>.
334 They could be called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
335 L<EVP_PKEY_param_check(3)> respectively.
339 EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object,
340 and associates the given B<id> and B<flags>. The following flags are
343 EVP_PKEY_FLAG_AUTOARGLEN
344 EVP_PKEY_FLAG_SIGCTX_CUSTOM
346 If an B<EVP_PKEY_METHOD> is set with the B<EVP_PKEY_FLAG_AUTOARGLEN> flag, the
347 maximum size of the output buffer will be automatically calculated or checked
348 in corresponding EVP methods by the EVP framework. Thus the implementations of
349 these methods don't need to care about handling the case of returning output
350 buffer size by themselves. For details on the output buffer size, refer to
353 The B<EVP_PKEY_FLAG_SIGCTX_CUSTOM> is used to indicate the signctx() method
354 of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a
355 digest signing operation by calling L<EVP_DigestSignFinal(3)>.
357 EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by
360 EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src>
363 EVP_PKEY_meth_find() finds an B<EVP_PKEY_METHOD> object with the B<id>.
364 This function first searches through the user-defined method objects and
365 then the built-in objects.
367 EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods.
369 EVP_PKEY_meth_remove() removes an B<EVP_PKEY_METHOD> object added by
370 EVP_PKEY_meth_add0().
372 The EVP_PKEY_meth_set functions set the corresponding fields of
373 B<EVP_PKEY_METHOD> structure with the arguments passed.
375 The EVP_PKEY_meth_get functions get the corresponding fields of
376 B<EVP_PKEY_METHOD> structure to the arguments provided.
380 EVP_PKEY_meth_new() returns a pointer to a new B<EVP_PKEY_METHOD>
381 object or returns NULL on error.
383 EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.
385 EVP_PKEY_meth_find() returns a pointer to the found B<EVP_PKEY_METHOD>
386 object or returns NULL if not found.
388 EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0
389 if an error occurred.
391 EVP_PKEY_meth_remove() returns 1 if method is removed successfully or
392 0 if an error occurred.
394 All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return
395 values. For the 'get' functions, function pointers are returned by
400 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
402 Licensed under the OpenSSL license (the "License"). You may not use
403 this file except in compliance with the License. You can obtain a copy
404 in the file LICENSE in the source distribution or at
405 L<https://www.openssl.org/source/license.html>.