VirtualBox

source: vbox/trunk/src/libs/openssl-1.1.1l/doc/man1/genpkey.pod@ 91772

Last change on this file since 91772 was 91772, checked in by vboxsync, 3 years ago

openssl-1.1.1l: Applied and adjusted our OpenSSL changes to 1.1.1l. bugref:10126

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette