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