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