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