1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
.Dd $Mdocdate: November 3 2016 $
.Dt EVP_PKEY_KEYGEN 3
.Os
.Sh NAME
.Nm EVP_PKEY_keygen_init ,
.Nm EVP_PKEY_keygen ,
.Nm EVP_PKEY_paramgen_init ,
.Nm EVP_PKEY_paramgen ,
.Nm EVP_PKEY_CTX_set_cb ,
.Nm EVP_PKEY_CTX_get_cb ,
.Nm EVP_PKEY_CTX_get_keygen_info ,
.Nm EVP_PKEY_CTX_set_app_data ,
.Nm EVP_PKEY_CTX_get_app_data
.Nd key and parameter generation functions
.Sh SYNOPSIS
.In openssl/evp.h
.Ft int
.Fo EVP_PKEY_keygen_init
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Ft int
.Fo EVP_PKEY_keygen
.Fa "EVP_PKEY_CTX *ctx"
.Fa "EVP_PKEY **ppkey"
.Fc
.Ft int
.Fo EVP_PKEY_paramgen_init
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Ft int
.Fo EVP_PKEY_paramgen
.Fa "EVP_PKEY_CTX *ctx"
.Fa "EVP_PKEY **ppkey"
.Fc
.Ft typedef int
.Fo EVP_PKEY_gen_cb
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Ft void
.Fo EVP_PKEY_CTX_set_cb
.Fa "EVP_PKEY_CTX *ctx"
.Fa "EVP_PKEY_gen_cb *cb"
.Fc
.Ft EVP_PKEY_gen_cb *
.Fo EVP_PKEY_CTX_get_cb
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Ft int
.Fo EVP_PKEY_CTX_get_keygen_info
.Fa "EVP_PKEY_CTX *ctx"
.Fa "int idx"
.Fc
.Ft void
.Fo EVP_PKEY_CTX_set_app_data
.Fa "EVP_PKEY_CTX *ctx"
.Fa "void *data"
.Fc
.Ft void *
.Fo EVP_PKEY_CTX_get_app_data
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Sh DESCRIPTION
The
.Fn EVP_PKEY_keygen_init
function initializes a public key algorithm context using key
.Fa ctx->pkey
for a key generation operation.
.Pp
The
.Fn EVP_PKEY_keygen
function performs a key generation operation, the generated key is
written to
.Fa ppkey .
.Pp
The functions
.Fn EVP_PKEY_paramgen_init
and
.Fn EVP_PKEY_paramgen
are similar except parameters are generated.
.Pp
The function
.Fn EVP_PKEY_CTX_set_cb
sets the key or parameter generation callback to
.Fa cb .
The function
.Fn EVP_PKEY_CTX_get_cb
returns the key or parameter generation callback.
.Pp
The function
.Fn EVP_PKEY_CTX_get_keygen_info
returns parameters associated with the generation operation.
If
.Fa idx
is -1, the total number of parameters available is returned.
Any non negative value returns the value of that parameter.
.Fn EVP_PKEY_CTX_get_keygen_info
with a non-negative value for
.Fa idx
should only be called within the generation callback.
.Pp
If the callback returns 0, then the key generation operation is aborted
and an error occurs.
This might occur during a time consuming operation where a user clicks
on a "cancel" button.
.Pp
The functions
.Fn EVP_PKEY_CTX_set_app_data
and
.Fn EVP_PKEY_CTX_get_app_data
set and retrieve an opaque pointer.
This can be used to set some application defined value which can be
retrieved in the callback: for example a handle which is used to update
a "progress dialog".
.Pp
After the call to
.Fn EVP_PKEY_keygen_init
or
.Fn EVP_PKEY_paramgen_init ,
algorithm specific control operations can be performed to set any
appropriate parameters for the operation.
.Pp
The functions
.Fn EVP_PKEY_keygen
and
.Fn EVP_PKEY_paramgen
can be called more than once on the same context if several operations
are performed using the same parameters.
.Pp
The meaning of the parameters passed to the callback will depend on the
algorithm and the specific implementation of the algorithm.
Some might not give any useful information at all during key or
parameter generation.
Others might not even call the callback.
.Pp
The operation performed by key or parameter generation depends on the
algorithm used.
In some cases (e.g. EC with a supplied named curve) the "generation"
option merely sets the appropriate fields in an
.Vt EVP_PKEY
structure.
.Pp
In OpenSSL, an
.Vt EVP_PKEY
structure containing a private key also contains the public key
components and parameters (if any).
An OpenSSL private key is equivalent to what some libraries call a "key
pair".
A private key can be used in functions which require the use of a public
key or parameters.
.Sh RETURN VALUES
.Fn EVP_PKEY_keygen_init ,
.Fn EVP_PKEY_paramgen_init ,
.Fn EVP_PKEY_keygen ,
and
.Fn EVP_PKEY_paramgen
return 1 for success and 0 or a negative value for failure.
In particular, a return value of -2 indicates the operation is not
supported by the public key algorithm.
.Sh EXAMPLES
Generate a 2048 bit RSA key:
.Bd -literal
#include <openssl/evp.h>
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
EVP_PKEY *pkey = NULL;
ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_keygen_init(ctx) <= 0)
/* Error */
if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
/* Error */
/* Generate key */
if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
/* Error */
.Ed
.Pp
Generate a key from a set of parameters:
.Bd -literal
#include <openssl/evp.h>
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
EVP_PKEY *pkey = NULL, *param;
/* Assumed param is set up already */
ctx = EVP_PKEY_CTX_new(param);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_keygen_init(ctx) <= 0)
/* Error */
/* Generate key */
if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
/* Error */
.Ed
.Pp
Example of generation callback for OpenSSL public key implementations:
.Bd -literal
/* Application data is a BIO to output status to */
EVP_PKEY_CTX_set_app_data(ctx, status_bio);
static int
genpkey_cb(EVP_PKEY_CTX *ctx)
{
char c = '*';
BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
int p;
p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
if (p == 0)
c='.';
if (p == 1)
c='+';
if (p == 2)
c='*';
if (p == 3)
c='\en';
BIO_write(b,&c,1);
(void)BIO_flush(b);
return 1;
}
.Ed
.Sh SEE ALSO
.Xr EVP_PKEY_CTX_new 3 ,
.Xr EVP_PKEY_decrypt 3 ,
.Xr EVP_PKEY_derive 3 ,
.Xr EVP_PKEY_encrypt 3 ,
.Xr EVP_PKEY_sign 3 ,
.Xr EVP_PKEY_verify 3 ,
.Xr EVP_PKEY_verify_recover 3
.Sh HISTORY
These functions were first added to OpenSSL 1.0.0.
|
