1EVP_PKEY_METH_NEW(3)                OpenSSL               EVP_PKEY_METH_NEW(3)
2
3
4

NAME

6       EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy,
7       EVP_PKEY_meth_find, EVP_PKEY_meth_add0, EVP_PKEY_METHOD,
8       EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy,
9       EVP_PKEY_meth_set_cleanup, EVP_PKEY_meth_set_paramgen,
10       EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign,
11       EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover,
12       EVP_PKEY_meth_set_signctx, EVP_PKEY_meth_set_verifyctx,
13       EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt,
14       EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl,
15       EVP_PKEY_meth_set_check, EVP_PKEY_meth_set_public_check,
16       EVP_PKEY_meth_set_param_check, EVP_PKEY_meth_set_digest_custom,
17       EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy,
18       EVP_PKEY_meth_get_cleanup, EVP_PKEY_meth_get_paramgen,
19       EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign,
20       EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover,
21       EVP_PKEY_meth_get_signctx, EVP_PKEY_meth_get_verifyctx,
22       EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt,
23       EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl,
24       EVP_PKEY_meth_get_check, EVP_PKEY_meth_get_public_check,
25       EVP_PKEY_meth_get_param_check, EVP_PKEY_meth_get_digest_custom,
26       EVP_PKEY_meth_remove - manipulating EVP_PKEY_METHOD structure
27

SYNOPSIS

29        #include <openssl/evp.h>
30
31        typedef struct evp_pkey_method_st EVP_PKEY_METHOD;
32
33        EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags);
34        void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth);
35        void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src);
36        const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type);
37        int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth);
38        int EVP_PKEY_meth_remove(const EVP_PKEY_METHOD *pmeth);
39
40        void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth,
41                                    int (*init) (EVP_PKEY_CTX *ctx));
42        void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth,
43                                    int (*copy) (EVP_PKEY_CTX *dst,
44                                                 EVP_PKEY_CTX *src));
45        void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth,
46                                       void (*cleanup) (EVP_PKEY_CTX *ctx));
47        void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth,
48                                        int (*paramgen_init) (EVP_PKEY_CTX *ctx),
49                                        int (*paramgen) (EVP_PKEY_CTX *ctx,
50                                                         EVP_PKEY *pkey));
51        void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth,
52                                      int (*keygen_init) (EVP_PKEY_CTX *ctx),
53                                      int (*keygen) (EVP_PKEY_CTX *ctx,
54                                                     EVP_PKEY *pkey));
55        void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth,
56                                    int (*sign_init) (EVP_PKEY_CTX *ctx),
57                                    int (*sign) (EVP_PKEY_CTX *ctx,
58                                                 unsigned char *sig, size_t *siglen,
59                                                 const unsigned char *tbs,
60                                                 size_t tbslen));
61        void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth,
62                                      int (*verify_init) (EVP_PKEY_CTX *ctx),
63                                      int (*verify) (EVP_PKEY_CTX *ctx,
64                                                     const unsigned char *sig,
65                                                     size_t siglen,
66                                                     const unsigned char *tbs,
67                                                     size_t tbslen));
68        void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth,
69                                              int (*verify_recover_init) (EVP_PKEY_CTX
70                                                                          *ctx),
71                                              int (*verify_recover) (EVP_PKEY_CTX
72                                                                     *ctx,
73                                                                     unsigned char
74                                                                     *sig,
75                                                                     size_t *siglen,
76                                                                     const unsigned
77                                                                     char *tbs,
78                                                                     size_t tbslen));
79        void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth,
80                                       int (*signctx_init) (EVP_PKEY_CTX *ctx,
81                                                            EVP_MD_CTX *mctx),
82                                       int (*signctx) (EVP_PKEY_CTX *ctx,
83                                                       unsigned char *sig,
84                                                       size_t *siglen,
85                                                       EVP_MD_CTX *mctx));
86        void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth,
87                                         int (*verifyctx_init) (EVP_PKEY_CTX *ctx,
88                                                                EVP_MD_CTX *mctx),
89                                         int (*verifyctx) (EVP_PKEY_CTX *ctx,
90                                                           const unsigned char *sig,
91                                                           int siglen,
92                                                           EVP_MD_CTX *mctx));
93        void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth,
94                                       int (*encrypt_init) (EVP_PKEY_CTX *ctx),
95                                       int (*encryptfn) (EVP_PKEY_CTX *ctx,
96                                                         unsigned char *out,
97                                                         size_t *outlen,
98                                                         const unsigned char *in,
99                                                         size_t inlen));
100        void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth,
101                                       int (*decrypt_init) (EVP_PKEY_CTX *ctx),
102                                       int (*decrypt) (EVP_PKEY_CTX *ctx,
103                                                       unsigned char *out,
104                                                       size_t *outlen,
105                                                       const unsigned char *in,
106                                                       size_t inlen));
107        void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth,
108                                      int (*derive_init) (EVP_PKEY_CTX *ctx),
109                                      int (*derive) (EVP_PKEY_CTX *ctx,
110                                                     unsigned char *key,
111                                                     size_t *keylen));
112        void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth,
113                                    int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
114                                                 void *p2),
115                                    int (*ctrl_str) (EVP_PKEY_CTX *ctx,
116                                                     const char *type,
117                                                     const char *value));
118        void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,
119                                     int (*check) (EVP_PKEY *pkey));
120        void EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth,
121                                            int (*check) (EVP_PKEY *pkey));
122        void EVP_PKEY_meth_set_param_check(EVP_PKEY_METHOD *pmeth,
123                                           int (*check) (EVP_PKEY *pkey));
124        void EVP_PKEY_meth_set_digest_custom(EVP_PKEY_METHOD *pmeth,
125                                            int (*digest_custom) (EVP_PKEY_CTX *ctx,
126                                                                  EVP_MD_CTX *mctx));
127
128        void EVP_PKEY_meth_get_init(const EVP_PKEY_METHOD *pmeth,
129                                    int (**pinit) (EVP_PKEY_CTX *ctx));
130        void EVP_PKEY_meth_get_copy(const EVP_PKEY_METHOD *pmeth,
131                                    int (**pcopy) (EVP_PKEY_CTX *dst,
132                                                   EVP_PKEY_CTX *src));
133        void EVP_PKEY_meth_get_cleanup(const EVP_PKEY_METHOD *pmeth,
134                                       void (**pcleanup) (EVP_PKEY_CTX *ctx));
135        void EVP_PKEY_meth_get_paramgen(const EVP_PKEY_METHOD *pmeth,
136                                        int (**pparamgen_init) (EVP_PKEY_CTX *ctx),
137                                        int (**pparamgen) (EVP_PKEY_CTX *ctx,
138                                                           EVP_PKEY *pkey));
139        void EVP_PKEY_meth_get_keygen(const EVP_PKEY_METHOD *pmeth,
140                                      int (**pkeygen_init) (EVP_PKEY_CTX *ctx),
141                                      int (**pkeygen) (EVP_PKEY_CTX *ctx,
142                                                       EVP_PKEY *pkey));
143        void EVP_PKEY_meth_get_sign(const EVP_PKEY_METHOD *pmeth,
144                                    int (**psign_init) (EVP_PKEY_CTX *ctx),
145                                    int (**psign) (EVP_PKEY_CTX *ctx,
146                                                   unsigned char *sig, size_t *siglen,
147                                                   const unsigned char *tbs,
148                                                   size_t tbslen));
149        void EVP_PKEY_meth_get_verify(const EVP_PKEY_METHOD *pmeth,
150                                      int (**pverify_init) (EVP_PKEY_CTX *ctx),
151                                      int (**pverify) (EVP_PKEY_CTX *ctx,
152                                                       const unsigned char *sig,
153                                                       size_t siglen,
154                                                       const unsigned char *tbs,
155                                                       size_t tbslen));
156        void EVP_PKEY_meth_get_verify_recover(const EVP_PKEY_METHOD *pmeth,
157                                              int (**pverify_recover_init) (EVP_PKEY_CTX
158                                                                            *ctx),
159                                              int (**pverify_recover) (EVP_PKEY_CTX
160                                                                       *ctx,
161                                                                       unsigned char
162                                                                       *sig,
163                                                                       size_t *siglen,
164                                                                       const unsigned
165                                                                       char *tbs,
166                                                                       size_t tbslen));
167        void EVP_PKEY_meth_get_signctx(const EVP_PKEY_METHOD *pmeth,
168                                       int (**psignctx_init) (EVP_PKEY_CTX *ctx,
169                                                              EVP_MD_CTX *mctx),
170                                       int (**psignctx) (EVP_PKEY_CTX *ctx,
171                                                         unsigned char *sig,
172                                                         size_t *siglen,
173                                                         EVP_MD_CTX *mctx));
174        void EVP_PKEY_meth_get_verifyctx(const EVP_PKEY_METHOD *pmeth,
175                                         int (**pverifyctx_init) (EVP_PKEY_CTX *ctx,
176                                                                  EVP_MD_CTX *mctx),
177                                         int (**pverifyctx) (EVP_PKEY_CTX *ctx,
178                                                             const unsigned char *sig,
179                                                             int siglen,
180                                                             EVP_MD_CTX *mctx));
181        void EVP_PKEY_meth_get_encrypt(const EVP_PKEY_METHOD *pmeth,
182                                       int (**pencrypt_init) (EVP_PKEY_CTX *ctx),
183                                       int (**pencryptfn) (EVP_PKEY_CTX *ctx,
184                                                           unsigned char *out,
185                                                           size_t *outlen,
186                                                           const unsigned char *in,
187                                                           size_t inlen));
188        void EVP_PKEY_meth_get_decrypt(const EVP_PKEY_METHOD *pmeth,
189                                       int (**pdecrypt_init) (EVP_PKEY_CTX *ctx),
190                                       int (**pdecrypt) (EVP_PKEY_CTX *ctx,
191                                                         unsigned char *out,
192                                                         size_t *outlen,
193                                                         const unsigned char *in,
194                                                         size_t inlen));
195        void EVP_PKEY_meth_get_derive(const EVP_PKEY_METHOD *pmeth,
196                                      int (**pderive_init) (EVP_PKEY_CTX *ctx),
197                                      int (**pderive) (EVP_PKEY_CTX *ctx,
198                                                       unsigned char *key,
199                                                       size_t *keylen));
200        void EVP_PKEY_meth_get_ctrl(const EVP_PKEY_METHOD *pmeth,
201                                    int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1,
202                                                   void *p2),
203                                    int (**pctrl_str) (EVP_PKEY_CTX *ctx,
204                                                       const char *type,
205                                                       const char *value));
206        void EVP_PKEY_meth_get_check(const EVP_PKEY_METHOD *pmeth,
207                                     int (**pcheck) (EVP_PKEY *pkey));
208        void EVP_PKEY_meth_get_public_check(const EVP_PKEY_METHOD *pmeth,
209                                            int (**pcheck) (EVP_PKEY *pkey));
210        void EVP_PKEY_meth_get_param_check(const EVP_PKEY_METHOD *pmeth,
211                                           int (**pcheck) (EVP_PKEY *pkey));
212        void EVP_PKEY_meth_get_digest_custom(EVP_PKEY_METHOD *pmeth,
213                                            int (**pdigest_custom) (EVP_PKEY_CTX *ctx,
214                                                                    EVP_MD_CTX *mctx));
215

DESCRIPTION

217       EVP_PKEY_METHOD is a structure which holds a set of methods for a
218       specific public key cryptographic algorithm. Those methods are usually
219       used to perform different jobs, such as generating a key, signing or
220       verifying, encrypting or decrypting, etc.
221
222       There are two places where the EVP_PKEY_METHOD objects are stored: one
223       is a built-in static array representing the standard methods for
224       different algorithms, and the other one is a stack of user-defined
225       application-specific methods, which can be manipulated by using
226       EVP_PKEY_meth_add0(3).
227
228       The EVP_PKEY_METHOD objects are usually referenced by EVP_PKEY_CTX
229       objects.
230
231   Methods
232       The methods are the underlying implementations of a particular public
233       key algorithm present by the EVP_PKEY_CTX object.
234
235        int (*init) (EVP_PKEY_CTX *ctx);
236        int (*copy) (EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src);
237        void (*cleanup) (EVP_PKEY_CTX *ctx);
238
239       The init() method is called to initialize algorithm-specific data when
240       a new EVP_PKEY_CTX is created. As opposed to init(), the cleanup()
241       method is called when an EVP_PKEY_CTX is freed. The copy() method is
242       called when an EVP_PKEY_CTX is being duplicated. Refer to
243       EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_new_id(3), EVP_PKEY_CTX_free(3) and
244       EVP_PKEY_CTX_dup(3).
245
246        int (*paramgen_init) (EVP_PKEY_CTX *ctx);
247        int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
248
249       The paramgen_init() and paramgen() methods deal with key parameter
250       generation.  They are called by EVP_PKEY_paramgen_init(3) and
251       EVP_PKEY_paramgen(3) to handle the parameter generation process.
252
253        int (*keygen_init) (EVP_PKEY_CTX *ctx);
254        int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey);
255
256       The keygen_init() and keygen() methods are used to generate the actual
257       key for the specified algorithm. They are called by
258       EVP_PKEY_keygen_init(3) and EVP_PKEY_keygen(3).
259
260        int (*sign_init) (EVP_PKEY_CTX *ctx);
261        int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
262                     const unsigned char *tbs, size_t tbslen);
263
264       The sign_init() and sign() methods are used to generate the signature
265       of a piece of data using a private key. They are called by
266       EVP_PKEY_sign_init(3) and EVP_PKEY_sign(3).
267
268        int (*verify_init) (EVP_PKEY_CTX *ctx);
269        int (*verify) (EVP_PKEY_CTX *ctx,
270                       const unsigned char *sig, size_t siglen,
271                       const unsigned char *tbs, size_t tbslen);
272
273       The verify_init() and verify() methods are used to verify whether a
274       signature is valid. They are called by EVP_PKEY_verify_init(3) and
275       EVP_PKEY_verify(3).
276
277        int (*verify_recover_init) (EVP_PKEY_CTX *ctx);
278        int (*verify_recover) (EVP_PKEY_CTX *ctx,
279                               unsigned char *rout, size_t *routlen,
280                               const unsigned char *sig, size_t siglen);
281
282       The verify_recover_init() and verify_recover() methods are used to
283       verify a signature and then recover the digest from the signature (for
284       instance, a signature that was generated by RSA signing algorithm).
285       They are called by EVP_PKEY_verify_recover_init(3) and
286       EVP_PKEY_verify_recover(3).
287
288        int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
289        int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
290                        EVP_MD_CTX *mctx);
291
292       The signctx_init() and signctx() methods are used to sign a digest
293       present by a EVP_MD_CTX object. They are called by the EVP_DigestSign
294       functions. See EVP_DigestSignInit(3) for detail.
295
296        int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
297        int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen,
298                          EVP_MD_CTX *mctx);
299
300       The verifyctx_init() and verifyctx() methods are used to verify a
301       signature against the data in a EVP_MD_CTX object. They are called by
302       the various EVP_DigestVerify functions. See EVP_DigestVerifyInit(3) for
303       detail.
304
305        int (*encrypt_init) (EVP_PKEY_CTX *ctx);
306        int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
307                        const unsigned char *in, size_t inlen);
308
309       The encrypt_init() and encrypt() methods are used to encrypt a piece of
310       data.  They are called by EVP_PKEY_encrypt_init(3) and
311       EVP_PKEY_encrypt(3).
312
313        int (*decrypt_init) (EVP_PKEY_CTX *ctx);
314        int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
315                        const unsigned char *in, size_t inlen);
316
317       The decrypt_init() and decrypt() methods are used to decrypt a piece of
318       data.  They are called by EVP_PKEY_decrypt_init(3) and
319       EVP_PKEY_decrypt(3).
320
321        int (*derive_init) (EVP_PKEY_CTX *ctx);
322        int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
323
324       The derive_init() and derive() methods are used to derive the shared
325       secret from a public key algorithm (for instance, the DH algorithm).
326       They are called by EVP_PKEY_derive_init(3) and EVP_PKEY_derive(3).
327
328        int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2);
329        int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value);
330
331       The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
332       settings. See EVP_PKEY_CTX_ctrl(3) and related functions for detail.
333
334        int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen,
335                           const unsigned char *tbs, size_t tbslen);
336        int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig,
337                             size_t siglen, const unsigned char *tbs,
338                             size_t tbslen);
339
340       The digestsign() and digestverify() methods are used to generate or
341       verify a signature in a one-shot mode. They could be called by
342       EVP_DigetSign(3) and EVP_DigestVerify(3).
343
344        int (*check) (EVP_PKEY *pkey);
345        int (*public_check) (EVP_PKEY *pkey);
346        int (*param_check) (EVP_PKEY *pkey);
347
348       The check(), public_check() and param_check() methods are used to
349       validate a key-pair, the public component and parameters respectively
350       for a given pkey.  They could be called by EVP_PKEY_check(3),
351       EVP_PKEY_public_check(3) and EVP_PKEY_param_check(3) respectively.
352
353        int (*digest_custom) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
354
355       The digest_custom() method is used to generate customized digest
356       content before the real message is passed to functions like
357       EVP_DigestSignUpdate(3) or EVP_DigestVerifyInit(3). This is usually
358       required by some public key signature algorithms like SM2 which
359       requires a hashed prefix to the message to be signed. The
360       digest_custom() function will be called by EVP_DigestSignInit(3) and
361       EVP_DigestVerifyInit(3).
362
363   Functions
364       EVP_PKEY_meth_new() creates and returns a new EVP_PKEY_METHOD object,
365       and associates the given id and flags. The following flags are
366       supported:
367
368        EVP_PKEY_FLAG_AUTOARGLEN
369        EVP_PKEY_FLAG_SIGCTX_CUSTOM
370
371       If an EVP_PKEY_METHOD is set with the EVP_PKEY_FLAG_AUTOARGLEN flag,
372       the maximum size of the output buffer will be automatically calculated
373       or checked in corresponding EVP methods by the EVP framework. Thus the
374       implementations of these methods don't need to care about handling the
375       case of returning output buffer size by themselves. For details on the
376       output buffer size, refer to EVP_PKEY_sign(3).
377
378       The EVP_PKEY_FLAG_SIGCTX_CUSTOM is used to indicate the signctx()
379       method of an EVP_PKEY_METHOD is always called by the EVP framework
380       while doing a digest signing operation by calling
381       EVP_DigestSignFinal(3).
382
383       EVP_PKEY_meth_free() frees an existing EVP_PKEY_METHOD pointed by
384       pmeth.
385
386       EVP_PKEY_meth_copy() copies an EVP_PKEY_METHOD object from src to dst.
387
388       EVP_PKEY_meth_find() finds an EVP_PKEY_METHOD object with the id.  This
389       function first searches through the user-defined method objects and
390       then the built-in objects.
391
392       EVP_PKEY_meth_add0() adds pmeth to the user defined stack of methods.
393
394       EVP_PKEY_meth_remove() removes an EVP_PKEY_METHOD object added by
395       EVP_PKEY_meth_add0().
396
397       The EVP_PKEY_meth_set functions set the corresponding fields of
398       EVP_PKEY_METHOD structure with the arguments passed.
399
400       The EVP_PKEY_meth_get functions get the corresponding fields of
401       EVP_PKEY_METHOD structure to the arguments provided.
402

RETURN VALUES

404       EVP_PKEY_meth_new() returns a pointer to a new EVP_PKEY_METHOD object
405       or returns NULL on error.
406
407       EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values.
408
409       EVP_PKEY_meth_find() returns a pointer to the found EVP_PKEY_METHOD
410       object or returns NULL if not found.
411
412       EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0 if
413       an error occurred.
414
415       EVP_PKEY_meth_remove() returns 1 if method is removed successfully or 0
416       if an error occurred.
417
418       All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return
419       values. For the 'get' functions, function pointers are returned by
420       arguments.
421
423       Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
424
425       Licensed under the OpenSSL license (the "License").  You may not use
426       this file except in compliance with the License.  You can obtain a copy
427       in the file LICENSE in the source distribution or at
428       <https://www.openssl.org/source/license.html>.
429
430
431
4321.1.1                             2018-09-11              EVP_PKEY_METH_NEW(3)
Impressum