]>
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>] | |
14 | [B<->I<cipher>] | |
15 | [B<-engine> I<id>] | |
16 | [B<-paramfile> I<file>] | |
17 | [B<-algorithm> I<alg>] | |
18 | [B<-pkeyopt> I<opt:value>] | |
49131a7d DSH |
19 | [B<-genparam>] |
20 | [B<-text>] | |
21 | ||
1738c0ce RS |
22 | =for comment ifdef engine |
23 | ||
49131a7d DSH |
24 | =head1 DESCRIPTION |
25 | ||
26 | The B<genpkey> command generates a private key. | |
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 | |
c4de074e | 47 | The output file password source. For more information about the format of B<arg> |
e8769719 | 48 | see L<openssl(1)/Pass phrase options>. |
49131a7d | 49 | |
e8769719 | 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 | |
c4de074e | 57 | Specifying an engine (by its unique B<id> string) will cause B<genpkey> |
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 | |
e8769719 | 82 | =item B<-pkeyopt> I<opt:value> |
49131a7d | 83 | |
c4de074e | 84 | Set the public key algorithm option B<opt> to B<value>. The precise set of |
49131a7d | 85 | options supported depends on the public key algorithm used and its |
77579510 MC |
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 | |
131 | hexadecimal value if preceded by B<0x>. Default value is 65537. | |
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 | ||
77579510 | 141 | =item B<rsa_keygen_bits:numbits>, B<rsa_keygen_primes:numprimes>, B<rsa_keygen_pubexp:value> |
7751098e DSH |
142 | |
143 | These options have the same meaning as the B<RSA> algorithm. | |
144 | ||
145 | =item B<rsa_pss_keygen_md:digest> | |
146 | ||
147 | If set the key is restricted and can only use B<digest> for signing. | |
148 | ||
149 | =item B<rsa_pss_keygen_mgf1_md:digest> | |
150 | ||
151 | If set the key is restricted and can only use B<digest> as it's MGF1 | |
152 | parameter. | |
153 | ||
154 | =item B<rsa_pss_keygen_saltlen:len> | |
155 | ||
156 | If set the key is restricted and B<len> specifies the minimum salt length. | |
157 | ||
158 | =back | |
159 | ||
77579510 MC |
160 | =head2 EC Key Generation Options |
161 | ||
162 | The EC key generation options can also be used for parameter generation. | |
49131a7d DSH |
163 | |
164 | =over 4 | |
165 | ||
77579510 | 166 | =item B<ec_paramgen_curve:curve> |
49131a7d | 167 | |
77579510 MC |
168 | The EC curve to use. OpenSSL supports NIST curve names such as "P-256". |
169 | ||
170 | =item B<ec_param_enc:encoding> | |
171 | ||
172 | The encoding to use for parameters. The "encoding" parameter must be either | |
173 | "named_curve" or "explicit". The default value is "named_curve". | |
49131a7d | 174 | |
677741f8 AP |
175 | =back |
176 | ||
77579510 MC |
177 | =head1 PARAMETER GENERATION OPTIONS |
178 | ||
179 | The options supported by each algorithm and indeed each implementation of an | |
180 | algorithm can vary. The options for the OpenSSL implementations are detailed | |
181 | below. | |
182 | ||
183 | =head2 DSA Parameter Generation Options | |
49131a7d DSH |
184 | |
185 | =over 4 | |
186 | ||
77579510 | 187 | =item B<dsa_paramgen_bits:numbits> |
49131a7d | 188 | |
70b0b977 | 189 | The number of bits in the generated prime. If not specified 2048 is used. |
49131a7d | 190 | |
77579510 | 191 | =item B<dsa_paramgen_q_bits:numbits> |
49131a7d | 192 | |
77579510 | 193 | The number of bits in the q parameter. Must be one of 160, 224 or 256. If not |
70b0b977 | 194 | specified 224 is used. |
49131a7d | 195 | |
77579510 | 196 | =item B<dsa_paramgen_md:digest> |
618eb125 | 197 | |
77579510 MC |
198 | The digest to use during parameter generation. Must be one of B<sha1>, B<sha224> |
199 | or B<sha256>. If set, then the number of bits in B<q> will match the output size | |
200 | of the specified digest and the B<dsa_paramgen_q_bits> parameter will be | |
201 | ignored. If not set, then a digest will be used that gives an output matching | |
202 | the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224 | |
203 | or B<sha256> if it is 256. | |
618eb125 | 204 | |
49131a7d DSH |
205 | =back |
206 | ||
77579510 | 207 | =head2 DH Parameter Generation Options |
146ca72c | 208 | |
49131a7d DSH |
209 | =over 4 |
210 | ||
77579510 | 211 | =item B<dh_paramgen_prime_len:numbits> |
146ca72c | 212 | |
70b0b977 | 213 | The number of bits in the prime parameter B<p>. The default is 2048. |
49131a7d | 214 | |
77579510 | 215 | =item B<dh_paramgen_subprime_len:numbits> |
49131a7d | 216 | |
77579510 MC |
217 | The number of bits in the sub prime parameter B<q>. The default is 256 if the |
218 | prime is at least 2048 bits long or 160 otherwise. Only relevant if used in | |
219 | conjunction with the B<dh_paramgen_type> option to generate X9.42 DH parameters. | |
e5fa864f | 220 | |
77579510 | 221 | =item B<dh_paramgen_generator:value> |
e5fa864f | 222 | |
77579510 | 223 | The value to use for the generator B<g>. The default is 2. |
e5fa864f | 224 | |
77579510 | 225 | =item B<dh_paramgen_type:value> |
e5fa864f | 226 | |
77579510 MC |
227 | The type of DH parameters to generate. Use 0 for PKCS#3 DH and 1 for X9.42 DH. |
228 | The default is 0. | |
e5fa864f | 229 | |
77579510 | 230 | =item B<dh_rfc5114:num> |
e5fa864f | 231 | |
77579510 MC |
232 | If this option is set, then the appropriate RFC5114 parameters are used |
233 | instead of generating new parameters. The value B<num> can take the | |
234 | values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of | |
235 | 1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup | |
236 | and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections | |
237 | 2.1, 2.2 and 2.3 respectively. If present this overrides all other DH parameter | |
238 | options. | |
e5fa864f DSH |
239 | |
240 | =back | |
241 | ||
77579510 | 242 | =head2 EC Parameter Generation Options |
e5fa864f | 243 | |
77579510 MC |
244 | The EC parameter generation options are the same as for key generation. See |
245 | L<EC Key Generation Options> above. | |
e5fa864f | 246 | |
49131a7d DSH |
247 | =head1 NOTES |
248 | ||
249 | The use of the genpkey program is encouraged over the algorithm specific | |
250 | utilities because additional algorithm options and ENGINE provided algorithms | |
251 | can be used. | |
252 | ||
253 | =head1 EXAMPLES | |
254 | ||
255 | Generate an RSA private key using default parameters: | |
256 | ||
146ca72c | 257 | openssl genpkey -algorithm RSA -out key.pem |
49131a7d DSH |
258 | |
259 | Encrypt output private key using 128 bit AES and the passphrase "hello": | |
260 | ||
e5fa864f | 261 | openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello |
49131a7d DSH |
262 | |
263 | Generate a 2048 bit RSA key using 3 as the public exponent: | |
264 | ||
dfee8626 RS |
265 | openssl genpkey -algorithm RSA -out key.pem \ |
266 | -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3 | |
49131a7d | 267 | |
77579510 | 268 | Generate 2048 bit DSA parameters: |
49131a7d DSH |
269 | |
270 | openssl genpkey -genparam -algorithm DSA -out dsap.pem \ | |
dfee8626 | 271 | -pkeyopt dsa_paramgen_bits:2048 |
49131a7d DSH |
272 | |
273 | Generate DSA key from parameters: | |
274 | ||
146ca72c | 275 | openssl genpkey -paramfile dsap.pem -out dsakey.pem |
49131a7d | 276 | |
77579510 | 277 | Generate 2048 bit DH parameters: |
49131a7d DSH |
278 | |
279 | openssl genpkey -genparam -algorithm DH -out dhp.pem \ | |
dfee8626 | 280 | -pkeyopt dh_paramgen_prime_len:2048 |
77579510 MC |
281 | |
282 | Generate 2048 bit X9.42 DH parameters: | |
283 | ||
284 | openssl genpkey -genparam -algorithm DH -out dhpx.pem \ | |
dfee8626 RS |
285 | -pkeyopt dh_paramgen_prime_len:2048 \ |
286 | -pkeyopt dh_paramgen_type:1 | |
49131a7d | 287 | |
618eb125 DSH |
288 | Output RFC5114 2048 bit DH parameters with 224 bit subgroup: |
289 | ||
290 | openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2 | |
291 | ||
49131a7d DSH |
292 | Generate DH key from parameters: |
293 | ||
146ca72c DSH |
294 | openssl genpkey -paramfile dhp.pem -out dhkey.pem |
295 | ||
296 | Generate EC parameters: | |
297 | ||
298 | openssl genpkey -genparam -algorithm EC -out ecp.pem \ | |
1bc74519 RS |
299 | -pkeyopt ec_paramgen_curve:secp384r1 \ |
300 | -pkeyopt ec_param_enc:named_curve | |
146ca72c DSH |
301 | |
302 | Generate EC key from parameters: | |
303 | ||
304 | openssl genpkey -paramfile ecp.pem -out eckey.pem | |
305 | ||
a528d4f0 | 306 | Generate EC key directly: |
49131a7d | 307 | |
146ca72c | 308 | openssl genpkey -algorithm EC -out eckey.pem \ |
1bc74519 RS |
309 | -pkeyopt ec_paramgen_curve:P-384 \ |
310 | -pkeyopt ec_param_enc:named_curve | |
49131a7d | 311 | |
c082201a DSH |
312 | Generate an X25519 private key: |
313 | ||
314 | openssl genpkey -algorithm X25519 -out xkey.pem | |
315 | ||
77579510 MC |
316 | Generate an ED448 private key: |
317 | ||
318 | openssl genpkey -algorithm ED448 -out xkey.pem | |
319 | ||
a528d4f0 RS |
320 | =head1 HISTORY |
321 | ||
322 | The ability to use NIST curve names, and to generate an EC key directly, | |
fc5ecadd DMSP |
323 | were added in OpenSSL 1.0.2. |
324 | The ability to generate X25519 keys was added in OpenSSL 1.1.0. | |
325 | The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1. | |
a528d4f0 | 326 | |
e2f92610 RS |
327 | =head1 COPYRIGHT |
328 | ||
b6b66573 | 329 | Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 330 | |
449040b4 | 331 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
332 | this file except in compliance with the License. You can obtain a copy |
333 | in the file LICENSE in the source distribution or at | |
334 | L<https://www.openssl.org/source/license.html>. | |
335 | ||
336 | =cut |