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