| blob | 079f5919f6ac89a19c1c95418abcc084e432fdd6 |
1 .\" $NetBSD: EVP_PKEY_keygen.3,v 1.14 2015/06/12 17:01:14 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .de Vb \" Begin verbatim text
12 .ft CW
13 .nf
14 .ne \\$1
15 ..
16 .de Ve \" End verbatim text
17 .ft R
18 .fi
19 ..
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
26 .tr \(*W-
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
28 .ie n \{\
29 . ds -- \(*W-
30 . ds PI pi
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
33 . ds L" ""
34 . ds R" ""
35 . ds C` ""
36 . ds C' ""
37 'br\}
38 .el\{\
39 . ds -- \|\(em\|
40 . ds PI \(*p
41 . ds L" ``
42 . ds R" ''
43 . ds C`
44 . ds C'
45 'br\}
46 .\"
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
48 .ie \n(.g .ds Aq \(aq
49 .el .ds Aq '
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .\"
56 .\" Avoid warning from groff about undefined register 'F'.
57 .de IX
58 ..
59 .nr rF 0
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
62 . if \nF \{
63 . de IX
64 . tm Index:\\$1\t\\n%\t"\\$2"
65 ..
66 . if !\nF==2 \{
67 . nr % 0
68 . nr F 2
69 . \}
70 . \}
71 .\}
72 .rr rF
73 .\"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
77 .if n \{\
78 . ds #H 0
79 . ds #V .8m
80 . ds #F .3m
81 . ds #[ \f1
82 . ds #] \fP
83 .\}
84 .if t \{\
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
86 . ds #V .6m
87 . ds #F 0
88 . ds #[ \&
89 . ds #] \&
90 .\}
91 . \" simple accents for nroff and troff
92 .if n \{\
93 . ds ' \&
94 . ds ` \&
95 . ds ^ \&
96 . ds , \&
97 . ds ~ ~
98 . ds /
99 .\}
100 .if t \{\
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
107 .\}
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
123 \{\
124 . ds : e
125 . ds 8 ss
126 . ds o a
127 . ds d- d\h'-1'\(ga
128 . ds D- D\h'-1'\(hy
129 . ds th \o'bp'
130 . ds Th \o'LP'
131 . ds ae ae
132 . ds Ae AE
133 .\}
134 .rm #[ #] #H #V #F C
135 .\" ========================================================================
136 .\"
137 .IX Title "EVP_PKEY_keygen 3"
138 .TH EVP_PKEY_keygen 3 "2013-02-05" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
141 .if n .ad l
142 .nh
143 .SH "NAME"
144 EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, EVP_PKEY_CTX_get_keygen_info, EVP_PKEVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data \- key and parameter generation functions
145 .SH "LIBRARY"
146 libcrypto, -lcrypto
147 .SH "SYNOPSIS"
148 .IX Header "SYNOPSIS"
149 .Vb 1
150 \& #include <openssl/evp.h>
151 \&
152 \& int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
153 \& int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
154 \& int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
155 \& int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
156 \&
157 \& typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
158 \&
159 \& void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
160 \& EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
161 \&
162 \& int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
163 \&
164 \& void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
165 \& void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
166 .Ve
167 .SH "DESCRIPTION"
168 .IX Header "DESCRIPTION"
169 The \fIEVP_PKEY_keygen_init()\fR function initializes a public key algorithm
170 context using key \fBpkey\fR for a key genration operation.
171 .PP
172 The \fIEVP_PKEY_keygen()\fR function performs a key generation operation, the
173 generated key is written to \fBppkey\fR.
174 .PP
175 The functions \fIEVP_PKEY_paramgen_init()\fR and \fIEVP_PKEY_paramgen()\fR are similar
176 except parameters are generated.
177 .PP
178 The function \fIEVP_PKEY_set_cb()\fR sets the key or parameter generation callback
179 to \fBcb\fR. The function \fIEVP_PKEY_CTX_get_cb()\fR returns the key or parameter
180 generation callback.
181 .PP
182 The function \fIEVP_PKEY_CTX_get_keygen_info()\fR returns parameters associated
183 with the generation operation. If \fBidx\fR is \-1 the total number of
184 parameters available is returned. Any non negative value returns the value of
185 that parameter. \fIEVP_PKEY_CTX_gen_keygen_info()\fR with a non-negative value for
186 \&\fBidx\fR should only be called within the generation callback.
187 .PP
188 If the callback returns 0 then the key genration operation is aborted and an
189 error occurs. This might occur during a time consuming operation where
190 a user clicks on a \*(L"cancel\*(R" button.
191 .PP
192 The functions \fIEVP_PKEY_CTX_set_app_data()\fR and \fIEVP_PKEY_CTX_get_app_data()\fR set
193 and retrieve an opaque pointer. This can be used to set some application
194 defined value which can be retrieved in the callback: for example a handle
195 which is used to update a \*(L"progress dialog\*(R".
196 .SH "NOTES"
197 .IX Header "NOTES"
198 After the call to \fIEVP_PKEY_keygen_init()\fR or \fIEVP_PKEY_paramgen_init()\fR algorithm
199 specific control operations can be performed to set any appropriate parameters
200 for the operation.
201 .PP
202 The functions \fIEVP_PKEY_keygen()\fR and \fIEVP_PKEY_paramgen()\fR can be called more than
203 once on the same context if several operations are performed using the same
204 parameters.
205 .PP
206 The meaning of the parameters passed to the callback will depend on the
207 algorithm and the specifiic implementation of the algorithm. Some might not
208 give any useful information at all during key or parameter generation. Others
209 might not even call the callback.
210 .PP
211 The operation performed by key or parameter generation depends on the algorithm
212 used. In some cases (e.g. \s-1EC\s0 with a supplied named curve) the \*(L"generation\*(R"
213 option merely sets the appropriate fields in an \s-1EVP_PKEY\s0 structure.
214 .PP
215 In OpenSSL an \s-1EVP_PKEY\s0 structure containing a private key also contains the
216 public key components and parameters (if any). An OpenSSL private key is
217 equivalent to what some libraries call a \*(L"key pair\*(R". A private key can be used
218 in functions which require the use of a public key or parameters.
219 .SH "RETURN VALUES"
220 .IX Header "RETURN VALUES"
221 \&\fIEVP_PKEY_keygen_init()\fR, \fIEVP_PKEY_paramgen_init()\fR, \fIEVP_PKEY_keygen()\fR and
222 \&\fIEVP_PKEY_paramgen()\fR return 1 for success and 0 or a negative value for failure.
223 In particular a return value of \-2 indicates the operation is not supported by
224 the public key algorithm.
225 .SH "EXAMPLES"
226 .IX Header "EXAMPLES"
227 Generate a 2048 bit \s-1RSA\s0 key:
228 .PP
229 .Vb 2
230 \& #include <openssl/evp.h>
231 \& #include <openssl/rsa.h>
232 \&
233 \& EVP_PKEY_CTX *ctx;
234 \& EVP_PKEY *pkey = NULL;
235 \& ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
236 \& if (!ctx)
237 \& /* Error occurred */
238 \& if (EVP_PKEY_keygen_init(ctx) <= 0)
239 \& /* Error */
240 \& if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
241 \& /* Error */
242 \&
243 \& /* Generate key */
244 \& if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
245 \& /* Error */
246 .Ve
247 .PP
248 Generate a key from a set of parameters:
249 .PP
250 .Vb 2
251 \& #include <openssl/evp.h>
252 \& #include <openssl/rsa.h>
253 \&
254 \& EVP_PKEY_CTX *ctx;
255 \& EVP_PKEY *pkey = NULL, *param;
256 \& /* Assumed param is set up already */
257 \& ctx = EVP_PKEY_CTX_new(param);
258 \& if (!ctx)
259 \& /* Error occurred */
260 \& if (EVP_PKEY_keygen_init(ctx) <= 0)
261 \& /* Error */
262 \&
263 \& /* Generate key */
264 \& if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
265 \& /* Error */
266 .Ve
267 .PP
268 Example of generation callback for OpenSSL public key implementations:
269 .PP
270 .Vb 1
271 \& /* Application data is a BIO to output status to */
272 \&
273 \& EVP_PKEY_CTX_set_app_data(ctx, status_bio);
274 \&
275 \& static int genpkey_cb(EVP_PKEY_CTX *ctx)
276 \& {
277 \& char c=\*(Aq*\*(Aq;
278 \& BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
279 \& int p;
280 \& p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
281 \& if (p == 0) c=\*(Aq.\*(Aq;
282 \& if (p == 1) c=\*(Aq+\*(Aq;
283 \& if (p == 2) c=\*(Aq*\*(Aq;
284 \& if (p == 3) c=\*(Aq\en\*(Aq;
285 \& BIO_write(b,&c,1);
286 \& (void)BIO_flush(b);
287 \& return 1;
288 \& }
289 .Ve
290 .SH "SEE ALSO"
291 .IX Header "SEE ALSO"
292 \&\fIEVP_PKEY_CTX_new\fR\|(3),
293 \&\fIEVP_PKEY_encrypt\fR\|(3),
294 \&\fIEVP_PKEY_decrypt\fR\|(3),
295 \&\fIEVP_PKEY_sign\fR\|(3),
296 \&\fIEVP_PKEY_verify\fR\|(3),
297 \&\fIEVP_PKEY_verify_recover\fR\|(3),
298 \&\fIEVP_PKEY_derive\fR\|(3)
299 .SH "HISTORY"
300 .IX Header "HISTORY"
301 These functions were first added to OpenSSL 1.0.0.