EVP_PKEY_CTX_set_cb(3ssl)

1EVP_PKEY_keygen(3)                  OpenSSL                 EVP_PKEY_keygen(3)
2
3
4

NAME

6       EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init,
7       EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
8       EVP_PKEY_CTX_get_keygen_info, EVP_PKEVP_PKEY_CTX_set_app_data,
9       EVP_PKEY_CTX_get_app_data - key and parameter generation functions
10

SYNOPSIS

12        #include <openssl/evp.h>
13
14        int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
15        int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
16        int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
17        int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
18
19        typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
20
21        void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
22        EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
23
24        int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
25
26        void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
27        void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
28

DESCRIPTION

30       The EVP_PKEY_keygen_init() function initializes a public key algorithm
31       context using key pkey for a key genration operation.
32
33       The EVP_PKEY_keygen() function performs a key generation operation, the
34       generated key is written to ppkey.
35
36       The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are
37       similar except parameters are generated.
38
39       The function EVP_PKEY_set_cb() sets the key or parameter generation
40       callback to cb. The function EVP_PKEY_CTX_get_cb() returns the key or
41       parameter generation callback.
42
43       The function EVP_PKEY_CTX_get_keygen_info() returns parameters
44       associated with the generation operation. If idx is -1 the total number
45       of parameters available is returned. Any non negative value returns the
46       value of that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-
47       negative value for idx should only be called within the generation
48       callback.
49
50       If the callback returns 0 then the key genration operation is aborted
51       and an error occurs. This might occur during a time consuming operation
52       where a user clicks on a "cancel" button.
53
54       The functions EVP_PKEY_CTX_set_app_data() and
55       EVP_PKEY_CTX_get_app_data() set and retrieve an opaque pointer. This
56       can be used to set some application defined value which can be
57       retrieved in the callback: for example a handle which is used to update
58       a "progress dialog".
59

NOTES

61       After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init()
62       algorithm specific control operations can be performed to set any
63       appropriate parameters for the operation.
64
65       The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called
66       more than once on the same context if several operations are performed
67       using the same parameters.
68
69       The meaning of the parameters passed to the callback will depend on the
70       algorithm and the specifiic implementation of the algorithm. Some might
71       not give any useful information at all during key or parameter
72       generation. Others might not even call the callback.
73
74       The operation performed by key or parameter generation depends on the
75       algorithm used. In some cases (e.g. EC with a supplied named curve) the
76       "generation" option merely sets the appropriate fields in an EVP_PKEY
77       structure.
78
79       In OpenSSL an EVP_PKEY structure containing a private key also contains
80       the public key components and parameters (if any). An OpenSSL private
81       key is equivalent to what some libraries call a "key pair". A private
82       key can be used in functions which require the use of a public key or
83       parameters.
84

RETURN VALUES

86       EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
87       EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for
88       failure.  In particular a return value of -2 indicates the operation is
89       not supported by the public key algorithm.
90

EXAMPLES

92       Generate a 2048 bit RSA key:
93
94        #include <openssl/evp.h>
95        #include <openssl/rsa.h>
96
97        EVP_PKEY_CTX *ctx;
98        EVP_PKEY *pkey = NULL;
99        ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
100        if (!ctx)
101               /* Error occurred */
102        if (EVP_PKEY_keygen_init(ctx) <= 0)
103               /* Error */
104        if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
105               /* Error */
106
107        /* Generate key */
108        if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
109               /* Error */
110
111       Generate a key from a set of parameters:
112
113        #include <openssl/evp.h>
114        #include <openssl/rsa.h>
115
116        EVP_PKEY_CTX *ctx;
117        EVP_PKEY *pkey = NULL, *param;
118        /* Assumed param is set up already */
119        ctx = EVP_PKEY_CTX_new(param);
120        if (!ctx)
121               /* Error occurred */
122        if (EVP_PKEY_keygen_init(ctx) <= 0)
123               /* Error */
124
125        /* Generate key */
126        if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
127               /* Error */
128
129       Example of generation callback for OpenSSL public key implementations:
130
131        /* Application data is a BIO to output status to */
132
133        EVP_PKEY_CTX_set_app_data(ctx, status_bio);
134
135        static int genpkey_cb(EVP_PKEY_CTX *ctx)
136               {
137               char c='*';
138               BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
139               int p;
140               p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
141               if (p == 0) c='.';
142               if (p == 1) c='+';
143               if (p == 2) c='*';
144               if (p == 3) c='\n';
145               BIO_write(b,&c,1);
146               (void)BIO_flush(b);
147               return 1;
148               }
149

HISTORY

156       These functions were first added to OpenSSL 1.0.0.
157
158
159
1601.0.2o                            2019-09-10                EVP_PKEY_keygen(3)