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