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, ED448, ML-DSA and ML-KEM. 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 ML-DSA Key Generation Options 204 205=over 4 206 207=item B<hexseed>:I<seed> 208 209This specifies the optional ML-DSA I<seed> in hexadecimal form. The seed is 32 210bytes, giving 64 hexadecimal digits. 211When generated from an explicit seed the key is completely determined by the 212seed value. 213If other users can see the command-line arguments of the running process, this 214option may compromise the secret key, it is best avoided, tests-aside. 215 216See L<EVP_PKEY-ML-DSA(7)> for more detail. 217 218=back 219 220=head2 ML-KEM Key Generation Options 221 222=over 4 223 224=item B<hexseed>:I<seed> 225 226This specifies the optional ML-KEM I<seed> in hexadecimal form. The seed is 64 227bytes, giving 128 hexadecimal digits. 228When generated from an explicit seed the key is completely determined by the 229seed value. 230If other users can see the command-line arguments of the running process, this 231option may compromise the secret key, it is best avoided, tests-aside. 232 233See L<EVP_PKEY-ML-KEM(7)> for more detail. 234 235=back 236 237=head2 DH Key Generation Options 238 239=over 4 240 241=item B<group>:I<name> 242 243The B<paramfile> option is not required if a named group is used here. 244See the L</DH Parameter Generation Options> section below. 245 246=back 247 248 249=head1 PARAMETER GENERATION OPTIONS 250 251The options supported by each algorithm and indeed each implementation of an 252algorithm can vary. The options for the OpenSSL implementations are detailed 253below. 254 255=head2 DSA Parameter Generation Options 256 257=over 4 258 259=item B<dsa_paramgen_bits>:I<numbits> 260 261The number of bits in the generated prime. If not specified 2048 is used. 262 263=item B<dsa_paramgen_q_bits>:I<numbits> 264 265=item B<qbits>:I<numbits> 266 267The number of bits in the q parameter. Must be one of 160, 224 or 256. If not 268specified 224 is used. 269 270=item B<dsa_paramgen_md>:I<digest> 271 272=item B<digest>:I<digest> 273 274The digest to use during parameter generation. Must be one of B<sha1>, B<sha224> 275or B<sha256>. If set, then the number of bits in B<q> will match the output size 276of the specified digest and the B<dsa_paramgen_q_bits> parameter will be 277ignored. If not set, then a digest will be used that gives an output matching 278the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224 279or B<sha256> if it is 256. 280 281=item B<properties>:I<query> 282 283The I<digest> property I<query> string to use when fetching a digest from a provider. 284 285=item B<type>:I<type> 286 287The type of generation to use. Set this to 1 to use legacy FIPS186-2 parameter 288generation. The default of 0 uses FIPS186-4 parameter generation. 289 290=item B<gindex>:I<index> 291 292The index to use for canonical generation and verification of the generator g. 293Set this to a positive value ranging from 0..255 to use this mode. Larger values 294will only use the bottom byte. 295This I<index> must then be reused during key validation to verify the value of g. 296If this value is not set then g is not verifiable. The default value is -1. 297 298=item B<hexseed>:I<seed> 299 300The seed I<seed> data to use instead of generating a random seed internally. 301This should be used for testing purposes only. This will either produced fixed 302values for the generated parameters OR it will fail if the seed did not 303generate valid primes. 304 305=back 306 307=head2 DH Parameter Generation Options 308 309For most use cases it is recommended to use the B<group> option rather than 310the B<type> options. Note that the B<group> option is not used by default if 311no parameter generation options are specified. 312 313=over 4 314 315=item B<group>:I<name> 316 317=item B<dh_param>:I<name> 318 319Use a named DH group to select constant values for the DH parameters. 320All other options will be ignored if this value is set. 321 322Valid values that are associated with the B<algorithm> of B<"DH"> are: 323"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", 324"modp_1536", "modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192". 325 326Valid values that are associated with the B<algorithm> of B<"DHX"> are the 327RFC5114 names "dh_1024_160", "dh_2048_224", "dh_2048_256". 328 329=item B<dh_rfc5114>:I<num> 330 331If this option is set, then the appropriate RFC5114 parameters are used 332instead of generating new parameters. The value I<num> can be one of 3331, 2 or 3 that are equivalent to using the option B<group> with one of 334"dh_1024_160", "dh_2048_224" or "dh_2048_256". 335All other options will be ignored if this value is set. 336 337=item B<pbits>:I<numbits> 338 339=item B<dh_paramgen_prime_len>:I<numbits> 340 341The number of bits in the prime parameter I<p>. The default is 2048. 342 343=item B<qbits>:I<numbits> 344 345=item B<dh_paramgen_subprime_len>:I<numbits> 346 347The number of bits in the sub prime parameter I<q>. The default is 224. 348Only relevant if used in conjunction with the B<dh_paramgen_type> option to 349generate DHX parameters. 350 351=item B<safeprime-generator>:I<value> 352 353=item B<dh_paramgen_generator>:I<value> 354 355The value to use for the generator I<g>. The default is 2. 356The B<algorithm> option must be B<"DH"> for this parameter to be used. 357 358=item B<type>:I<string> 359 360The type name of DH parameters to generate. Valid values are: 361 362=over 4 363 364=item "generator" 365 366Use a safe prime generator with the option B<safeprime_generator> 367The B<algorithm> option must be B<"DH">. 368 369=item "fips186_4" 370 371FIPS186-4 parameter generation. 372The B<algorithm> option must be B<"DHX">. 373 374=item "fips186_2" 375 376FIPS186-4 parameter generation. 377The B<algorithm> option must be B<"DHX">. 378 379=item "group" 380 381Can be used with the option B<pbits> to select one of 382"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144" or "ffdhe8192". 383The B<algorithm> option must be B<"DH">. 384 385=item "default" 386 387Selects a default type based on the B<algorithm>. This is used by the 388OpenSSL default provider to set the type for backwards compatibility. 389If B<algorithm> is B<"DH"> then B<"generator"> is used. 390If B<algorithm> is B<"DHX"> then B<"fips186_2"> is used. 391 392=back 393 394=item B<dh_paramgen_type>:I<value> 395 396The type of DH parameters to generate. Valid values are 0, 1, 2 or 3 397which correspond to setting the option B<type> to 398"generator", "fips186_2", "fips186_4" or "group". 399 400=item B<digest>:I<digest> 401 402The digest to use during parameter generation. Must be one of B<sha1>, B<sha224> 403or B<sha256>. If set, then the number of bits in B<qbits> will match the output 404size of the specified digest and the B<qbits> parameter will be 405ignored. If not set, then a digest will be used that gives an output matching 406the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it is 407224 or B<sha256> if it is 256. 408This is only used by "fips186_4" and "fips186_2" key generation. 409 410=item B<properties>:I<query> 411 412The I<digest> property I<query> string to use when fetching a digest from a provider. 413This is only used by "fips186_4" and "fips186_2" key generation. 414 415=item B<gindex>:I<index> 416 417The index to use for canonical generation and verification of the generator g. 418Set this to a positive value ranging from 0..255 to use this mode. Larger values 419will only use the bottom byte. 420This I<index> must then be reused during key validation to verify the value of g. 421If this value is not set then g is not verifiable. The default value is -1. 422This is only used by "fips186_4" and "fips186_2" key generation. 423 424=item B<hexseed>:I<seed> 425 426The seed I<seed> data to use instead of generating a random seed internally. 427This should be used for testing purposes only. This will either produced fixed 428values for the generated parameters OR it will fail if the seed did not 429generate valid primes. 430This is only used by "fips186_4" and "fips186_2" key generation. 431 432=back 433 434=head2 EC Parameter Generation Options 435 436The EC parameter generation options are the same as for key generation. See 437L</EC Key Generation Options> above. 438 439=head1 NOTES 440 441The use of the genpkey program is encouraged over the algorithm specific 442utilities because additional algorithm options and ENGINE provided algorithms 443can be used. 444 445=head1 EXAMPLES 446 447Generate an RSA private key using default parameters: 448 449 openssl genpkey -algorithm RSA -out key.pem 450 451Encrypt output private key using 128 bit AES and the passphrase "hello": 452 453 openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello 454 455Generate a 2048 bit RSA key using 3 as the public exponent: 456 457 openssl genpkey -algorithm RSA -out key.pem \ 458 -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3 459 460Generate 2048 bit DSA parameters that can be validated: The output values for 461gindex and seed are required for key validation purposes and are not saved to 462the output pem file). 463 464 openssl genpkey -genparam -algorithm DSA -out dsap.pem -pkeyopt pbits:2048 \ 465 -pkeyopt qbits:224 -pkeyopt digest:SHA256 -pkeyopt gindex:1 -text 466 467Generate DSA key from parameters: 468 469 openssl genpkey -paramfile dsap.pem -out dsakey.pem 470 471Generate 4096 bit DH Key using safe prime group ffdhe4096: 472 473 openssl genpkey -algorithm DH -out dhkey.pem -pkeyopt group:ffdhe4096 474 475Generate 2048 bit X9.42 DH key with 256 bit subgroup using RFC5114 group3: 476 477 openssl genpkey -algorithm DHX -out dhkey.pem -pkeyopt dh_rfc5114:3 478 479Generate a DH key using a DH parameters file: 480 481 openssl genpkey -paramfile dhp.pem -out dhkey.pem 482 483Output DH parameters for safe prime group ffdhe2048: 484 485 openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt group:ffdhe2048 486 487Output 2048 bit X9.42 DH parameters with 224 bit subgroup using RFC5114 group2: 488 489 openssl genpkey -genparam -algorithm DHX -out dhp.pem -pkeyopt dh_rfc5114:2 490 491Output 2048 bit X9.42 DH parameters with 224 bit subgroup using FIP186-4 keygen: 492 493 openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \ 494 -pkeyopt pbits:2048 -pkeyopt qbits:224 -pkeyopt digest:SHA256 \ 495 -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:2 496 497Output 1024 bit X9.42 DH parameters with 160 bit subgroup using FIP186-2 keygen: 498 499 openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \ 500 -pkeyopt pbits:1024 -pkeyopt qbits:160 -pkeyopt digest:SHA1 \ 501 -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:1 502 503Output 2048 bit DH parameters: 504 505 openssl genpkey -genparam -algorithm DH -out dhp.pem \ 506 -pkeyopt dh_paramgen_prime_len:2048 507 508Output 2048 bit DH parameters using a generator: 509 510 openssl genpkey -genparam -algorithm DH -out dhpx.pem \ 511 -pkeyopt dh_paramgen_prime_len:2048 \ 512 -pkeyopt dh_paramgen_type:1 513 514Generate EC parameters: 515 516 openssl genpkey -genparam -algorithm EC -out ecp.pem \ 517 -pkeyopt ec_paramgen_curve:secp384r1 \ 518 -pkeyopt ec_param_enc:named_curve 519 520Generate EC key from parameters: 521 522 openssl genpkey -paramfile ecp.pem -out eckey.pem 523 524Generate EC key directly: 525 526 openssl genpkey -algorithm EC -out eckey.pem \ 527 -pkeyopt ec_paramgen_curve:P-384 \ 528 -pkeyopt ec_param_enc:named_curve 529 530Generate an X25519 private key: 531 532 openssl genpkey -algorithm X25519 -out xkey.pem 533 534Generate an ED448 private key: 535 536 openssl genpkey -algorithm ED448 -out xkey.pem 537 538Generate an ML-DSA-65 private key: 539 540 openssl genpkey -algorithm ML-DSA-65 -out ml-dsa-key.pem 541 542Generate an ML-KEM-768 private key: 543 544 openssl genpkey -algorithm ML-KEM-768 -out ml-kem-key.pem 545 546=head1 HISTORY 547 548The ability to use NIST curve names, and to generate an EC key directly, 549were added in OpenSSL 1.0.2. 550The ability to generate X25519 keys was added in OpenSSL 1.1.0. 551The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1. 552 553The B<-engine> option was deprecated in OpenSSL 3.0. 554 555Support for B<ML-DSA> and B<ML-KEM> was added in OpenSSL 3.5. 556 557=head1 COPYRIGHT 558 559Copyright 2006-2025 The OpenSSL Project Authors. All Rights Reserved. 560 561Licensed under the Apache License 2.0 (the "License"). You may not use 562this file except in compliance with the License. You can obtain a copy 563in the file LICENSE in the source distribution or at 564L<https://www.openssl.org/source/license.html>. 565 566=cut 567