genpkey.pod revision 348343 
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<-out filename>]
12[B<-outform PEM|DER>]
13[B<-pass arg>]
14[B<-I<cipher>>]
15[B<-engine id>]
16[B<-paramfile file>]
17[B<-algorithm alg>]
18[B<-pkeyopt opt:value>]
19[B<-genparam>]
20[B<-text>]
21
22=head1 DESCRIPTION
23
24The B<genpkey> command generates a private key.
25
26=head1 OPTIONS
27
28=over 4
29
30=item B<-out filename>
31
32the output filename. If this argument is not specified then standard output is
33used.  
34
35=item B<-outform DER|PEM>
36
37This specifies the output format DER or PEM. The default format is PEM.
38
39=item B<-pass arg>
40
41The output file password source. For more information about the format of B<arg>
42see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
43
44=item B<-I<cipher>>
45
46This option encrypts the private key with the supplied cipher. Any algorithm
47name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
48
49=item B<-engine id>
50
51Specifying an engine (by its unique B<id> string) will cause B<genpkey>
52to attempt to obtain a functional reference to the specified engine,
53thus initialising it if needed. The engine will then be set as the default
54for all available algorithms. If used this option should precede all other
55options.
56
57=item B<-algorithm alg>
58
59Public key algorithm to use such as RSA, DSA or DH. If used this option must
60precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
61are mutually exclusive. Engines may add algorithms in addition to the standard
62built-in ones.
63
64Valid built-in algorithm names for private key generation are RSA and EC.
65
66Valid built-in algorithm names for parameter generation (see the B<-genparam>
67option) are DH, DSA and EC.
68
69Note that the algorithm name X9.42 DH may be used as a synonym for the DH
70algorithm. These are identical and do not indicate the type of parameters that
71will be generated. Use the B<dh_paramgen_type> option to indicate whether PKCS#3
72or X9.42 DH parameters are required. See L<DH Parameter Generation Options>
73below for more details.
74
75=item B<-pkeyopt opt:value>
76
77Set the public key algorithm option B<opt> to B<value>. The precise set of
78options supported depends on the public key algorithm used and its
79implementation. See L<KEY GENERATION OPTIONS> and
80L<PARAMETER GENERATION OPTIONS> below for more details.
81
82=item B<-genparam>
83
84Generate a set of parameters instead of a private key. If used this option must
85precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options.
86
87=item B<-paramfile filename>
88
89Some public key algorithms generate a private key based on a set of parameters.
90They can be supplied using this option. If this option is used the public key
91algorithm used is determined by the parameters. If used this option must
92precede and B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
93are mutually exclusive.
94
95=item B<-text>
96
97Print an (unencrypted) text representation of private and public keys and
98parameters along with the PEM or DER structure.
99
100=back
101
102=head1 KEY GENERATION OPTIONS
103
104The options supported by each algorith and indeed each implementation of an
105algorithm can vary. The options for the OpenSSL implementations are detailed
106below.
107
108=head2 RSA Key Generation Options
109
110=over 4
111
112=item B<rsa_keygen_bits:numbits>
113
114The number of bits in the generated key. If not specified 2048 is used.
115
116=item B<rsa_keygen_pubexp:value>
117
118The RSA public exponent value. This can be a large decimal or
119hexadecimal value if preceded by B<0x>. Default value is 65537.
120
121=back
122
123=head2 EC Key Generation Options
124
125The EC key generation options can also be used for parameter generation.
126
127=over 4
128
129=item B<ec_paramgen_curve:curve>
130
131The EC curve to use. OpenSSL supports NIST curve names such as "P-256".
132
133=item B<ec_param_enc:encoding>
134
135The encoding to use for parameters. The "encoding" parameter must be either
136"named_curve" or "explicit". The default value is "named_curve".
137
138=back
139
140=head1 PARAMETER GENERATION OPTIONS
141
142The options supported by each algorithm and indeed each implementation of an
143algorithm can vary. The options for the OpenSSL implementations are detailed
144below.
145
146=head2 DSA Parameter Generation Options
147
148=over 4
149
150=item B<dsa_paramgen_bits:numbits>
151
152The number of bits in the generated prime. If not specified 2048 is used.
153
154=item B<dsa_paramgen_q_bits:numbits>
155
156The number of bits in the q parameter. Must be one of 160, 224 or 256. If not
157specified 224 is used.
158
159=item B<dsa_paramgen_md:digest>
160
161The digest to use during parameter generation. Must be one of B<sha1>, B<sha224>
162or B<sha256>. If set, then the number of bits in B<q> will match the output size
163of the specified digest and the B<dsa_paramgen_q_bits> parameter will be
164ignored. If not set, then a digest will be used that gives an output matching
165the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224
166or B<sha256> if it is 256.
167
168=back
169
170=head2 DH Parameter Generation Options
171
172=over 4
173
174=item B<dh_paramgen_prime_len:numbits>
175
176The number of bits in the prime parameter B<p>. The default is 2048.
177
178=item B<dh_paramgen_subprime_len:numbits>
179
180The number of bits in the sub prime parameter B<q>. The default is 256 if the
181prime is at least 2048 bits long or 160 otherwise. Only relevant if used in
182conjunction with the B<dh_paramgen_type> option to generate X9.42 DH parameters.
183
184=item B<dh_paramgen_generator:value>
185
186The value to use for the generator B<g>. The default is 2.
187
188=item B<dh_paramgen_type:value>
189
190The type of DH parameters to generate. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
191The default is 0.
192
193=item B<dh_rfc5114:num>
194
195If this option is set, then the appropriate RFC5114 parameters are used
196instead of generating new parameters. The value B<num> can take the
197values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of
1981024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup
199and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
2002.1, 2.2 and 2.3 respectively. If present this overrides all other DH parameter
201options.
202
203=back
204
205=head2 EC Parameter Generation Options
206
207The EC parameter generation options are the same as for key generation. See
208L<EC Key Generation Options> above.
209
210=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS
211
212Gost 2001 support is not enabled by default. To enable this algorithm,
213one should load the ccgost engine in the OpenSSL configuration file.
214See README.gost file in the engines/ccgost directiry of the source
215distribution for more details.
216
217Use of a parameter file for the GOST R 34.10 algorithm is optional.
218Parameters can be specified during key generation directly as well as
219during generation of parameter file.
220
221=over 4
222
223=item B<paramset:name>
224
225Specifies GOST R 34.10-2001 parameter set according to RFC 4357.
226Parameter set can be specified using abbreviated name, object short name or
227numeric OID. Following parameter sets are supported:
228
229  paramset   OID               Usage
230  A          1.2.643.2.2.35.1  Signature
231  B          1.2.643.2.2.35.2  Signature
232  C          1.2.643.2.2.35.3  Signature
233  XA         1.2.643.2.2.36.0  Key exchange
234  XB         1.2.643.2.2.36.1  Key exchange
235  test       1.2.643.2.2.35.0  Test purposes
236
237=back
238
239=head1 NOTES
240
241The use of the genpkey program is encouraged over the algorithm specific
242utilities because additional algorithm options and ENGINE provided algorithms
243can be used.
244
245=head1 EXAMPLES
246
247Generate an RSA private key using default parameters:
248
249 openssl genpkey -algorithm RSA -out key.pem 
250
251Encrypt output private key using 128 bit AES and the passphrase "hello":
252
253 openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
254
255Generate a 2048 bit RSA key using 3 as the public exponent:
256
257 openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \
258 						-pkeyopt rsa_keygen_pubexp:3
259
260Generate 2048 bit DSA parameters:
261
262 openssl genpkey -genparam -algorithm DSA -out dsap.pem \
263                                                -pkeyopt dsa_paramgen_bits:2048
264
265Generate DSA key from parameters:
266
267 openssl genpkey -paramfile dsap.pem -out dsakey.pem 
268
269Generate 2048 bit DH parameters:
270
271 openssl genpkey -genparam -algorithm DH -out dhp.pem \
272                                        -pkeyopt dh_paramgen_prime_len:2048
273
274Generate 2048 bit X9.42 DH parameters:
275
276 openssl genpkey -genparam -algorithm DH -out dhpx.pem \
277                                        -pkeyopt dh_paramgen_prime_len:2048 \
278                                        -pkeyopt dh_paramgen_type:1
279
280Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
281
282 openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
283
284Generate DH key from parameters:
285
286 openssl genpkey -paramfile dhp.pem -out dhkey.pem 
287
288Generate EC key directly:
289
290 openssl genpkey -algorithm EC -out eckey.pem \
291        -pkeyopt ec_paramgen_curve:P-384 \
292        -pkeyopt ec_param_enc:named_curve
293
294=head1 HISTORY
295
296The ability to use NIST curve names, and to generate an EC key directly,
297were added in OpenSSL 1.0.2.
298
299=cut
300
301