EVP_PKEY_meth_new.pod revision 325337 
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,
11EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl,
12EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup,
13EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign,
14EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx,
15EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt,
16EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl
17- manipulating EVP_PKEY_METHOD structure
18
19=head1 SYNOPSIS
20
21 #include <openssl/evp.h>
22
23 typedef struct evp_pkey_method_st EVP_PKEY_METHOD;
24
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);
30
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,
35                                          EVP_PKEY_CTX *src));
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,
41                                                  EVP_PKEY *pkey));
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,
45                                              EVP_PKEY *pkey));
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,
51                                          size_t tbslen));
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,
56                                              size_t siglen,
57                                              const unsigned char *tbs,
58                                              size_t tbslen));
59 void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,
60                                       int (*verify_recover_init) (EVP_PKEY_CTX
61                                                                   *ctx),
62                                       int (*verify_recover) (EVP_PKEY_CTX
63                                                              *ctx,
64                                                              unsigned char
65                                                              *sig,
66                                                              size_t *siglen,
67                                                              const unsigned
68                                                              char *tbs,
69                                                              size_t tbslen));
70 void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,
71                                int (*signctx_init) (EVP_PKEY_CTX *ctx,
72                                                     EVP_MD_CTX *mctx),
73                                int (*signctx) (EVP_PKEY_CTX *ctx,
74                                                unsigned char *sig,
75                                                size_t *siglen,
76                                                EVP_MD_CTX *mctx));
77 void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,
78                                  int (*verifyctx_init) (EVP_PKEY_CTX *ctx,
79                                                         EVP_MD_CTX *mctx),
80                                  int (*verifyctx) (EVP_PKEY_CTX *ctx,
81                                                    const unsigned char *sig,
82                                                    int siglen,
83                                                    EVP_MD_CTX *mctx));
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,
87                                                  unsigned char *out,
88                                                  size_t *outlen,
89                                                  const unsigned char *in,
90                                                  size_t inlen));
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,
94                                                unsigned char *out,
95                                                size_t *outlen,
96                                                const unsigned char *in,
97                                                size_t inlen));
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,
101                                              unsigned char *key,
102                                              size_t *keylen));
103 void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,
104                             int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
105                                          void *p2),
106                             int (*ctrl_str) (EVP_PKEY_CTX *ctx,
107                                              const char *type,
108                                              const char *value));
109
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,
114                                            EVP_PKEY_CTX *src));
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,
120                                                    EVP_PKEY *pkey));
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,
124                                                EVP_PKEY *pkey));
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,
130                                            size_t tbslen));
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,
135                                                size_t siglen,
136                                                const unsigned char *tbs,
137                                                size_t tbslen));
138 void EVP_PKEY_meth_get_verify_recover(EVP_PKEY_METHOD *pmeth,
139                                       int (**pverify_recover_init) (EVP_PKEY_CTX
140                                                                     *ctx),
141                                       int (**pverify_recover) (EVP_PKEY_CTX
142                                                                *ctx,
143                                                                unsigned char
144                                                                *sig,
145                                                                size_t *siglen,
146                                                                const unsigned
147                                                                char *tbs,
148                                                                size_t tbslen));
149 void EVP_PKEY_meth_get_signctx(EVP_PKEY_METHOD *pmeth,
150                                int (**psignctx_init) (EVP_PKEY_CTX *ctx,
151                                                       EVP_MD_CTX *mctx),
152                                int (**psignctx) (EVP_PKEY_CTX *ctx,
153                                                  unsigned char *sig,
154                                                  size_t *siglen,
155                                                  EVP_MD_CTX *mctx));
156 void EVP_PKEY_meth_get_verifyctx(EVP_PKEY_METHOD *pmeth,
157                                  int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,
158                                                           EVP_MD_CTX *mctx),
159                                  int (**pverifyctx) (EVP_PKEY_CTX *ctx,
160                                                      const unsigned char *sig,
161                                                      int siglen,
162                                                      EVP_MD_CTX *mctx));
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,
166                                                    unsigned char *out,
167                                                    size_t *outlen,
168                                                    const unsigned char *in,
169                                                    size_t inlen));
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,
173                                                  unsigned char *out,
174                                                  size_t *outlen,
175                                                  const unsigned char *in,
176                                                  size_t inlen));
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,
180                                                unsigned char *key,
181                                                size_t *keylen));
182 void EVP_PKEY_meth_get_ctrl(EVP_PKEY_METHOD *pmeth,
183                             int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
184                                            void *p2),
185                             int (**pctrl_str) (EVP_PKEY_CTX *ctx,
186                                                const char *type,
187                                                const char *value));
188
189=head1 DESCRIPTION
190
191B<EVP_PKEY_METHOD> is a structure which holds a set of methods for a
192specific public key cryptographic algorithm. Those methods are usually
193used to perform different jobs, such as generating a key, signing or
194verifying, encrypting or decrypting, etc.
195
196There are two places where the B<EVP_PKEY_METHOD> objects are stored: one
197is a built-in static array representing the standard methods for different
198algorithms, and the other one is a stack of user-defined application-specific
199methods, which can be manipulated by using L<EVP_PKEY_meth_add0(3)>.
200
201The B<EVP_PKEY_METHOD> objects are usually referenced by B<EVP_PKEY_CTX>
202objects.
203
204=head2 Methods
205
206The methods are the underlying implementations of a particular public key
207algorithm present by the B<EVP_PKEY_CTX> object.
208
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);
212
213The init() method is called to initialize algorithm-specific data when a new
214B<EVP_PKEY_CTX> is created. As opposed to init(), the cleanup() method is called
215when an B<EVP_PKEY_CTX> is freed. The copy() method is called when an B<EVP_PKEY_CTX>
216is being duplicated. Refer to L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_id(3)>,
217L<EVP_PKEY_CTX_free(3)> and L<EVP_PKEY_CTX_dup(3)>.
218
219 int (*paramgen_init) (EVP_PKEY_CTX *ctx);
220 int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
221
222The paramgen_init() and paramgen() methods deal with key parameter generation.
223They are called by L<EVP_PKEY_paramgen_init(3)> and L<EVP_PKEY_paramgen(3)> to
224handle the parameter generation process.
225
226 int (*keygen_init) (EVP_PKEY_CTX *ctx);
227 int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
228
229The keygen_init() and keygen() methods are used to generate the actual key for
230the specified algorithm. They are called by L<EVP_PKEY_keygen_init(3)> and
231L<EVP_PKEY_keygen(3)>.
232
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);
236
237The sign_init() and sign() methods are used to generate the signature of a
238piece of data using a private key. They are called by L<EVP_PKEY_sign_init(3)>
239and L<EVP_PKEY_sign(3)>.
240
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);
245
246The verify_init() and verify() methods are used to verify whether a signature is
247valid. They are called by L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
248
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);
253
254The verify_recover_init() and verify_recover() methods are used to verify a
255signature and then recover the digest from the signature (for instance, a
256signature that was generated by RSA signing algorithm). They are called by
257L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
258
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,
261                 EVP_MD_CTX *mctx);
262
263The signctx_init() and signctx() methods are used to sign a digest present by
264a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See
265L<EVP_DigestSignInit(3)> for detail.
266
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,
269                   EVP_MD_CTX *mctx);
270
271The verifyctx_init() and verifyctx() methods are used to verify a signature
272against the data in a B<EVP_MD_CTX> object. They are called by the various
273EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for detail.
274
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);
278
279The encrypt_init() and encrypt() methods are used to encrypt a piece of data.
280They are called by L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)>.
281
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);
285
286The decrypt_init() and decrypt() methods are used to decrypt a piece of data.
287They are called by L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
288
289 int (*derive_init) (EVP_PKEY_CTX *ctx);
290 int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
291
292The derive_init() and derive() methods are used to derive the shared secret
293from a public key algorithm (for instance, the DH algorithm). They are called by
294L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>.
295
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);
298
299The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
300settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail.
301
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,
306                      size_t tbslen);
307
308The digestsign() and digestverify() methods are used to generate or verify
309a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)>
310and L<EVP_DigestVerify(3)>.
311
312=head2 Functions
313
314EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object,
315and associates the given B<id> and B<flags>. The following flags are
316supported:
317
318 EVP_PKEY_FLAG_AUTOARGLEN
319 EVP_PKEY_FLAG_SIGCTX_CUSTOM
320
321If an B<EVP_PKEY_METHOD> is set with the B<EVP_PKEY_FLAG_AUTOARGLEN> flag, the
322maximum size of the output buffer will be automatically calculated or checked
323in corresponding EVP methods by the EVP framework. Thus the implementations of
324these methods don't need to care about handling the case of returning output
325buffer size by themselves. For details on the output buffer size, refer to
326L<EVP_PKEY_sign(3)>.
327
328The B<EVP_PKEY_FLAG_SIGCTX_CUSTOM> is used to indicate the signctx() method
329of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a
330digest signing operation by calling L<EVP_DigestSignFinal(3)>.
331
332EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by
333B<pmeth>.
334
335EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src>
336to B<dst>.
337
338EVP_PKEY_meth_find() finds an B<EVP_PKEY_METHOD> object with the B<id>.
339This function first searches through the user-defined method objects and
340then the built-in objects.
341
342EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods.
343
344The EVP_PKEY_meth_set functions set the corresponding fields of
345B<EVP_PKEY_METHOD> structure with the arguments passed.
346
347The EVP_PKEY_meth_get functions get the corresponding fields of
348B<EVP_PKEY_METHOD> structure to the arguments provided.
349
350=head1 RETURN VALUES
351
352EVP_PKEY_meth_new() returns a pointer to a new B<EVP_PKEY_METHOD>
353object or returns NULL on error.
354
355EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.
356
357EVP_PKEY_meth_find() returns a pointer to the found B<EVP_PKEY_METHOD>
358object or returns NULL if not found.
359
360EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0
361if an error occurred.
362
363All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return
364values. For the 'get' functions, function pointers are returned by
365arguments.
366
367=head1 COPYRIGHT
368
369Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
370
371Licensed under the OpenSSL license (the "License").  You may not use
372this file except in compliance with the License.  You can obtain a copy
373in the file LICENSE in the source distribution or at
374L<https://www.openssl.org/source/license.html>.
375
376=cut
377