1 | =pod
|
---|
2 |
|
---|
3 | =head1 NAME
|
---|
4 |
|
---|
5 | openssl-genpkey,
|
---|
6 | genpkey - generate a private key
|
---|
7 |
|
---|
8 | =head1 SYNOPSIS
|
---|
9 |
|
---|
10 | B<openssl> B<genpkey>
|
---|
11 | [B<-help>]
|
---|
12 | [B<-out filename>]
|
---|
13 | [B<-outform PEM|DER>]
|
---|
14 | [B<-pass arg>]
|
---|
15 | [B<-I<cipher>>]
|
---|
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 |
|
---|
31 | =item B<-help>
|
---|
32 |
|
---|
33 | Print out a usage message.
|
---|
34 |
|
---|
35 | =item B<-out filename>
|
---|
36 |
|
---|
37 | Output the key to the specified file. If this argument is not specified then
|
---|
38 | standard output is used.
|
---|
39 |
|
---|
40 | =item B<-outform DER|PEM>
|
---|
41 |
|
---|
42 | This specifies the output format DER or PEM. The default format is PEM.
|
---|
43 |
|
---|
44 | =item B<-pass arg>
|
---|
45 |
|
---|
46 | The output file password source. For more information about the format of B<arg>
|
---|
47 | see L<openssl(1)/Pass Phrase Options>.
|
---|
48 |
|
---|
49 | =item B<-I<cipher>>
|
---|
50 |
|
---|
51 | This option encrypts the private key with the supplied cipher. Any algorithm
|
---|
52 | name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
|
---|
53 |
|
---|
54 | =item B<-engine id>
|
---|
55 |
|
---|
56 | Specifying an engine (by its unique B<id> string) will cause B<genpkey>
|
---|
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
|
---|
59 | for all available algorithms. If used this option should precede all other
|
---|
60 | options.
|
---|
61 |
|
---|
62 | =item B<-algorithm alg>
|
---|
63 |
|
---|
64 | Public key algorithm to use such as RSA, DSA or DH. If used this option must
|
---|
65 | precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
|
---|
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.
|
---|
80 |
|
---|
81 | =item B<-pkeyopt opt:value>
|
---|
82 |
|
---|
83 | Set the public key algorithm option B<opt> to B<value>. The precise set of
|
---|
84 | options supported depends on the public key algorithm used and its
|
---|
85 | implementation. See L<KEY GENERATION OPTIONS> and
|
---|
86 | L<PARAMETER GENERATION OPTIONS> below for more details.
|
---|
87 |
|
---|
88 | =item B<-genparam>
|
---|
89 |
|
---|
90 | Generate a set of parameters instead of a private key. If used this option must
|
---|
91 | precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options.
|
---|
92 |
|
---|
93 | =item B<-paramfile filename>
|
---|
94 |
|
---|
95 | Some public key algorithms generate a private key based on a set of parameters.
|
---|
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
|
---|
98 | precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
|
---|
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.
|
---|
105 |
|
---|
106 | =back
|
---|
107 |
|
---|
108 | =head1 KEY GENERATION OPTIONS
|
---|
109 |
|
---|
110 | The options supported by each algorithm and indeed each implementation of an
|
---|
111 | algorithm can vary. The options for the OpenSSL implementations are detailed
|
---|
112 | below. There are no key generation options defined for the X25519, X448, ED25519
|
---|
113 | or ED448 algorithms.
|
---|
114 |
|
---|
115 | =head2 RSA Key Generation Options
|
---|
116 |
|
---|
117 | =over 4
|
---|
118 |
|
---|
119 | =item B<rsa_keygen_bits:numbits>
|
---|
120 |
|
---|
121 | The number of bits in the generated key. If not specified 2048 is used.
|
---|
122 |
|
---|
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 |
|
---|
134 | =head2 RSA-PSS Key Generation Options
|
---|
135 |
|
---|
136 | Note: by default an B<RSA-PSS> key has no parameter restrictions.
|
---|
137 |
|
---|
138 | =over 4
|
---|
139 |
|
---|
140 | =item B<rsa_keygen_bits:numbits>, B<rsa_keygen_primes:numprimes>, B<rsa_keygen_pubexp:value>
|
---|
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 |
|
---|
159 | =head2 EC Key Generation Options
|
---|
160 |
|
---|
161 | The EC key generation options can also be used for parameter generation.
|
---|
162 |
|
---|
163 | =over 4
|
---|
164 |
|
---|
165 | =item B<ec_paramgen_curve:curve>
|
---|
166 |
|
---|
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".
|
---|
173 |
|
---|
174 | =back
|
---|
175 |
|
---|
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
|
---|
183 |
|
---|
184 | =over 4
|
---|
185 |
|
---|
186 | =item B<dsa_paramgen_bits:numbits>
|
---|
187 |
|
---|
188 | The number of bits in the generated prime. If not specified 2048 is used.
|
---|
189 |
|
---|
190 | =item B<dsa_paramgen_q_bits:numbits>
|
---|
191 |
|
---|
192 | The number of bits in the q parameter. Must be one of 160, 224 or 256. If not
|
---|
193 | specified 224 is used.
|
---|
194 |
|
---|
195 | =item B<dsa_paramgen_md:digest>
|
---|
196 |
|
---|
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.
|
---|
203 |
|
---|
204 | =back
|
---|
205 |
|
---|
206 | =head2 DH Parameter Generation Options
|
---|
207 |
|
---|
208 | =over 4
|
---|
209 |
|
---|
210 | =item B<dh_paramgen_prime_len:numbits>
|
---|
211 |
|
---|
212 | The number of bits in the prime parameter B<p>. The default is 2048.
|
---|
213 |
|
---|
214 | =item B<dh_paramgen_subprime_len:numbits>
|
---|
215 |
|
---|
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.
|
---|
219 |
|
---|
220 | =item B<dh_paramgen_generator:value>
|
---|
221 |
|
---|
222 | The value to use for the generator B<g>. The default is 2.
|
---|
223 |
|
---|
224 | =item B<dh_paramgen_type:value>
|
---|
225 |
|
---|
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.
|
---|
228 |
|
---|
229 | =item B<dh_rfc5114:num>
|
---|
230 |
|
---|
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.
|
---|
238 |
|
---|
239 | =back
|
---|
240 |
|
---|
241 | =head2 EC Parameter Generation Options
|
---|
242 |
|
---|
243 | The EC parameter generation options are the same as for key generation. See
|
---|
244 | L<EC Key Generation Options> above.
|
---|
245 |
|
---|
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 |
|
---|
256 | openssl genpkey -algorithm RSA -out key.pem
|
---|
257 |
|
---|
258 | Encrypt output private key using 128 bit AES and the passphrase "hello":
|
---|
259 |
|
---|
260 | openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
|
---|
261 |
|
---|
262 | Generate a 2048 bit RSA key using 3 as the public exponent:
|
---|
263 |
|
---|
264 | openssl genpkey -algorithm RSA -out key.pem \
|
---|
265 | -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3
|
---|
266 |
|
---|
267 | Generate 2048 bit DSA parameters:
|
---|
268 |
|
---|
269 | openssl genpkey -genparam -algorithm DSA -out dsap.pem \
|
---|
270 | -pkeyopt dsa_paramgen_bits:2048
|
---|
271 |
|
---|
272 | Generate DSA key from parameters:
|
---|
273 |
|
---|
274 | openssl genpkey -paramfile dsap.pem -out dsakey.pem
|
---|
275 |
|
---|
276 | Generate 2048 bit DH parameters:
|
---|
277 |
|
---|
278 | openssl genpkey -genparam -algorithm DH -out dhp.pem \
|
---|
279 | -pkeyopt dh_paramgen_prime_len:2048
|
---|
280 |
|
---|
281 | Generate 2048 bit X9.42 DH parameters:
|
---|
282 |
|
---|
283 | openssl genpkey -genparam -algorithm DH -out dhpx.pem \
|
---|
284 | -pkeyopt dh_paramgen_prime_len:2048 \
|
---|
285 | -pkeyopt dh_paramgen_type:1
|
---|
286 |
|
---|
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 |
|
---|
291 | Generate DH key from parameters:
|
---|
292 |
|
---|
293 | openssl genpkey -paramfile dhp.pem -out dhkey.pem
|
---|
294 |
|
---|
295 | Generate EC parameters:
|
---|
296 |
|
---|
297 | openssl genpkey -genparam -algorithm EC -out ecp.pem \
|
---|
298 | -pkeyopt ec_paramgen_curve:secp384r1 \
|
---|
299 | -pkeyopt ec_param_enc:named_curve
|
---|
300 |
|
---|
301 | Generate EC key from parameters:
|
---|
302 |
|
---|
303 | openssl genpkey -paramfile ecp.pem -out eckey.pem
|
---|
304 |
|
---|
305 | Generate EC key directly:
|
---|
306 |
|
---|
307 | openssl genpkey -algorithm EC -out eckey.pem \
|
---|
308 | -pkeyopt ec_paramgen_curve:P-384 \
|
---|
309 | -pkeyopt ec_param_enc:named_curve
|
---|
310 |
|
---|
311 | Generate an X25519 private key:
|
---|
312 |
|
---|
313 | openssl genpkey -algorithm X25519 -out xkey.pem
|
---|
314 |
|
---|
315 | Generate an ED448 private key:
|
---|
316 |
|
---|
317 | openssl genpkey -algorithm ED448 -out xkey.pem
|
---|
318 |
|
---|
319 | =head1 HISTORY
|
---|
320 |
|
---|
321 | The ability to use NIST curve names, and to generate an EC key directly,
|
---|
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.
|
---|
325 |
|
---|
326 | =head1 COPYRIGHT
|
---|
327 |
|
---|
328 | Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
|
---|
329 |
|
---|
330 | Licensed under the OpenSSL license (the "License"). You may not use
|
---|
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
|
---|