]>
Commit | Line | Data |
---|---|---|
49131a7d DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
3f2181e6 | 5 | openssl-genpkey, |
49131a7d DSH |
6 | genpkey - generate a private key |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<genpkey> | |
169394d4 | 11 | [B<-help>] |
49131a7d DSH |
12 | [B<-out filename>] |
13 | [B<-outform PEM|DER>] | |
14 | [B<-pass arg>] | |
e75138ab | 15 | [B<-I<cipher>>] |
49131a7d DSH |
16 | [B<-engine id>] |
17 | [B<-paramfile file>] | |
18 | [B<-algorithm alg>] | |
19 | [B<-pkeyopt opt:value>] | |
20 | [B<-genparam>] | |
21 | [B<-text>] | |
22 | ||
23 | =head1 DESCRIPTION | |
24 | ||
25 | The B<genpkey> command generates a private key. | |
26 | ||
27 | =head1 OPTIONS | |
28 | ||
29 | =over 4 | |
30 | ||
169394d4 MR |
31 | =item B<-help> |
32 | ||
33 | Print out a usage message. | |
34 | ||
49131a7d DSH |
35 | =item B<-out filename> |
36 | ||
169394d4 MR |
37 | Output the key to the specified file. If this argument is not specified then |
38 | standard output is used. | |
49131a7d DSH |
39 | |
40 | =item B<-outform DER|PEM> | |
41 | ||
7477c83e | 42 | This specifies the output format DER or PEM. The default format is PEM. |
49131a7d DSH |
43 | |
44 | =item B<-pass arg> | |
45 | ||
c4de074e | 46 | The output file password source. For more information about the format of B<arg> |
9b86974e | 47 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. |
49131a7d | 48 | |
e75138ab | 49 | =item B<-I<cipher>> |
49131a7d | 50 | |
5ce60a20 | 51 | This option encrypts the private key with the supplied cipher. Any algorithm |
49131a7d DSH |
52 | name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>. |
53 | ||
54 | =item B<-engine id> | |
55 | ||
c4de074e | 56 | Specifying an engine (by its unique B<id> string) will cause B<genpkey> |
49131a7d DSH |
57 | to attempt to obtain a functional reference to the specified engine, |
58 | thus initialising it if needed. The engine will then be set as the default | |
e4549295 DSH |
59 | for all available algorithms. If used this option should precede all other |
60 | options. | |
49131a7d DSH |
61 | |
62 | =item B<-algorithm alg> | |
63 | ||
c4de074e | 64 | Public key algorithm to use such as RSA, DSA or DH. If used this option must |
f489ab31 | 65 | precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> |
e4549295 | 66 | are mutually exclusive. |
49131a7d DSH |
67 | |
68 | =item B<-pkeyopt opt:value> | |
69 | ||
c4de074e | 70 | Set the public key algorithm option B<opt> to B<value>. The precise set of |
49131a7d DSH |
71 | options supported depends on the public key algorithm used and its |
72 | implementation. See B<KEY GENERATION OPTIONS> below for more details. | |
73 | ||
74 | =item B<-genparam> | |
75 | ||
c4de074e | 76 | Generate a set of parameters instead of a private key. If used this option must |
77a795e4 | 77 | precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options. |
49131a7d DSH |
78 | |
79 | =item B<-paramfile filename> | |
80 | ||
81 | Some public key algorithms generate a private key based on a set of parameters. | |
e4549295 DSH |
82 | They can be supplied using this option. If this option is used the public key |
83 | algorithm used is determined by the parameters. If used this option must | |
77a795e4 | 84 | precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> |
e4549295 DSH |
85 | are mutually exclusive. |
86 | ||
87 | =item B<-text> | |
88 | ||
89 | Print an (unencrypted) text representation of private and public keys and | |
90 | parameters along with the PEM or DER structure. | |
49131a7d DSH |
91 | |
92 | =back | |
93 | ||
94 | =head1 KEY GENERATION OPTIONS | |
95 | ||
4c583c36 | 96 | The options supported by each algorithm and indeed each implementation of an |
49131a7d DSH |
97 | algorithm can vary. The options for the OpenSSL implementations are detailed |
98 | below. | |
99 | ||
100 | =head1 RSA KEY GENERATION OPTIONS | |
101 | ||
102 | =over 4 | |
103 | ||
104 | =item B<rsa_keygen_bits:numbits> | |
105 | ||
106 | The number of bits in the generated key. If not specified 1024 is used. | |
107 | ||
665d899f PY |
108 | =item B<rsa_keygen_primes:numprimes> |
109 | ||
110 | The number of primes in the generated key. If not specified 2 is used. | |
111 | ||
112 | =item B<rsa_keygen_pubexp:value> | |
113 | ||
114 | The RSA public exponent value. This can be a large decimal or | |
115 | hexadecimal value if preceded by B<0x>. Default value is 65537. | |
116 | ||
117 | =back | |
118 | ||
119 | =head1 RSA-PSS KEY GENERATION OPTIONS | |
120 | ||
121 | Note: by default an B<RSA-PSS> key has no parameter restrictions. | |
122 | ||
123 | =over 4 | |
124 | ||
125 | =item B<rsa_keygen_bits:numbits>, B<rsa_keygen_pubexp:value> | |
126 | ||
127 | These options have the same meaning as the B<RSA> algorithm. | |
128 | ||
129 | =item B<rsa_pss_keygen_md:digest> | |
130 | ||
49131a7d DSH |
131 | =item B<rsa_keygen_pubexp:value> |
132 | ||
133 | The RSA public exponent value. This can be a large decimal or | |
134 | hexadecimal value if preceded by B<0x>. Default value is 65537. | |
135 | ||
136 | =back | |
137 | ||
7751098e DSH |
138 | =head1 RSA-PSS KEY GENERATION OPTIONS |
139 | ||
140 | Note: by default an B<RSA-PSS> key has no parameter restrictions. | |
141 | ||
142 | =over 4 | |
143 | ||
144 | =item B<rsa_keygen_bits:numbits>, B<rsa_keygen_pubexp:value> | |
145 | ||
146 | These options have the same meaning as the B<RSA> algorithm. | |
147 | ||
148 | =item B<rsa_pss_keygen_md:digest> | |
149 | ||
150 | If set the key is restricted and can only use B<digest> for signing. | |
151 | ||
152 | =item B<rsa_pss_keygen_mgf1_md:digest> | |
153 | ||
154 | If set the key is restricted and can only use B<digest> as it's MGF1 | |
155 | parameter. | |
156 | ||
157 | =item B<rsa_pss_keygen_saltlen:len> | |
158 | ||
159 | If set the key is restricted and B<len> specifies the minimum salt length. | |
160 | ||
161 | =back | |
162 | ||
49131a7d DSH |
163 | =head1 DSA PARAMETER GENERATION OPTIONS |
164 | ||
165 | =over 4 | |
166 | ||
167 | =item B<dsa_paramgen_bits:numbits> | |
168 | ||
169 | The number of bits in the generated parameters. If not specified 1024 is used. | |
170 | ||
677741f8 AP |
171 | =back |
172 | ||
49131a7d DSH |
173 | =head1 DH PARAMETER GENERATION OPTIONS |
174 | ||
175 | =over 4 | |
176 | ||
177 | =item B<dh_paramgen_prime_len:numbits> | |
178 | ||
179 | The number of bits in the prime parameter B<p>. | |
180 | ||
181 | =item B<dh_paramgen_generator:value> | |
182 | ||
183 | The value to use for the generator B<g>. | |
184 | ||
618eb125 DSH |
185 | =item B<dh_rfc5114:num> |
186 | ||
187 | If this option is set then the appropriate RFC5114 parameters are used | |
188 | instead of generating new parameters. The value B<num> can take the | |
189 | values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of | |
190 | 1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup | |
191 | and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections | |
192 | 2.1, 2.2 and 2.3 respectively. | |
193 | ||
49131a7d DSH |
194 | =back |
195 | ||
196 | =head1 EC PARAMETER GENERATION OPTIONS | |
197 | ||
a528d4f0 | 198 | The EC parameter generation options below can also |
146ca72c DSH |
199 | be supplied as EC key generation options. This can (for example) generate a |
200 | key from a named curve without the need to use an explicit parameter file. | |
201 | ||
49131a7d DSH |
202 | =over 4 |
203 | ||
204 | =item B<ec_paramgen_curve:curve> | |
205 | ||
c4de074e | 206 | The EC curve to use. OpenSSL supports NIST curve names such as "P-256". |
146ca72c DSH |
207 | |
208 | =item B<ec_param_enc:encoding> | |
209 | ||
c4de074e | 210 | The encoding to use for parameters. The "encoding" parameter must be either |
146ca72c | 211 | "named_curve" or "explicit". |
49131a7d DSH |
212 | |
213 | =back | |
214 | ||
e5fa864f DSH |
215 | =head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS |
216 | ||
217 | Gost 2001 support is not enabled by default. To enable this algorithm, | |
218 | one should load the ccgost engine in the OpenSSL configuration file. | |
4c583c36 | 219 | See README.gost file in the engines/ccgost directory of the source |
e5fa864f DSH |
220 | distribution for more details. |
221 | ||
222 | Use of a parameter file for the GOST R 34.10 algorithm is optional. | |
223 | Parameters can be specified during key generation directly as well as | |
224 | during generation of parameter file. | |
225 | ||
226 | =over 4 | |
227 | ||
228 | =item B<paramset:name> | |
229 | ||
230 | Specifies GOST R 34.10-2001 parameter set according to RFC 4357. | |
231 | Parameter set can be specified using abbreviated name, object short name or | |
232 | numeric OID. Following parameter sets are supported: | |
233 | ||
234 | paramset OID Usage | |
235 | A 1.2.643.2.2.35.1 Signature | |
236 | B 1.2.643.2.2.35.2 Signature | |
237 | C 1.2.643.2.2.35.3 Signature | |
238 | XA 1.2.643.2.2.36.0 Key exchange | |
239 | XB 1.2.643.2.2.36.1 Key exchange | |
240 | test 1.2.643.2.2.35.0 Test purposes | |
241 | ||
242 | =back | |
243 | ||
a2eecb5d | 244 | =head1 X25519 and X448 KEY GENERATION OPTIONS |
e5fa864f | 245 | |
a2eecb5d MC |
246 | The X25519 and X448 algorithms do not currently support any key generation |
247 | options. | |
e5fa864f | 248 | |
49131a7d DSH |
249 | =head1 NOTES |
250 | ||
251 | The use of the genpkey program is encouraged over the algorithm specific | |
252 | utilities because additional algorithm options and ENGINE provided algorithms | |
253 | can be used. | |
254 | ||
255 | =head1 EXAMPLES | |
256 | ||
257 | Generate an RSA private key using default parameters: | |
258 | ||
146ca72c | 259 | openssl genpkey -algorithm RSA -out key.pem |
49131a7d DSH |
260 | |
261 | Encrypt output private key using 128 bit AES and the passphrase "hello": | |
262 | ||
e5fa864f | 263 | openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello |
49131a7d DSH |
264 | |
265 | Generate a 2048 bit RSA key using 3 as the public exponent: | |
266 | ||
e5fa864f | 267 | openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \ |
1bc74519 | 268 | -pkeyopt rsa_keygen_pubexp:3 |
49131a7d DSH |
269 | |
270 | Generate 1024 bit DSA parameters: | |
271 | ||
272 | openssl genpkey -genparam -algorithm DSA -out dsap.pem \ | |
1bc74519 | 273 | -pkeyopt dsa_paramgen_bits:1024 |
49131a7d DSH |
274 | |
275 | Generate DSA key from parameters: | |
276 | ||
146ca72c | 277 | openssl genpkey -paramfile dsap.pem -out dsakey.pem |
49131a7d DSH |
278 | |
279 | Generate 1024 bit DH parameters: | |
280 | ||
281 | openssl genpkey -genparam -algorithm DH -out dhp.pem \ | |
1bc74519 | 282 | -pkeyopt dh_paramgen_prime_len:1024 |
49131a7d | 283 | |
618eb125 DSH |
284 | Output RFC5114 2048 bit DH parameters with 224 bit subgroup: |
285 | ||
286 | openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2 | |
287 | ||
49131a7d DSH |
288 | Generate DH key from parameters: |
289 | ||
146ca72c DSH |
290 | openssl genpkey -paramfile dhp.pem -out dhkey.pem |
291 | ||
292 | Generate EC parameters: | |
293 | ||
294 | openssl genpkey -genparam -algorithm EC -out ecp.pem \ | |
1bc74519 RS |
295 | -pkeyopt ec_paramgen_curve:secp384r1 \ |
296 | -pkeyopt ec_param_enc:named_curve | |
146ca72c DSH |
297 | |
298 | Generate EC key from parameters: | |
299 | ||
300 | openssl genpkey -paramfile ecp.pem -out eckey.pem | |
301 | ||
a528d4f0 | 302 | Generate EC key directly: |
49131a7d | 303 | |
146ca72c | 304 | openssl genpkey -algorithm EC -out eckey.pem \ |
1bc74519 RS |
305 | -pkeyopt ec_paramgen_curve:P-384 \ |
306 | -pkeyopt ec_param_enc:named_curve | |
49131a7d | 307 | |
c082201a DSH |
308 | Generate an X25519 private key: |
309 | ||
310 | openssl genpkey -algorithm X25519 -out xkey.pem | |
311 | ||
a528d4f0 RS |
312 | =head1 HISTORY |
313 | ||
314 | The ability to use NIST curve names, and to generate an EC key directly, | |
315 | were added in OpenSSL 1.0.2. | |
316 | ||
e2f92610 RS |
317 | =head1 COPYRIGHT |
318 | ||
b0edda11 | 319 | Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
320 | |
321 | Licensed under the OpenSSL license (the "License"). You may not use | |
322 | this file except in compliance with the License. You can obtain a copy | |
323 | in the file LICENSE in the source distribution or at | |
324 | L<https://www.openssl.org/source/license.html>. | |
325 | ||
326 | =cut |