1=pod 2 3=head1 NAME 4 5openssl-genpkey, 6genpkey - generate a private key 7 8=head1 SYNOPSIS 9 10B<openssl> B<genpkey> 11[B<-help>] 12[B<-out filename>] 13[B<-outform PEM|DER>] 14[B<-pass arg>] 15[B<-I<cipher>>] 16[B<-engine id>] 17[B<-paramfile file>] 18[B<-algorithm alg>] 19[B<-pkeyopt opt:value>] 20[B<-genparam>] 21[B<-text>] 22 23=head1 DESCRIPTION 24 25The B<genpkey> command generates a private key. 26 27=head1 OPTIONS 28 29=over 4 30 31=item B<-help> 32 33Print out a usage message. 34 35=item B<-out filename> 36 37Output the key to the specified file. If this argument is not specified then 38standard output is used. 39 40=item B<-outform DER|PEM> 41 42This specifies the output format DER or PEM. The default format is PEM. 43 44=item B<-pass arg> 45 46The output file password source. For more information about the format of B<arg> 47see L<openssl(1)/Pass Phrase Options>. 48 49=item B<-I<cipher>> 50 51This option encrypts the private key with the supplied cipher. Any algorithm 52name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>. 53 54=item B<-engine id> 55 56Specifying an engine (by its unique B<id> string) will cause B<genpkey> 57to attempt to obtain a functional reference to the specified engine, 58thus initialising it if needed. The engine will then be set as the default 59for all available algorithms. If used this option should precede all other 60options. 61 62=item B<-algorithm alg> 63 64Public key algorithm to use such as RSA, DSA or DH. If used this option must 65precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> 66are mutually exclusive. Engines may add algorithms in addition to the standard 67built-in ones. 68 69Valid built-in algorithm names for private key generation are RSA, RSA-PSS, EC, 70X25519, X448, ED25519 and ED448. 71 72Valid built-in algorithm names for parameter generation (see the B<-genparam> 73option) are DH, DSA and EC. 74 75Note that the algorithm name X9.42 DH may be used as a synonym for the DH 76algorithm. These are identical and do not indicate the type of parameters that 77will be generated. Use the B<dh_paramgen_type> option to indicate whether PKCS#3 78or X9.42 DH parameters are required. See L<DH Parameter Generation Options> 79below for more details. 80 81=item B<-pkeyopt opt:value> 82 83Set the public key algorithm option B<opt> to B<value>. The precise set of 84options supported depends on the public key algorithm used and its 85implementation. See L<KEY GENERATION OPTIONS> and 86L<PARAMETER GENERATION OPTIONS> below for more details. 87 88=item B<-genparam> 89 90Generate a set of parameters instead of a private key. If used this option must 91precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options. 92 93=item B<-paramfile filename> 94 95Some public key algorithms generate a private key based on a set of parameters. 96They can be supplied using this option. If this option is used the public key 97algorithm used is determined by the parameters. If used this option must 98precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> 99are mutually exclusive. 100 101=item B<-text> 102 103Print an (unencrypted) text representation of private and public keys and 104parameters along with the PEM or DER structure. 105 106=back 107 108=head1 KEY GENERATION OPTIONS 109 110The options supported by each algorithm and indeed each implementation of an 111algorithm can vary. The options for the OpenSSL implementations are detailed 112below. There are no key generation options defined for the X25519, X448, ED25519 113or ED448 algorithms. 114 115=head2 RSA Key Generation Options 116 117=over 4 118 119=item B<rsa_keygen_bits:numbits> 120 121The number of bits in the generated key. If not specified 2048 is used. 122 123=item B<rsa_keygen_primes:numprimes> 124 125The number of primes in the generated key. If not specified 2 is used. 126 127=item B<rsa_keygen_pubexp:value> 128 129The RSA public exponent value. This can be a large decimal or 130hexadecimal value if preceded by B<0x>. Default value is 65537. 131 132=back 133 134=head2 RSA-PSS Key Generation Options 135 136Note: by default an B<RSA-PSS> key has no parameter restrictions. 137 138=over 4 139 140=item B<rsa_keygen_bits:numbits>, B<rsa_keygen_primes:numprimes>, B<rsa_keygen_pubexp:value> 141 142These options have the same meaning as the B<RSA> algorithm. 143 144=item B<rsa_pss_keygen_md:digest> 145 146If set the key is restricted and can only use B<digest> for signing. 147 148=item B<rsa_pss_keygen_mgf1_md:digest> 149 150If set the key is restricted and can only use B<digest> as it's MGF1 151parameter. 152 153=item B<rsa_pss_keygen_saltlen:len> 154 155If set the key is restricted and B<len> specifies the minimum salt length. 156 157=back 158 159=head2 EC Key Generation Options 160 161The EC key generation options can also be used for parameter generation. 162 163=over 4 164 165=item B<ec_paramgen_curve:curve> 166 167The EC curve to use. OpenSSL supports NIST curve names such as "P-256". 168 169=item B<ec_param_enc:encoding> 170 171The encoding to use for parameters. The "encoding" parameter must be either 172"named_curve" or "explicit". The default value is "named_curve". 173 174=back 175 176=head1 PARAMETER GENERATION OPTIONS 177 178The options supported by each algorithm and indeed each implementation of an 179algorithm can vary. The options for the OpenSSL implementations are detailed 180below. 181 182=head2 DSA Parameter Generation Options 183 184=over 4 185 186=item B<dsa_paramgen_bits:numbits> 187 188The number of bits in the generated prime. If not specified 2048 is used. 189 190=item B<dsa_paramgen_q_bits:numbits> 191 192The number of bits in the q parameter. Must be one of 160, 224 or 256. If not 193specified 224 is used. 194 195=item B<dsa_paramgen_md:digest> 196 197The digest to use during parameter generation. Must be one of B<sha1>, B<sha224> 198or B<sha256>. If set, then the number of bits in B<q> will match the output size 199of the specified digest and the B<dsa_paramgen_q_bits> parameter will be 200ignored. If not set, then a digest will be used that gives an output matching 201the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224 202or B<sha256> if it is 256. 203 204=back 205 206=head2 DH Parameter Generation Options 207 208=over 4 209 210=item B<dh_paramgen_prime_len:numbits> 211 212The number of bits in the prime parameter B<p>. The default is 2048. 213 214=item B<dh_paramgen_subprime_len:numbits> 215 216The number of bits in the sub prime parameter B<q>. The default is 256 if the 217prime is at least 2048 bits long or 160 otherwise. Only relevant if used in 218conjunction with the B<dh_paramgen_type> option to generate X9.42 DH parameters. 219 220=item B<dh_paramgen_generator:value> 221 222The value to use for the generator B<g>. The default is 2. 223 224=item B<dh_paramgen_type:value> 225 226The type of DH parameters to generate. Use 0 for PKCS#3 DH and 1 for X9.42 DH. 227The default is 0. 228 229=item B<dh_rfc5114:num> 230 231If this option is set, then the appropriate RFC5114 parameters are used 232instead of generating new parameters. The value B<num> can take the 233values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of 2341024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup 235and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections 2362.1, 2.2 and 2.3 respectively. If present this overrides all other DH parameter 237options. 238 239=back 240 241=head2 EC Parameter Generation Options 242 243The EC parameter generation options are the same as for key generation. See 244L<EC Key Generation Options> above. 245 246=head1 NOTES 247 248The use of the genpkey program is encouraged over the algorithm specific 249utilities because additional algorithm options and ENGINE provided algorithms 250can be used. 251 252=head1 EXAMPLES 253 254Generate an RSA private key using default parameters: 255 256 openssl genpkey -algorithm RSA -out key.pem 257 258Encrypt output private key using 128 bit AES and the passphrase "hello": 259 260 openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello 261 262Generate a 2048 bit RSA key using 3 as the public exponent: 263 264 openssl genpkey -algorithm RSA -out key.pem \ 265 -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3 266 267Generate 2048 bit DSA parameters: 268 269 openssl genpkey -genparam -algorithm DSA -out dsap.pem \ 270 -pkeyopt dsa_paramgen_bits:2048 271 272Generate DSA key from parameters: 273 274 openssl genpkey -paramfile dsap.pem -out dsakey.pem 275 276Generate 2048 bit DH parameters: 277 278 openssl genpkey -genparam -algorithm DH -out dhp.pem \ 279 -pkeyopt dh_paramgen_prime_len:2048 280 281Generate 2048 bit X9.42 DH parameters: 282 283 openssl genpkey -genparam -algorithm DH -out dhpx.pem \ 284 -pkeyopt dh_paramgen_prime_len:2048 \ 285 -pkeyopt dh_paramgen_type:1 286 287Output RFC5114 2048 bit DH parameters with 224 bit subgroup: 288 289 openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2 290 291Generate DH key from parameters: 292 293 openssl genpkey -paramfile dhp.pem -out dhkey.pem 294 295Generate EC parameters: 296 297 openssl genpkey -genparam -algorithm EC -out ecp.pem \ 298 -pkeyopt ec_paramgen_curve:secp384r1 \ 299 -pkeyopt ec_param_enc:named_curve 300 301Generate EC key from parameters: 302 303 openssl genpkey -paramfile ecp.pem -out eckey.pem 304 305Generate EC key directly: 306 307 openssl genpkey -algorithm EC -out eckey.pem \ 308 -pkeyopt ec_paramgen_curve:P-384 \ 309 -pkeyopt ec_param_enc:named_curve 310 311Generate an X25519 private key: 312 313 openssl genpkey -algorithm X25519 -out xkey.pem 314 315Generate an ED448 private key: 316 317 openssl genpkey -algorithm ED448 -out xkey.pem 318 319=head1 HISTORY 320 321The ability to use NIST curve names, and to generate an EC key directly, 322were added in OpenSSL 1.0.2. 323The ability to generate X25519 keys was added in OpenSSL 1.1.0. 324The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1. 325 326=head1 COPYRIGHT 327 328Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved. 329 330Licensed under the OpenSSL license (the "License"). You may not use 331this file except in compliance with the License. You can obtain a copy 332in the file LICENSE in the source distribution or at 333L<https://www.openssl.org/source/license.html>. 334 335=cut 336