1=pod 2 3=begin comment 4{- join("\n", @autowarntext) -} 5 6=end comment 7 8=head1 NAME 9 10openssl-genpkey - generate a private key 11 12=head1 SYNOPSIS 13 14B<openssl> B<genpkey> 15[B<-help>] 16[B<-out> I<filename>] 17[B<-outform> B<DER>|B<PEM>] 18[B<-verbose>] 19[B<-quiet>] 20[B<-pass> I<arg>] 21[B<-I<cipher>>] 22[B<-paramfile> I<file>] 23[B<-algorithm> I<alg>] 24[B<-pkeyopt> I<opt>:I<value>] 25[B<-genparam>] 26[B<-text>] 27{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} 28{- $OpenSSL::safe::opt_config_synopsis -} 29 30=head1 DESCRIPTION 31 32This command generates a private key. 33 34=head1 OPTIONS 35 36=over 4 37 38=item B<-help> 39 40Print out a usage message. 41 42=item B<-out> I<filename> 43 44Output the key to the specified file. If this argument is not specified then 45standard output is used. 46 47=item B<-outform> B<DER>|B<PEM> 48 49The output format, except when B<-genparam> is given; the default is B<PEM>. 50See L<openssl-format-options(1)> for details. 51 52When B<-genparam> is given, B<-outform> is ignored. 53 54=item B<-verbose> 55 56Output "status dots" while generating keys. 57 58=item B<-quiet> 59 60Do not output "status dots" while generating keys. 61 62=item B<-pass> I<arg> 63 64The output file password source. For more information about the format of I<arg> 65see L<openssl-passphrase-options(1)>. 66 67=item B<-I<cipher>> 68 69This option encrypts the private key with the supplied cipher. Any algorithm 70name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>. 71 72=item B<-algorithm> I<alg> 73 74Public key algorithm to use such as RSA, DSA, DH or DHX. If used this option must 75precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> 76are mutually exclusive. Engines may add algorithms in addition to the standard 77built-in ones. 78 79Valid built-in algorithm names for private key generation are RSA, RSA-PSS, EC, 80X25519, X448, ED25519 and ED448. 81 82Valid built-in algorithm names for parameter generation (see the B<-genparam> 83option) are DH, DSA and EC. 84 85Note that the algorithm name X9.42 DH may be used as a synonym for DHX keys and 86PKCS#3 refers to DH Keys. Some options are not shared between DH and DHX keys. 87 88=item B<-pkeyopt> I<opt>:I<value> 89 90Set the public key algorithm option I<opt> to I<value>. The precise set of 91options supported depends on the public key algorithm used and its 92implementation. See L</KEY GENERATION OPTIONS> and 93L</PARAMETER GENERATION OPTIONS> below for more details. 94 95=item B<-genparam> 96 97Generate a set of parameters instead of a private key. If used this option must 98precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options. 99 100=item B<-paramfile> I<filename> 101 102Some public key algorithms generate a private key based on a set of parameters. 103They can be supplied using this option. If this option is used the public key 104algorithm used is determined by the parameters. If used this option must 105precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> 106are mutually exclusive. 107 108=item B<-text> 109 110Print an (unencrypted) text representation of private and public keys and 111parameters along with the PEM or DER structure. 112 113{- $OpenSSL::safe::opt_engine_item -} 114 115{- $OpenSSL::safe::opt_provider_item -} 116 117{- $OpenSSL::safe::opt_config_item -} 118 119=back 120 121=head1 KEY GENERATION OPTIONS 122 123The options supported by each algorithm and indeed each implementation of an 124algorithm can vary. The options for the OpenSSL implementations are detailed 125below. There are no key generation options defined for the X25519, X448, ED25519 126or ED448 algorithms. 127 128=head2 RSA Key Generation Options 129 130=over 4 131 132=item B<rsa_keygen_bits:numbits> 133 134The number of bits in the generated key. If not specified 2048 is used. 135 136=item B<rsa_keygen_primes:numprimes> 137 138The number of primes in the generated key. If not specified 2 is used. 139 140=item B<rsa_keygen_pubexp:value> 141 142The RSA public exponent value. This can be a large decimal or 143hexadecimal value if preceded by C<0x>. Default value is 65537. 144 145=back 146 147=head2 RSA-PSS Key Generation Options 148 149Note: by default an B<RSA-PSS> key has no parameter restrictions. 150 151=over 4 152 153=item B<rsa_keygen_bits>:I<numbits>, B<rsa_keygen_primes>:I<numprimes>, 154B<rsa_keygen_pubexp>:I<value> 155 156These options have the same meaning as the B<RSA> algorithm. 157 158=item B<rsa_pss_keygen_md>:I<digest> 159 160If set the key is restricted and can only use I<digest> for signing. 161 162=item B<rsa_pss_keygen_mgf1_md>:I<digest> 163 164If set the key is restricted and can only use I<digest> as it's MGF1 165parameter. 166 167=item B<rsa_pss_keygen_saltlen>:I<len> 168 169If set the key is restricted and I<len> specifies the minimum salt length. 170 171=back 172 173=head2 EC Key Generation Options 174 175The EC key generation options can also be used for parameter generation. 176 177=over 4 178 179=item B<ec_paramgen_curve>:I<curve> 180 181The EC curve to use. OpenSSL supports NIST curve names such as "P-256". 182 183=item B<ec_param_enc>:I<encoding> 184 185The encoding to use for parameters. The I<encoding> parameter must be either 186B<named_curve> or B<explicit>. The default value is B<named_curve>. 187 188=back 189 190=head2 DH Key Generation Options 191 192=over 4 193 194=item B<group>:I<name> 195 196The B<paramfile> option is not required if a named group is used here. 197See the L</DH Parameter Generation Options> section below. 198 199=back 200 201 202=head1 PARAMETER GENERATION OPTIONS 203 204The options supported by each algorithm and indeed each implementation of an 205algorithm can vary. The options for the OpenSSL implementations are detailed 206below. 207 208=head2 DSA Parameter Generation Options 209 210=over 4 211 212=item B<dsa_paramgen_bits>:I<numbits> 213 214The number of bits in the generated prime. If not specified 2048 is used. 215 216=item B<dsa_paramgen_q_bits>:I<numbits> 217 218=item B<qbits>:I<numbits> 219 220The number of bits in the q parameter. Must be one of 160, 224 or 256. If not 221specified 224 is used. 222 223=item B<dsa_paramgen_md>:I<digest> 224 225=item B<digest>:I<digest> 226 227The digest to use during parameter generation. Must be one of B<sha1>, B<sha224> 228or B<sha256>. If set, then the number of bits in B<q> will match the output size 229of the specified digest and the B<dsa_paramgen_q_bits> parameter will be 230ignored. If not set, then a digest will be used that gives an output matching 231the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224 232or B<sha256> if it is 256. 233 234=item B<properties>:I<query> 235 236The I<digest> property I<query> string to use when fetching a digest from a provider. 237 238=item B<type>:I<type> 239 240The type of generation to use. Set this to 1 to use legacy FIPS186-2 parameter 241generation. The default of 0 uses FIPS186-4 parameter generation. 242 243=item B<gindex>:I<index> 244 245The index to use for canonical generation and verification of the generator g. 246Set this to a positive value ranging from 0..255 to use this mode. Larger values 247will only use the bottom byte. 248This I<index> must then be reused during key validation to verify the value of g. 249If this value is not set then g is not verifiable. The default value is -1. 250 251=item B<hexseed>:I<seed> 252 253The seed I<seed> data to use instead of generating a random seed internally. 254This should be used for testing purposes only. This will either produced fixed 255values for the generated parameters OR it will fail if the seed did not 256generate valid primes. 257 258=back 259 260=head2 DH Parameter Generation Options 261 262For most use cases it is recommended to use the B<group> option rather than 263the B<type> options. Note that the B<group> option is not used by default if 264no parameter generation options are specified. 265 266=over 4 267 268=item B<group>:I<name> 269 270=item B<dh_param>:I<name> 271 272Use a named DH group to select constant values for the DH parameters. 273All other options will be ignored if this value is set. 274 275Valid values that are associated with the B<algorithm> of B<"DH"> are: 276"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", 277"modp_1536", "modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192". 278 279Valid values that are associated with the B<algorithm> of B<"DHX"> are the 280RFC5114 names "dh_1024_160", "dh_2048_224", "dh_2048_256". 281 282=item B<dh_rfc5114>:I<num> 283 284If this option is set, then the appropriate RFC5114 parameters are used 285instead of generating new parameters. The value I<num> can be one of 2861, 2 or 3 that are equivalent to using the option B<group> with one of 287"dh_1024_160", "dh_2048_224" or "dh_2048_256". 288All other options will be ignored if this value is set. 289 290=item B<pbits>:I<numbits> 291 292=item B<dh_paramgen_prime_len>:I<numbits> 293 294The number of bits in the prime parameter I<p>. The default is 2048. 295 296=item B<qbits>:I<numbits> 297 298=item B<dh_paramgen_subprime_len>:I<numbits> 299 300The number of bits in the sub prime parameter I<q>. The default is 224. 301Only relevant if used in conjunction with the B<dh_paramgen_type> option to 302generate DHX parameters. 303 304=item B<safeprime-generator>:I<value> 305 306=item B<dh_paramgen_generator>:I<value> 307 308The value to use for the generator I<g>. The default is 2. 309The B<algorithm> option must be B<"DH"> for this parameter to be used. 310 311=item B<type>:I<string> 312 313The type name of DH parameters to generate. Valid values are: 314 315=over 4 316 317=item "generator" 318 319Use a safe prime generator with the option B<safeprime_generator> 320The B<algorithm> option must be B<"DH">. 321 322=item "fips186_4" 323 324FIPS186-4 parameter generation. 325The B<algorithm> option must be B<"DHX">. 326 327=item "fips186_2" 328 329FIPS186-4 parameter generation. 330The B<algorithm> option must be B<"DHX">. 331 332=item "group" 333 334Can be used with the option B<pbits> to select one of 335"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144" or "ffdhe8192". 336The B<algorithm> option must be B<"DH">. 337 338=item "default" 339 340Selects a default type based on the B<algorithm>. This is used by the 341OpenSSL default provider to set the type for backwards compatibility. 342If B<algorithm> is B<"DH"> then B<"generator"> is used. 343If B<algorithm> is B<"DHX"> then B<"fips186_2"> is used. 344 345=back 346 347=item B<dh_paramgen_type>:I<value> 348 349The type of DH parameters to generate. Valid values are 0, 1, 2 or 3 350which correspond to setting the option B<type> to 351"generator", "fips186_2", "fips186_4" or "group". 352 353=item B<digest>:I<digest> 354 355The digest to use during parameter generation. Must be one of B<sha1>, B<sha224> 356or B<sha256>. If set, then the number of bits in B<qbits> will match the output 357size of the specified digest and the B<qbits> parameter will be 358ignored. If not set, then a digest will be used that gives an output matching 359the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it is 360224 or B<sha256> if it is 256. 361This is only used by "fips186_4" and "fips186_2" key generation. 362 363=item B<properties>:I<query> 364 365The I<digest> property I<query> string to use when fetching a digest from a provider. 366This is only used by "fips186_4" and "fips186_2" key generation. 367 368=item B<gindex>:I<index> 369 370The index to use for canonical generation and verification of the generator g. 371Set this to a positive value ranging from 0..255 to use this mode. Larger values 372will only use the bottom byte. 373This I<index> must then be reused during key validation to verify the value of g. 374If this value is not set then g is not verifiable. The default value is -1. 375This is only used by "fips186_4" and "fips186_2" key generation. 376 377=item B<hexseed>:I<seed> 378 379The seed I<seed> data to use instead of generating a random seed internally. 380This should be used for testing purposes only. This will either produced fixed 381values for the generated parameters OR it will fail if the seed did not 382generate valid primes. 383This is only used by "fips186_4" and "fips186_2" key generation. 384 385=back 386 387=head2 EC Parameter Generation Options 388 389The EC parameter generation options are the same as for key generation. See 390L</EC Key Generation Options> above. 391 392=head1 NOTES 393 394The use of the genpkey program is encouraged over the algorithm specific 395utilities because additional algorithm options and ENGINE provided algorithms 396can be used. 397 398=head1 EXAMPLES 399 400Generate an RSA private key using default parameters: 401 402 openssl genpkey -algorithm RSA -out key.pem 403 404Encrypt output private key using 128 bit AES and the passphrase "hello": 405 406 openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello 407 408Generate a 2048 bit RSA key using 3 as the public exponent: 409 410 openssl genpkey -algorithm RSA -out key.pem \ 411 -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3 412 413Generate 2048 bit DSA parameters that can be validated: The output values for 414gindex and seed are required for key validation purposes and are not saved to 415the output pem file). 416 417 openssl genpkey -genparam -algorithm DSA -out dsap.pem -pkeyopt pbits:2048 \ 418 -pkeyopt qbits:224 -pkeyopt digest:SHA256 -pkeyopt gindex:1 -text 419 420Generate DSA key from parameters: 421 422 openssl genpkey -paramfile dsap.pem -out dsakey.pem 423 424Generate 4096 bit DH Key using safe prime group ffdhe4096: 425 426 openssl genpkey -algorithm DH -out dhkey.pem -pkeyopt group:ffdhe4096 427 428Generate 2048 bit X9.42 DH key with 256 bit subgroup using RFC5114 group3: 429 430 openssl genpkey -algorithm DHX -out dhkey.pem -pkeyopt dh_rfc5114:3 431 432Generate a DH key using a DH parameters file: 433 434 openssl genpkey -paramfile dhp.pem -out dhkey.pem 435 436Output DH parameters for safe prime group ffdhe2048: 437 438 openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt group:ffdhe2048 439 440Output 2048 bit X9.42 DH parameters with 224 bit subgroup using RFC5114 group2: 441 442 openssl genpkey -genparam -algorithm DHX -out dhp.pem -pkeyopt dh_rfc5114:2 443 444Output 2048 bit X9.42 DH parameters with 224 bit subgroup using FIP186-4 keygen: 445 446 openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \ 447 -pkeyopt pbits:2048 -pkeyopt qbits:224 -pkeyopt digest:SHA256 \ 448 -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:2 449 450Output 1024 bit X9.42 DH parameters with 160 bit subgroup using FIP186-2 keygen: 451 452 openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \ 453 -pkeyopt pbits:1024 -pkeyopt qbits:160 -pkeyopt digest:SHA1 \ 454 -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:1 455 456Output 2048 bit DH parameters: 457 458 openssl genpkey -genparam -algorithm DH -out dhp.pem \ 459 -pkeyopt dh_paramgen_prime_len:2048 460 461Output 2048 bit DH parameters using a generator: 462 463 openssl genpkey -genparam -algorithm DH -out dhpx.pem \ 464 -pkeyopt dh_paramgen_prime_len:2048 \ 465 -pkeyopt dh_paramgen_type:1 466 467Generate EC parameters: 468 469 openssl genpkey -genparam -algorithm EC -out ecp.pem \ 470 -pkeyopt ec_paramgen_curve:secp384r1 \ 471 -pkeyopt ec_param_enc:named_curve 472 473Generate EC key from parameters: 474 475 openssl genpkey -paramfile ecp.pem -out eckey.pem 476 477Generate EC key directly: 478 479 openssl genpkey -algorithm EC -out eckey.pem \ 480 -pkeyopt ec_paramgen_curve:P-384 \ 481 -pkeyopt ec_param_enc:named_curve 482 483Generate an X25519 private key: 484 485 openssl genpkey -algorithm X25519 -out xkey.pem 486 487Generate an ED448 private key: 488 489 openssl genpkey -algorithm ED448 -out xkey.pem 490 491=head1 HISTORY 492 493The ability to use NIST curve names, and to generate an EC key directly, 494were added in OpenSSL 1.0.2. 495The ability to generate X25519 keys was added in OpenSSL 1.1.0. 496The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1. 497 498The B<-engine> option was deprecated in OpenSSL 3.0. 499 500=head1 COPYRIGHT 501 502Copyright 2006-2022 The OpenSSL Project Authors. All Rights Reserved. 503 504Licensed under the Apache License 2.0 (the "License"). You may not use 505this file except in compliance with the License. You can obtain a copy 506in the file LICENSE in the source distribution or at 507L<https://www.openssl.org/source/license.html>. 508 509=cut 510
