]> git.ipfire.org Git - thirdparty/openssl.git/blame - doc/man3/EVP_PKEY_meth_new.pod
projects / thirdparty / openssl.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Convert _meth_get_ functions to const getters
[thirdparty/openssl.git] / doc / man3 / EVP_PKEY_meth_new.pod
CommitLineData
43f985fd
PY		 1=pod
2
3=head1 NAME
4
5EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy, EVP_PKEY_meth_find,
6EVP_PKEY_meth_add0, EVP_PKEY_METHOD,
7EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup,
8EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign,
9EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx,
10EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt,
2aee35d3 11EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, EVP_PKEY_meth_set_check,
b0004708 12EVP_PKEY_meth_set_public_check, EVP_PKEY_meth_set_param_check,
43f985fd
PY		 13EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup,
14EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign,
15EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx,
16EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt,
0822e89a 17EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check,
b0004708 18EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check,
0822e89a 19EVP_PKEY_meth_remove
43f985fd
PY		 20- manipulating EVP_PKEY_METHOD structure
21
22=head1 SYNOPSIS
23
24 #include <openssl/evp.h>
25
26 typedef struct evp_pkey_method_st EVP_PKEY_METHOD;
27
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);
0822e89a 33 int EVP_PKEY_meth_remove(const EVP_PKEY_METHOD *pmeth);
43f985fd
PY		 34
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,
39 EVP_PKEY_CTX *src));
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,
45 EVP_PKEY *pkey));
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,
49 EVP_PKEY *pkey));
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,
55 size_t tbslen));
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,
60 size_t siglen,
61 const unsigned char *tbs,
62 size_t tbslen));
63 void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,
64 int (*verify_recover_init) (EVP_PKEY_CTX
65 *ctx),
66 int (*verify_recover) (EVP_PKEY_CTX
67 *ctx,
68 unsigned char
69 *sig,
70 size_t *siglen,
71 const unsigned
72 char *tbs,
73 size_t tbslen));
74 void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,
75 int (*signctx_init) (EVP_PKEY_CTX *ctx,
76 EVP_MD_CTX *mctx),
77 int (*signctx) (EVP_PKEY_CTX *ctx,
78 unsigned char *sig,
79 size_t *siglen,
80 EVP_MD_CTX *mctx));
81 void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,
82 int (*verifyctx_init) (EVP_PKEY_CTX *ctx,
83 EVP_MD_CTX *mctx),
84 int (*verifyctx) (EVP_PKEY_CTX *ctx,
85 const unsigned char *sig,
86 int siglen,
87 EVP_MD_CTX *mctx));
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,
91 unsigned char *out,
92 size_t *outlen,
93 const unsigned char *in,
94 size_t inlen));
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,
98 unsigned char *out,
99 size_t *outlen,
100 const unsigned char *in,
101 size_t inlen));
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,
105 unsigned char *key,
106 size_t *keylen));
107 void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,
108 int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
109 void *p2),
110 int (*ctrl_str) (EVP_PKEY_CTX *ctx,
111 const char *type,
112 const char *value));
2aee35d3
PY		 113 void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,
114 int (*check) (EVP_PKEY *pkey));
b0004708
PY		 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));
43f985fd 119
693be9a2 120 void EVP_PKEY_meth_get_init(const EVP_PKEY_METHOD *pmeth,
43f985fd 121 int (**pinit) (EVP_PKEY_CTX *ctx));
693be9a2 122 void EVP_PKEY_meth_get_copy(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 123 int (**pcopy) (EVP_PKEY_CTX *dst,
124 EVP_PKEY_CTX *src));
693be9a2 125 void EVP_PKEY_meth_get_cleanup(const EVP_PKEY_METHOD *pmeth,
43f985fd 126 void (**pcleanup) (EVP_PKEY_CTX *ctx));
693be9a2 127 void EVP_PKEY_meth_get_paramgen(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 128 int (**pparamgen_init) (EVP_PKEY_CTX *ctx),
129 int (**pparamgen) (EVP_PKEY_CTX *ctx,
130 EVP_PKEY *pkey));
693be9a2 131 void EVP_PKEY_meth_get_keygen(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 132 int (**pkeygen_init) (EVP_PKEY_CTX *ctx),
133 int (**pkeygen) (EVP_PKEY_CTX *ctx,
134 EVP_PKEY *pkey));
693be9a2 135 void EVP_PKEY_meth_get_sign(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 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,
140 size_t tbslen));
693be9a2 141 void EVP_PKEY_meth_get_verify(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 142 int (**pverify_init) (EVP_PKEY_CTX *ctx),
143 int (**pverify) (EVP_PKEY_CTX *ctx,
144 const unsigned char *sig,
145 size_t siglen,
146 const unsigned char *tbs,
147 size_t tbslen));
693be9a2 148 void EVP_PKEY_meth_get_verify_recover(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 149 int (**pverify_recover_init) (EVP_PKEY_CTX
150 *ctx),
151 int (**pverify_recover) (EVP_PKEY_CTX
152 *ctx,
153 unsigned char
154 *sig,
155 size_t *siglen,
156 const unsigned
157 char *tbs,
158 size_t tbslen));
693be9a2 159 void EVP_PKEY_meth_get_signctx(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 160 int (**psignctx_init) (EVP_PKEY_CTX *ctx,
161 EVP_MD_CTX *mctx),
162 int (**psignctx) (EVP_PKEY_CTX *ctx,
163 unsigned char *sig,
164 size_t *siglen,
165 EVP_MD_CTX *mctx));
693be9a2 166 void EVP_PKEY_meth_get_verifyctx(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 167 int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,
168 EVP_MD_CTX *mctx),
169 int (**pverifyctx) (EVP_PKEY_CTX *ctx,
170 const unsigned char *sig,
171 int siglen,
172 EVP_MD_CTX *mctx));
693be9a2 173 void EVP_PKEY_meth_get_encrypt(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 174 int (**pencrypt_init) (EVP_PKEY_CTX *ctx),
175 int (**pencryptfn) (EVP_PKEY_CTX *ctx,
176 unsigned char *out,
177 size_t *outlen,
178 const unsigned char *in,
179 size_t inlen));
693be9a2 180 void EVP_PKEY_meth_get_decrypt(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 181 int (**pdecrypt_init) (EVP_PKEY_CTX *ctx),
182 int (**pdecrypt) (EVP_PKEY_CTX *ctx,
183 unsigned char *out,
184 size_t *outlen,
185 const unsigned char *in,
186 size_t inlen));
693be9a2 187 void EVP_PKEY_meth_get_derive(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 188 int (**pderive_init) (EVP_PKEY_CTX *ctx),
189 int (**pderive) (EVP_PKEY_CTX *ctx,
190 unsigned char *key,
191 size_t *keylen));
693be9a2 192 void EVP_PKEY_meth_get_ctrl(const EVP_PKEY_METHOD *pmeth,
43f985fd
PY		 193 int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
194 void *p2),
195 int (**pctrl_str) (EVP_PKEY_CTX *ctx,
196 const char *type,
197 const char *value));
693be9a2 198 void EVP_PKEY_meth_get_check(const EVP_PKEY_METHOD *pmeth,
2aee35d3 199 int (**pcheck) (EVP_PKEY *pkey));
693be9a2 200 void EVP_PKEY_meth_get_public_check(const EVP_PKEY_METHOD *pmeth,
b0004708 201 int (**pcheck) (EVP_PKEY *pkey));
693be9a2 202 void EVP_PKEY_meth_get_param_check(const EVP_PKEY_METHOD *pmeth,
b0004708 203 int (**pcheck) (EVP_PKEY *pkey));
43f985fd
PY		 204
205=head1 DESCRIPTION
206
207B<EVP_PKEY_METHOD> is a structure which holds a set of methods for a
208specific public key cryptographic algorithm. Those methods are usually
209used to perform different jobs, such as generating a key, signing or
210verifying, encrypting or decrypting, etc.
211
212There are two places where the B<EVP_PKEY_METHOD> objects are stored: one
213is a built-in static array representing the standard methods for different
214algorithms, and the other one is a stack of user-defined application-specific
215methods, which can be manipulated by using L<EVP_PKEY_meth_add0(3)>.
216
217The B<EVP_PKEY_METHOD> objects are usually referenced by B<EVP_PKEY_CTX>
218objects.
219
220=head2 Methods
221
222The methods are the underlying implementations of a particular public key
223algorithm present by the B<EVP_PKEY_CTX> object.
224
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);
228
229The init() method is called to initialize algorithm-specific data when a new
230B<EVP_PKEY_CTX> is created. As opposed to init(), the cleanup() method is called
231when an B<EVP_PKEY_CTX> is freed. The copy() method is called when an B<EVP_PKEY_CTX>
232is being duplicated. Refer to L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_id(3)>,
233L<EVP_PKEY_CTX_free(3)> and L<EVP_PKEY_CTX_dup(3)>.
234
235 int (*paramgen_init) (EVP_PKEY_CTX *ctx);
236 int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
237
238The paramgen_init() and paramgen() methods deal with key parameter generation.
239They are called by L<EVP_PKEY_paramgen_init(3)> and L<EVP_PKEY_paramgen(3)> to
240handle the parameter generation process.
241
242 int (*keygen_init) (EVP_PKEY_CTX *ctx);
243 int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
244
245The keygen_init() and keygen() methods are used to generate the actual key for
246the specified algorithm. They are called by L<EVP_PKEY_keygen_init(3)> and
247L<EVP_PKEY_keygen(3)>.
248
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);
252
253The sign_init() and sign() methods are used to generate the signature of a
254piece of data using a private key. They are called by L<EVP_PKEY_sign_init(3)>
255and L<EVP_PKEY_sign(3)>.
256
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);
261
262The verify_init() and verify() methods are used to verify whether a signature is
263valid. They are called by L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
264
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);
269
270The verify_recover_init() and verify_recover() methods are used to verify a
271signature and then recover the digest from the signature (for instance, a
272signature that was generated by RSA signing algorithm). They are called by
273L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
274
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,
277 EVP_MD_CTX *mctx);
278
279The signctx_init() and signctx() methods are used to sign a digest present by
280a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See
281L<EVP_DigestSignInit(3)> for detail.
282
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,
285 EVP_MD_CTX *mctx);
286
287The verifyctx_init() and verifyctx() methods are used to verify a signature
288against the data in a B<EVP_MD_CTX> object. They are called by the various
289EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for detail.
290
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);
294
295The encrypt_init() and encrypt() methods are used to encrypt a piece of data.
296They are called by L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)>.
297
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);
301
302The decrypt_init() and decrypt() methods are used to decrypt a piece of data.
303They are called by L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
304
305 int (*derive_init) (EVP_PKEY_CTX *ctx);
306 int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
307
308The derive_init() and derive() methods are used to derive the shared secret
309from a public key algorithm (for instance, the DH algorithm). They are called by
310L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>.
311
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);
314
315The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
316settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail.
317
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,
322 size_t tbslen);
323
324The digestsign() and digestverify() methods are used to generate or verify
325a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)>
326and L<EVP_DigestVerify(3)>.
327
2aee35d3 328 int (*check) (EVP_PKEY *pkey);
b0004708
PY		 329 int (*public_check) (EVP_PKEY *pkey);
330 int (*param_check) (EVP_PKEY *pkey);
2aee35d3 331
b0004708
PY		 332The check(), public_check() and param_check() methods are used to validate a
333key-pair, the public component and parameters respectively for a given B<pkey>.
334They could be called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
335L<EVP_PKEY_param_check(3)> respectively.
2aee35d3 336
43f985fd
PY		 337=head2 Functions
338
339EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object,
340and associates the given B<id> and B<flags>. The following flags are
341supported:
342
343 EVP_PKEY_FLAG_AUTOARGLEN
344 EVP_PKEY_FLAG_SIGCTX_CUSTOM
345
346If an B<EVP_PKEY_METHOD> is set with the B<EVP_PKEY_FLAG_AUTOARGLEN> flag, the
347maximum size of the output buffer will be automatically calculated or checked
348in corresponding EVP methods by the EVP framework. Thus the implementations of
349these methods don't need to care about handling the case of returning output
350buffer size by themselves. For details on the output buffer size, refer to
351L<EVP_PKEY_sign(3)>.
352
353The B<EVP_PKEY_FLAG_SIGCTX_CUSTOM> is used to indicate the signctx() method
354of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a
355digest signing operation by calling L<EVP_DigestSignFinal(3)>.
356
357EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by
358B<pmeth>.
359
360EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src>
361to B<dst>.
362
363EVP_PKEY_meth_find() finds an B<EVP_PKEY_METHOD> object with the B<id>.
364This function first searches through the user-defined method objects and
365then the built-in objects.
366
367EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods.
368
0822e89a 369EVP_PKEY_meth_remove() removes an B<EVP_PKEY_METHOD> object added by
a8f730d5 370EVP_PKEY_meth_add0().
0822e89a 371
43f985fd
PY		 372The EVP_PKEY_meth_set functions set the corresponding fields of
373B<EVP_PKEY_METHOD> structure with the arguments passed.
374
375The EVP_PKEY_meth_get functions get the corresponding fields of
376B<EVP_PKEY_METHOD> structure to the arguments provided.
377
378=head1 RETURN VALUES
379
380EVP_PKEY_meth_new() returns a pointer to a new B<EVP_PKEY_METHOD>
381object or returns NULL on error.
382
383EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.
384
385EVP_PKEY_meth_find() returns a pointer to the found B<EVP_PKEY_METHOD>
386object or returns NULL if not found.
387
388EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0
389if an error occurred.
390
0822e89a
PY		 391EVP_PKEY_meth_remove() returns 1 if method is removed successfully or
3920 if an error occurred.
393
43f985fd
PY		 394All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return
395values. For the 'get' functions, function pointers are returned by
396arguments.
397
398=head1 COPYRIGHT
399
400Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
401
402Licensed under the OpenSSL license (the "License"). You may not use
403this file except in compliance with the License. You can obtain a copy
404in the file LICENSE in the source distribution or at
405L<https://www.openssl.org/source/license.html>.
406
407=cut
A mirror of the official openssl repository