crypto/openssl/doc/apps/genpkey.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 openssl-genpkey,
   6 genpkey - generate a private key
   7
   8 =head1 SYNOPSIS
   9
  10 B<openssl> B<genpkey>
  11 [B<-out filename>]
  12 [B<-outform PEM|DER>]
  13 [B<-pass arg>]
  14 [B<-I<cipher>>]
  15 [B<-engine id>]
  16 [B<-paramfile file>]
  17 [B<-algorithm alg>]
  18 [B<-pkeyopt opt:value>]
  19 [B<-genparam>]
  20 [B<-text>]
  21
  22 =head1 DESCRIPTION
  23
  24 The B<genpkey> command generates a private key.
  25
  26 =head1 OPTIONS
  27
  28 =over 4
  29
  30 =item B<-out filename>
  31
  32 the output filename. If this argument is not specified then standard output is
  33 used.
  34
  35 =item B<-outform DER|PEM>
  36
  37 This specifies the output format DER or PEM. The default format is PEM.
  38
  39 =item B<-pass arg>
  40
  41 The output file password source. For more information about the format of B<arg>
  42 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
  43
  44 =item B<-I<cipher>>
  45
  46 This option encrypts the private key with the supplied cipher. Any algorithm
  47 name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
  48
  49 =item B<-engine id>
  50
  51 Specifying an engine (by its unique B<id> string) will cause B<genpkey>
  52 to attempt to obtain a functional reference to the specified engine,
  53 thus initialising it if needed. The engine will then be set as the default
  54 for all available algorithms. If used this option should precede all other
  55 options.
  56
  57 =item B<-algorithm alg>
  58
  59 Public key algorithm to use such as RSA, DSA or DH. If used this option must
  60 precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
  61 are mutually exclusive. Engines may add algorithms in addition to the standard
  62 built-in ones.
  63
  64 Valid built-in algorithm names for private key generation are RSA and EC.
  65
  66 Valid built-in algorithm names for parameter generation (see the B<-genparam>
  67 option) are DH, DSA and EC.
  68
  69 Note that the algorithm name X9.42 DH may be used as a synonym for the DH
  70 algorithm. These are identical and do not indicate the type of parameters that
  71 will be generated. Use the B<dh_paramgen_type> option to indicate whether PKCS#3
  72 or X9.42 DH parameters are required. See L<DH Parameter Generation Options>
  73 below for more details.
  74
  75 =item B<-pkeyopt opt:value>
  76
  77 Set the public key algorithm option B<opt> to B<value>. The precise set of
  78 options supported depends on the public key algorithm used and its
  79 implementation. See L<KEY GENERATION OPTIONS> and
  80 L<PARAMETER GENERATION OPTIONS> below for more details.
  81
  82 =item B<-genparam>
  83
  84 Generate a set of parameters instead of a private key. If used this option must
  85 precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options.
  86
  87 =item B<-paramfile filename>
  88
  89 Some public key algorithms generate a private key based on a set of parameters.
  90 They can be supplied using this option. If this option is used the public key
  91 algorithm used is determined by the parameters. If used this option must
  92 precede and B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
  93 are mutually exclusive.
  94
  95 =item B<-text>
  96
  97 Print an (unencrypted) text representation of private and public keys and
  98 parameters along with the PEM or DER structure.
  99
 100 =back
 101
 102 =head1 KEY GENERATION OPTIONS
 103
 104 The options supported by each algorith and indeed each implementation of an
 105 algorithm can vary. The options for the OpenSSL implementations are detailed
 106 below.
 107
 108 =head2 RSA Key Generation Options
 109
 110 =over 4
 111
 112 =item B<rsa_keygen_bits:numbits>
 113
 114 The number of bits in the generated key. If not specified 2048 is used.
 115
 116 =item B<rsa_keygen_pubexp:value>
 117
 118 The RSA public exponent value. This can be a large decimal or
 119 hexadecimal value if preceded by B<0x>. Default value is 65537.
 120
 121 =back
 122
 123 =head2 EC Key Generation Options
 124
 125 The EC key generation options can also be used for parameter generation.
 126
 127 =over 4
 128
 129 =item B<ec_paramgen_curve:curve>
 130
 131 The EC curve to use. OpenSSL supports NIST curve names such as "P-256".
 132
 133 =item B<ec_param_enc:encoding>
 134
 135 The encoding to use for parameters. The "encoding" parameter must be either
 136 "named_curve" or "explicit". The default value is "named_curve".
 137
 138 =back
 139
 140 =head1 PARAMETER GENERATION OPTIONS
 141
 142 The options supported by each algorithm and indeed each implementation of an
 143 algorithm can vary. The options for the OpenSSL implementations are detailed
 144 below.
 145
 146 =head2 DSA Parameter Generation Options
 147
 148 =over 4
 149
 150 =item B<dsa_paramgen_bits:numbits>
 151
 152 The number of bits in the generated prime. If not specified 2048 is used.
 153
 154 =item B<dsa_paramgen_q_bits:numbits>
 155
 156 The number of bits in the q parameter. Must be one of 160, 224 or 256. If not
 157 specified 224 is used.
 158
 159 =item B<dsa_paramgen_md:digest>
 160
 161 The digest to use during parameter generation. Must be one of B<sha1>, B<sha224>
 162 or B<sha256>. If set, then the number of bits in B<q> will match the output size
 163 of the specified digest and the B<dsa_paramgen_q_bits> parameter will be
 164 ignored. If not set, then a digest will be used that gives an output matching
 165 the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224
 166 or B<sha256> if it is 256.
 167
 168 =back
 169
 170 =head2 DH Parameter Generation Options
 171
 172 =over 4
 173
 174 =item B<dh_paramgen_prime_len:numbits>
 175
 176 The number of bits in the prime parameter B<p>. The default is 2048.
 177
 178 =item B<dh_paramgen_subprime_len:numbits>
 179
 180 The number of bits in the sub prime parameter B<q>. The default is 256 if the
 181 prime is at least 2048 bits long or 160 otherwise. Only relevant if used in
 182 conjunction with the B<dh_paramgen_type> option to generate X9.42 DH parameters.
 183
 184 =item B<dh_paramgen_generator:value>
 185
 186 The value to use for the generator B<g>. The default is 2.
 187
 188 =item B<dh_paramgen_type:value>
 189
 190 The type of DH parameters to generate. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
 191 The default is 0.
 192
 193 =item B<dh_rfc5114:num>
 194
 195 If this option is set, then the appropriate RFC5114 parameters are used
 196 instead of generating new parameters. The value B<num> can take the
 197 values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of
 198 1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup
 199 and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
 200 2.1, 2.2 and 2.3 respectively. If present this overrides all other DH parameter
 201 options.
 202
 203 =back
 204
 205 =head2 EC Parameter Generation Options
 206
 207 The EC parameter generation options are the same as for key generation. See
 208 L<EC Key Generation Options> above.
 209
 210 =head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS
 211
 212 Gost 2001 support is not enabled by default. To enable this algorithm,
 213 one should load the ccgost engine in the OpenSSL configuration file.
 214 See README.gost file in the engines/ccgost directiry of the source
 215 distribution for more details.
 216
 217 Use of a parameter file for the GOST R 34.10 algorithm is optional.
 218 Parameters can be specified during key generation directly as well as
 219 during generation of parameter file.
 220
 221 =over 4
 222
 223 =item B<paramset:name>
 224
 225 Specifies GOST R 34.10-2001 parameter set according to RFC 4357.
 226 Parameter set can be specified using abbreviated name, object short name or
 227 numeric OID. Following parameter sets are supported:
 228
 229   paramset   OID               Usage
 230   A          1.2.643.2.2.35.1  Signature
 231   B          1.2.643.2.2.35.2  Signature
 232   C          1.2.643.2.2.35.3  Signature
 233   XA         1.2.643.2.2.36.0  Key exchange
 234   XB         1.2.643.2.2.36.1  Key exchange
 235   test       1.2.643.2.2.35.0  Test purposes
 236
 237 =back
 238
 239 =head1 NOTES
 240
 241 The use of the genpkey program is encouraged over the algorithm specific
 242 utilities because additional algorithm options and ENGINE provided algorithms
 243 can be used.
 244
 245 =head1 EXAMPLES
 246
 247 Generate an RSA private key using default parameters:
 248
 249  openssl genpkey -algorithm RSA -out key.pem
 250
 251 Encrypt output private key using 128 bit AES and the passphrase "hello":
 252
 253  openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
 254
 255 Generate a 2048 bit RSA key using 3 as the public exponent:
 256
 257  openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \
 258                                                 -pkeyopt rsa_keygen_pubexp:3
 259
 260 Generate 2048 bit DSA parameters:
 261
 262  openssl genpkey -genparam -algorithm DSA -out dsap.pem \
 263                                                 -pkeyopt dsa_paramgen_bits:2048
 264
 265 Generate DSA key from parameters:
 266
 267  openssl genpkey -paramfile dsap.pem -out dsakey.pem
 268
 269 Generate 2048 bit DH parameters:
 270
 271  openssl genpkey -genparam -algorithm DH -out dhp.pem \
 272                                         -pkeyopt dh_paramgen_prime_len:2048
 273
 274 Generate 2048 bit X9.42 DH parameters:
 275
 276  openssl genpkey -genparam -algorithm DH -out dhpx.pem \
 277                                         -pkeyopt dh_paramgen_prime_len:2048 \
 278                                         -pkeyopt dh_paramgen_type:1
 279
 280 Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
 281
 282  openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
 283
 284 Generate DH key from parameters:
 285
 286  openssl genpkey -paramfile dhp.pem -out dhkey.pem
 287
 288 Generate EC key directly:
 289
 290  openssl genpkey -algorithm EC -out eckey.pem \
 291         -pkeyopt ec_paramgen_curve:P-384 \
 292         -pkeyopt ec_param_enc:named_curve
 293
 294 =head1 HISTORY
 295
 296 The ability to use NIST curve names, and to generate an EC key directly,
 297 were added in OpenSSL 1.0.2.
 298
 299 =cut
 300