1OPENSSL-GENPKEY(1ossl)              OpenSSL             OPENSSL-GENPKEY(1ossl)
2
3
4

NAME

6       openssl-genpkey - generate a private key
7

SYNOPSIS

9       openssl genpkey [-help] [-out filename] [-outform DER|PEM] [-quiet]
10       [-pass arg] [-cipher] [-paramfile file] [-algorithm alg] [-pkeyopt
11       opt:value] [-genparam] [-text] [-engine id] [-provider name]
12       [-provider-path path] [-propquery propq] [-config configfile]
13

DESCRIPTION

15       This command generates a private key.
16

OPTIONS

18       -help
19           Print out a usage message.
20
21       -out filename
22           Output the key to the specified file. If this argument is not
23           specified then standard output is used.
24
25       -outform DER|PEM
26           The output format, except when -genparam is given; the default is
27           PEM.  See openssl-format-options(1) for details.
28
29           When -genparam is given, -outform is ignored.
30
31       -quiet
32           Do not output "status dots" while generating keys.
33
34       -pass arg
35           The output file password source. For more information about the
36           format of arg see openssl-passphrase-options(1).
37
38       -cipher
39           This option encrypts the private key with the supplied cipher. Any
40           algorithm name accepted by EVP_get_cipherbyname() is acceptable
41           such as des3.
42
43       -algorithm alg
44           Public key algorithm to use such as RSA, DSA, DH or DHX. If used
45           this option must precede any -pkeyopt options. The options
46           -paramfile and -algorithm are mutually exclusive. Engines may add
47           algorithms in addition to the standard built-in ones.
48
49           Valid built-in algorithm names for private key generation are RSA,
50           RSA-PSS, EC, X25519, X448, ED25519 and ED448.
51
52           Valid built-in algorithm names for parameter generation (see the
53           -genparam option) are DH, DSA and EC.
54
55           Note that the algorithm name X9.42 DH may be used as a synonym for
56           DHX keys and PKCS#3 refers to DH Keys. Some options are not shared
57           between DH and DHX keys.
58
59       -pkeyopt opt:value
60           Set the public key algorithm option opt to value. The precise set
61           of options supported depends on the public key algorithm used and
62           its implementation. See "KEY GENERATION OPTIONS" and "PARAMETER
63           GENERATION OPTIONS" below for more details.
64
65       -genparam
66           Generate a set of parameters instead of a private key. If used this
67           option must precede any -algorithm, -paramfile or -pkeyopt options.
68
69       -paramfile filename
70           Some public key algorithms generate a private key based on a set of
71           parameters.  They can be supplied using this option. If this option
72           is used the public key algorithm used is determined by the
73           parameters. If used this option must precede any -pkeyopt options.
74           The options -paramfile and -algorithm are mutually exclusive.
75
76       -text
77           Print an (unencrypted) text representation of private and public
78           keys and parameters along with the PEM or DER structure.
79
80       -engine id
81           See "Engine Options" in openssl(1).  This option is deprecated.
82
83       -provider name
84       -provider-path path
85       -propquery propq
86           See "Provider Options" in openssl(1), provider(7), and property(7).
87
88       -config configfile
89           See "Configuration Option" in openssl(1).
90

KEY GENERATION OPTIONS

92       The options supported by each algorithm and indeed each implementation
93       of an algorithm can vary. The options for the OpenSSL implementations
94       are detailed below. There are no key generation options defined for the
95       X25519, X448, ED25519 or ED448 algorithms.
96
97   RSA Key Generation Options
98       rsa_keygen_bits:numbits
99           The number of bits in the generated key. If not specified 2048 is
100           used.
101
102       rsa_keygen_primes:numprimes
103           The number of primes in the generated key. If not specified 2 is
104           used.
105
106       rsa_keygen_pubexp:value
107           The RSA public exponent value. This can be a large decimal or
108           hexadecimal value if preceded by "0x". Default value is 65537.
109
110   RSA-PSS Key Generation Options
111       Note: by default an RSA-PSS key has no parameter restrictions.
112
113       rsa_keygen_bits:numbits, rsa_keygen_primes:numprimes,
114       rsa_keygen_pubexp:value
115           These options have the same meaning as the RSA algorithm.
116
117       rsa_pss_keygen_md:digest
118           If set the key is restricted and can only use digest for signing.
119
120       rsa_pss_keygen_mgf1_md:digest
121           If set the key is restricted and can only use digest as it's MGF1
122           parameter.
123
124       rsa_pss_keygen_saltlen:len
125           If set the key is restricted and len specifies the minimum salt
126           length.
127
128   EC Key Generation Options
129       The EC key generation options can also be used for parameter
130       generation.
131
132       ec_paramgen_curve:curve
133           The EC curve to use. OpenSSL supports NIST curve names such as
134           "P-256".
135
136       ec_param_enc:encoding
137           The encoding to use for parameters. The encoding parameter must be
138           either named_curve or explicit. The default value is named_curve.
139
140   DH Key Generation Options
141       group:name
142           The paramfile option is not required if a named group is used here.
143           See the "DH Parameter Generation Options" section below.
144

PARAMETER GENERATION OPTIONS

146       The options supported by each algorithm and indeed each implementation
147       of an algorithm can vary. The options for the OpenSSL implementations
148       are detailed below.
149
150   DSA Parameter Generation Options
151       dsa_paramgen_bits:numbits
152           The number of bits in the generated prime. If not specified 2048 is
153           used.
154
155       dsa_paramgen_q_bits:numbits
156       qbits:numbits
157           The number of bits in the q parameter. Must be one of 160, 224 or
158           256. If not specified 224 is used.
159
160       dsa_paramgen_md:digest
161       digest:digest
162           The digest to use during parameter generation. Must be one of sha1,
163           sha224 or sha256. If set, then the number of bits in q will match
164           the output size of the specified digest and the dsa_paramgen_q_bits
165           parameter will be ignored. If not set, then a digest will be used
166           that gives an output matching the number of bits in q, i.e. sha1 if
167           q length is 160, sha224 if it 224 or sha256 if it is 256.
168
169       properties:query
170           The digest property query string to use when fetching a digest from
171           a provider.
172
173       type:type
174           The type of generation to use. Set this to 1 to use legacy
175           FIPS186-2 parameter generation. The default of 0 uses FIPS186-4
176           parameter generation.
177
178       gindex:index
179           The index to use for canonical generation and verification of the
180           generator g.  Set this to a positive value ranging from 0..255 to
181           use this mode. Larger values will only use the bottom byte.  This
182           index must then be reused during key validation to verify the value
183           of g.  If this value is not set then g is not verifiable. The
184           default value is -1.
185
186       hexseed:seed
187           The seed seed data to use instead of generating a random seed
188           internally.  This should be used for testing purposes only. This
189           will either produced fixed values for the generated parameters OR
190           it will fail if the seed did not generate valid primes.
191
192   DH Parameter Generation Options
193       For most use cases it is recommended to use the group option rather
194       than the type options. Note that the group option is not used by
195       default if no parameter generation options are specified.
196
197       group:name
198       dh_param:name
199           Use a named DH group to select constant values for the DH
200           parameters.  All other options will be ignored if this value is
201           set.
202
203           Valid values that are associated with the algorithm of "DH" are:
204           "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
205           "modp_1536", "modp_2048", "modp_3072", "modp_4096", "modp_6144",
206           "modp_8192".
207
208           Valid values that are associated with the algorithm of "DHX" are
209           the RFC5114 names "dh_1024_160", "dh_2048_224", "dh_2048_256".
210
211       dh_rfc5114:num
212           If this option is set, then the appropriate RFC5114 parameters are
213           used instead of generating new parameters. The value num can be one
214           of 1, 2 or 3 that are equivalant to using the option group with one
215           of "dh_1024_160", "dh_2048_224" or "dh_2048_256".  All other
216           options will be ignored if this value is set.
217
218       pbits:numbits
219       dh_paramgen_prime_len:numbits
220           The number of bits in the prime parameter p. The default is 2048.
221
222       qbits:numbits
223       dh_paramgen_subprime_len:numbits
224           The number of bits in the sub prime parameter q. The default is
225           224.  Only relevant if used in conjunction with the
226           dh_paramgen_type option to generate DHX parameters.
227
228       safeprime-generator:value
229       dh_paramgen_generator:value
230           The value to use for the generator g. The default is 2.  The
231           algorithm option must be "DH" for this parameter to be used.
232
233       type:string
234           The type name of DH parameters to generate. Valid values are:
235
236           "generator"
237               Use a safe prime generator with the option safeprime_generator
238               The algorithm option must be "DH".
239
240           "fips186_4"
241               FIPS186-4 parameter generation.  The algorithm option must be
242               "DHX".
243
244           "fips186_2"
245               FIPS186-4 parameter generation.  The algorithm option must be
246               "DHX".
247
248           "group"
249               Can be used with the option pbits to select one of "ffdhe2048",
250               "ffdhe3072", "ffdhe4096", "ffdhe6144" or "ffdhe8192".  The
251               algorithm option must be "DH".
252
253           "default"
254               Selects a default type based on the algorithm. This is used by
255               the OpenSSL default provider to set the type for backwards
256               compatability.  If algorithm is "DH" then "generator" is used.
257               If algorithm is "DHX" then "fips186_2" is used.
258
259       dh_paramgen_type:value
260           The type of DH parameters to generate. Valid values are 0, 1, 2 or
261           3 which correspond to setting the option type to "generator",
262           "fips186_2", "fips186_4" or "group".
263
264       digest:digest
265           The digest to use during parameter generation. Must be one of sha1,
266           sha224 or sha256. If set, then the number of bits in qbits will
267           match the output size of the specified digest and the qbits
268           parameter will be ignored. If not set, then a digest will be used
269           that gives an output matching the number of bits in q, i.e. sha1 if
270           q length is 160, sha224 if it is 224 or sha256 if it is 256.  This
271           is only used by "fips186_4" and "fips186_2" key generation.
272
273       properties:query
274           The digest property query string to use when fetching a digest from
275           a provider.  This is only used by "fips186_4" and "fips186_2" key
276           generation.
277
278       gindex:index
279           The index to use for canonical generation and verification of the
280           generator g.  Set this to a positive value ranging from 0..255 to
281           use this mode. Larger values will only use the bottom byte.  This
282           index must then be reused during key validation to verify the value
283           of g.  If this value is not set then g is not verifiable. The
284           default value is -1.  This is only used by "fips186_4" and
285           "fips186_2" key generation.
286
287       hexseed:seed
288           The seed seed data to use instead of generating a random seed
289           internally.  This should be used for testing purposes only. This
290           will either produced fixed values for the generated parameters OR
291           it will fail if the seed did not generate valid primes.  This is
292           only used by "fips186_4" and "fips186_2" key generation.
293
294   EC Parameter Generation Options
295       The EC parameter generation options are the same as for key generation.
296       See "EC Key Generation Options" above.
297

NOTES

299       The use of the genpkey program is encouraged over the algorithm
300       specific utilities because additional algorithm options and ENGINE
301       provided algorithms can be used.
302

EXAMPLES

304       Generate an RSA private key using default parameters:
305
306        openssl genpkey -algorithm RSA -out key.pem
307
308       Encrypt output private key using 128 bit AES and the passphrase
309       "hello":
310
311        openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
312
313       Generate a 2048 bit RSA key using 3 as the public exponent:
314
315        openssl genpkey -algorithm RSA -out key.pem \
316            -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3
317
318       Generate 2048 bit DSA parameters that can be validated: The output
319       values for gindex and seed are required for key validation purposes and
320       are not saved to the output pem file).
321
322        openssl genpkey -genparam -algorithm DSA -out dsap.pem -pkeyopt pbits:2048 \
323            -pkeyopt qbits:224 -pkeyopt digest:SHA256 -pkeyopt gindex:1 -text
324
325       Generate DSA key from parameters:
326
327        openssl genpkey -paramfile dsap.pem -out dsakey.pem
328
329       Generate 4096 bit DH Key using safe prime group ffdhe4096:
330
331        openssl genpkey -algorithm DH -out dhkey.pem -pkeyopt group:ffdhe4096
332
333       Generate 2048 bit X9.42 DH key with 256 bit subgroup using RFC5114
334       group3:
335
336        openssl genpkey -algorithm DHX -out dhkey.pem -pkeyopt dh_rfc5114:3
337
338       Generate a DH key using a DH parameters file:
339
340        openssl genpkey -paramfile dhp.pem -out dhkey.pem
341
342       Output DH parameters for safe prime group ffdhe2048:
343
344        openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt group:ffdhe2048
345
346       Output 2048 bit X9.42 DH parameters with 224 bit subgroup using RFC5114
347       group2:
348
349        openssl genpkey -genparam -algorithm DHX -out dhp.pem -pkeyopt dh_rfc5114:2
350
351       Output 2048 bit X9.42 DH parameters with 224 bit subgroup using
352       FIP186-4 keygen:
353
354        openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \
355            -pkeyopt pbits:2048 -pkeyopt qbits:224 -pkeyopt digest:SHA256 \
356            -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:2
357
358       Output 1024 bit X9.42 DH parameters with 160 bit subgroup using
359       FIP186-2 keygen:
360
361        openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \
362            -pkeyopt pbits:1024 -pkeyopt qbits:160 -pkeyopt digest:SHA1 \
363            -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:1
364
365       Output 2048 bit DH parameters:
366
367        openssl genpkey -genparam -algorithm DH -out dhp.pem \
368            -pkeyopt dh_paramgen_prime_len:2048
369
370       Output 2048 bit DH parameters using a generator:
371
372        openssl genpkey -genparam -algorithm DH -out dhpx.pem \
373            -pkeyopt dh_paramgen_prime_len:2048 \
374            -pkeyopt dh_paramgen_type:1
375
376       Generate EC parameters:
377
378        openssl genpkey -genparam -algorithm EC -out ecp.pem \
379               -pkeyopt ec_paramgen_curve:secp384r1 \
380               -pkeyopt ec_param_enc:named_curve
381
382       Generate EC key from parameters:
383
384        openssl genpkey -paramfile ecp.pem -out eckey.pem
385
386       Generate EC key directly:
387
388        openssl genpkey -algorithm EC -out eckey.pem \
389               -pkeyopt ec_paramgen_curve:P-384 \
390               -pkeyopt ec_param_enc:named_curve
391
392       Generate an X25519 private key:
393
394        openssl genpkey -algorithm X25519 -out xkey.pem
395
396       Generate an ED448 private key:
397
398        openssl genpkey -algorithm ED448 -out xkey.pem
399

HISTORY

401       The ability to use NIST curve names, and to generate an EC key
402       directly, were added in OpenSSL 1.0.2.  The ability to generate X25519
403       keys was added in OpenSSL 1.1.0.  The ability to generate X448, ED25519
404       and ED448 keys was added in OpenSSL 1.1.1.
405
406       The -engine option was deprecated in OpenSSL 3.0.
407
409       Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
410
411       Licensed under the Apache License 2.0 (the "License").  You may not use
412       this file except in compliance with the License.  You can obtain a copy
413       in the file LICENSE in the source distribution or at
414       <https://www.openssl.org/source/license.html>.
415
416
417
4183.0.9                             2023-07-27            OPENSSL-GENPKEY(1ossl)
Impressum