doc/apps/req.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 req - PKCS#10 certificate request and certificate generating utility.
   7
   8 =head1 SYNOPSIS
   9
  10 B<openssl> B<req>
  11 [B<-inform PEM|DER>]
  12 [B<-outform PEM|DER>]
  13 [B<-in filename>]
  14 [B<-passin arg>]
  15 [B<-out filename>]
  16 [B<-passout arg>]
  17 [B<-text>]
  18 [B<-noout>]
  19 [B<-verify>]
  20 [B<-modulus>]
  21 [B<-new>]
  22 [B<-rand file(s)>]
  23 [B<-newkey rsa:bits>]
  24 [B<-newkey dsa:file>]
  25 [B<-nodes>]
  26 [B<-key filename>]
  27 [B<-keyform PEM|DER>]
  28 [B<-keyout filename>]
  29 [B<-[md5|sha1|md2|mdc2]>]
  30 [B<-config filename>]
  31 [B<-subj arg>]
  32 [B<-x509>]
  33 [B<-days n>]
  34 [B<-set_serial n>]
  35 [B<-asn1-kludge>]
  36 [B<-newhdr>]
  37 [B<-extensions section>]
  38 [B<-reqexts section>]
  39 [B<-batch>]
  40 [B<-verbose>]
  41
  42 =head1 DESCRIPTION
  43
  44 The B<req> command primarily creates and processes certificate requests
  45 in PKCS#10 format. It can additionally create self signed certificates
  46 for use as root CAs for example.
  47
  48 =head1 COMMAND OPTIONS
  49
  50 =over 4
  51
  52 =item B<-inform DER|PEM>
  53
  54 This specifies the input format. The B<DER> option uses an ASN1 DER encoded
  55 form compatible with the PKCS#10. The B<PEM> form is the default format: it
  56 consists of the B<DER> format base64 encoded with additional header and
  57 footer lines.
  58
  59 =item B<-outform DER|PEM>
  60
  61 This specifies the output format, the options have the same meaning as the
  62 B<-inform> option.
  63
  64 =item B<-in filename>
  65
  66 This specifies the input filename to read a request from or standard input
  67 if this option is not specified. A request is only read if the creation
  68 options (B<-new> and B<-newkey>) are not specified.
  69
  70 =item B<-passin arg>
  71
  72 the input file password source. For more information about the format of B<arg>
  73 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
  74
  75 =item B<-out filename>
  76
  77 This specifies the output filename to write to or standard output by
  78 default.
  79
  80 =item B<-passout arg>
  81
  82 the output file password source. For more information about the format of B<arg>
  83 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
  84
  85 =item B<-text>
  86
  87 prints out the certificate request in text form.
  88
  89 =item B<-noout>
  90
  91 this option prevents output of the encoded version of the request.
  92
  93 =item B<-modulus>
  94
  95 this option prints out the value of the modulus of the public key
  96 contained in the request.
  97
  98 =item B<-verify>
  99
 100 verifies the signature on the request.
 101
 102 =item B<-new>
 103
 104 this option generates a new certificate request. It will prompt
 105 the user for the relevant field values. The actual fields
 106 prompted for and their maximum and minimum sizes are specified
 107 in the configuration file and any requested extensions.
 108
 109 If the B<-key> option is not used it will generate a new RSA private
 110 key using information specified in the configuration file.
 111
 112 =item B<-rand file(s)>
 113
 114 a file or files containing random data used to seed the random number
 115 generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
 116 Multiple files can be specified separated by a OS-dependent character.
 117 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
 118 all others.
 119
 120 =item B<-newkey arg>
 121
 122 this option creates a new certificate request and a new private
 123 key. The argument takes one of two forms. B<rsa:nbits>, where
 124 B<nbits> is the number of bits, generates an RSA key B<nbits>
 125 in size. B<dsa:filename> generates a DSA key using the parameters
 126 in the file B<filename>.
 127
 128 =item B<-key filename>
 129
 130 This specifies the file to read the private key from. It also
 131 accepts PKCS#8 format private keys for PEM format files.
 132
 133 =item B<-keyform PEM|DER>
 134
 135 the format of the private key file specified in the B<-key>
 136 argument. PEM is the default.
 137
 138 =item B<-keyout filename>
 139
 140 this gives the filename to write the newly created private key to.
 141 If this option is not specified then the filename present in the
 142 configuration file is used.
 143
 144 =item B<-nodes>
 145
 146 if this option is specified then if a private key is created it
 147 will not be encrypted.
 148
 149 =item B<-[md5|sha1|md2|mdc2]>
 150
 151 this specifies the message digest to sign the request with. This
 152 overrides the digest algorithm specified in the configuration file.
 153 This option is ignored for DSA requests: they always use SHA1.
 154
 155 =item B<-config filename>
 156
 157 this allows an alternative configuration file to be specified,
 158 this overrides the compile time filename or any specified in
 159 the B<OPENSSL_CONF> environment variable.
 160
 161 =item B<-subj arg>
 162
 163 sets subject name for new request or supersedes the subject name
 164 when processing a request.
 165
 166 =item B<-x509>
 167
 168 this option outputs a self signed certificate instead of a certificate
 169 request. This is typically used to generate a test certificate or
 170 a self signed root CA. The extensions added to the certificate
 171 (if any) are specified in the configuration file. Unless specified
 172 using the B<set_serial> option B<0> will be used for the serial
 173 number.
 174
 175 =item B<-days n>
 176
 177 when the B<-x509> option is being used this specifies the number of
 178 days to certify the certificate for. The default is 30 days.
 179
 180 =item B<-set_serial n>
 181
 182 serial number to use when outputting a self signed certifcate. This
 183 may be specified as a decimal value or a hex value if preceded by B<0x>.
 184 It is possible to use negative serial numbers but this is not recommended.
 185
 186 =item B<-extensions section>
 187
 188 =item B<-reqexts section>
 189
 190 these options specify alternative sections to include certificate
 191 extensions (if the B<-x509> option is present) or certificate
 192 request extensions. This allows several different sections to
 193 be used in the same configuration file to specify requests for
 194 a variety of purposes.
 195
 196 =item B<-asn1-kludge>
 197
 198 by default the B<req> command outputs certificate requests containing
 199 no attributes in the correct PKCS#10 format. However certain CAs will only
 200 accept requests containing no attributes in an invalid form: this
 201 option produces this invalid format.
 202
 203 More precisely the B<Attributes> in a PKCS#10 certificate request
 204 are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
 205 if no attributes are present then they should be encoded as an
 206 empty B<SET OF>. The invalid form does not include the empty
 207 B<SET OF> whereas the correct form does.
 208
 209 It should be noted that very few CAs still require the use of this option.
 210
 211 =item B<-newhdr>
 212
 213 Adds the word B<NEW> to the PEM file header and footer lines on the outputed
 214 request. Some software (Netscape certificate server) and some CAs need this.
 215
 216 =item B<-batch>
 217
 218 non-interactive mode.
 219
 220 =item B<-verbose>
 221
 222 print extra details about the operations being performed.
 223
 224 =back
 225
 226 =head1 CONFIGURATION FILE FORMAT
 227
 228 The configuration options are specified in the B<req> section of
 229 the configuration file. As with all configuration files if no
 230 value is specified in the specific section (i.e. B<req>) then
 231 the initial unnamed or B<default> section is searched too.
 232
 233 The options available are described in detail below.
 234
 235 =over 4
 236
 237 =item B<input_password output_password>
 238
 239 The passwords for the input private key file (if present) and
 240 the output private key file (if one will be created). The
 241 command line options B<passin> and B<passout> override the
 242 configuration file values.
 243
 244 =item B<default_bits>
 245
 246 This specifies the default key size in bits. If not specified then
 247 512 is used. It is used if the B<-new> option is used. It can be
 248 overridden by using the B<-newkey> option.
 249
 250 =item B<default_keyfile>
 251
 252 This is the default filename to write a private key to. If not
 253 specified the key is written to standard output. This can be
 254 overridden by the B<-keyout> option.
 255
 256 =item B<oid_file>
 257
 258 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
 259 Each line of the file should consist of the numerical form of the
 260 object identifier followed by white space then the short name followed
 261 by white space and finally the long name.
 262
 263 =item B<oid_section>
 264
 265 This specifies a section in the configuration file containing extra
 266 object identifiers. Each line should consist of the short name of the
 267 object identifier followed by B<=> and the numerical form. The short
 268 and long names are the same when this option is used.
 269
 270 =item B<RANDFILE>
 271
 272 This specifies a filename in which random number seed information is
 273 placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
 274 It is used for private key generation.
 275
 276 =item B<encrypt_key>
 277
 278 If this is set to B<no> then if a private key is generated it is
 279 B<not> encrypted. This is equivalent to the B<-nodes> command line
 280 option. For compatibility B<encrypt_rsa_key> is an equivalent option.
 281
 282 =item B<default_md>
 283
 284 This option specifies the digest algorithm to use. Possible values
 285 include B<md5 sha1 mdc2>. If not present then MD5 is used. This
 286 option can be overridden on the command line.
 287
 288 =item B<string_mask>
 289
 290 This option masks out the use of certain string types in certain
 291 fields. Most users will not need to change this option.
 292
 293 It can be set to several values B<default> which is also the default
 294 option uses PrintableStrings, T61Strings and BMPStrings if the
 295 B<pkix> value is used then only PrintableStrings and BMPStrings will
 296 be used. This follows the PKIX recommendation in RFC2459. If the
 297 B<utf8only> option is used then only UTF8Strings will be used: this
 298 is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
 299 option just uses PrintableStrings and T61Strings: certain software has
 300 problems with BMPStrings and UTF8Strings: in particular Netscape.
 301
 302 =item B<req_extensions>
 303
 304 this specifies the configuration file section containing a list of
 305 extensions to add to the certificate request. It can be overridden
 306 by the B<-reqexts> command line switch.
 307
 308 =item B<x509_extensions>
 309
 310 this specifies the configuration file section containing a list of
 311 extensions to add to certificate generated when the B<-x509> switch
 312 is used. It can be overridden by the B<-extensions> command line switch.
 313
 314 =item B<prompt>
 315
 316 if set to the value B<no> this disables prompting of certificate fields
 317 and just takes values from the config file directly. It also changes the
 318 expected format of the B<distinguished_name> and B<attributes> sections.
 319
 320 =item B<attributes>
 321
 322 this specifies the section containing any request attributes: its format
 323 is the same as B<distinguished_name>. Typically these may contain the
 324 challengePassword or unstructuredName types. They are currently ignored
 325 by OpenSSL's request signing utilities but some CAs might want them.
 326
 327 =item B<distinguished_name>
 328
 329 This specifies the section containing the distinguished name fields to
 330 prompt for when generating a certificate or certificate request. The format
 331 is described in the next section.
 332
 333 =back
 334
 335 =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
 336
 337 There are two separate formats for the distinguished name and attribute
 338 sections. If the B<prompt> option is set to B<no> then these sections
 339 just consist of field names and values: for example,
 340
 341  CN=My Name
 342  OU=My Organization
 343  emailAddress=someone@somewhere.org
 344
 345 This allows external programs (e.g. GUI based) to generate a template file
 346 with all the field names and values and just pass it to B<req>. An example
 347 of this kind of configuration file is contained in the B<EXAMPLES> section.
 348
 349 Alternatively if the B<prompt> option is absent or not set to B<no> then the
 350 file contains field prompting information. It consists of lines of the form:
 351
 352  fieldName="prompt"
 353  fieldName_default="default field value"
 354  fieldName_min= 2
 355  fieldName_max= 4
 356
 357 "fieldName" is the field name being used, for example commonName (or CN).
 358 The "prompt" string is used to ask the user to enter the relevant
 359 details. If the user enters nothing then the default value is used if no
 360 default value is present then the field is omitted. A field can
 361 still be omitted if a default value is present if the user just
 362 enters the '.' character.
 363
 364 The number of characters entered must be between the fieldName_min and
 365 fieldName_max limits: there may be additional restrictions based
 366 on the field being used (for example countryName can only ever be
 367 two characters long and must fit in a PrintableString).
 368
 369 Some fields (such as organizationName) can be used more than once
 370 in a DN. This presents a problem because configuration files will
 371 not recognize the same name occurring twice. To avoid this problem
 372 if the fieldName contains some characters followed by a full stop
 373 they will be ignored. So for example a second organizationName can
 374 be input by calling it "1.organizationName".
 375
 376 The actual permitted field names are any object identifier short or
 377 long names. These are compiled into OpenSSL and include the usual
 378 values such as commonName, countryName, localityName, organizationName,
 379 organizationUnitName, stateOrPrivinceName. Additionally emailAddress
 380 is include as well as name, surname, givenName initials and dnQualifier.
 381
 382 Additional object identifiers can be defined with the B<oid_file> or
 383 B<oid_section> options in the configuration file. Any additional fields
 384 will be treated as though they were a DirectoryString.
 385
 386
 387 =head1 EXAMPLES
 388
 389 Examine and verify certificate request:
 390
 391  openssl req -in req.pem -text -verify -noout
 392
 393 Create a private key and then generate a certificate request from it:
 394
 395  openssl genrsa -out key.pem 1024
 396  openssl req -new -key key.pem -out req.pem
 397
 398 The same but just using req:
 399
 400  openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
 401
 402 Generate a self signed root certificate:
 403
 404  openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
 405
 406 Example of a file pointed to by the B<oid_file> option:
 407
 408  1.2.3.4        shortName       A longer Name
 409  1.2.3.6        otherName       Other longer Name
 410
 411 Example of a section pointed to by B<oid_section> making use of variable
 412 expansion:
 413
 414  testoid1=1.2.3.5
 415  testoid2=${testoid1}.6
 416
 417 Sample configuration file prompting for field values:
 418
 419  [ req ]
 420  default_bits           = 1024
 421  default_keyfile        = privkey.pem
 422  distinguished_name     = req_distinguished_name
 423  attributes             = req_attributes
 424  x509_extensions        = v3_ca
 425
 426  dirstring_type = nobmp
 427
 428  [ req_distinguished_name ]
 429  countryName                    = Country Name (2 letter code)
 430  countryName_default            = AU
 431  countryName_min                = 2
 432  countryName_max                = 2
 433
 434  localityName                   = Locality Name (eg, city)
 435
 436  organizationalUnitName         = Organizational Unit Name (eg, section)
 437
 438  commonName                     = Common Name (eg, YOUR name)
 439  commonName_max                 = 64
 440
 441  emailAddress                   = Email Address
 442  emailAddress_max               = 40
 443
 444  [ req_attributes ]
 445  challengePassword              = A challenge password
 446  challengePassword_min          = 4
 447  challengePassword_max          = 20
 448
 449  [ v3_ca ]
 450
 451  subjectKeyIdentifier=hash
 452  authorityKeyIdentifier=keyid:always,issuer:always
 453  basicConstraints = CA:true
 454
 455 Sample configuration containing all field values:
 456
 457
 458  RANDFILE               = $ENV::HOME/.rnd
 459
 460  [ req ]
 461  default_bits           = 1024
 462  default_keyfile        = keyfile.pem
 463  distinguished_name     = req_distinguished_name
 464  attributes             = req_attributes
 465  prompt                 = no
 466  output_password        = mypass
 467
 468  [ req_distinguished_name ]
 469  C                      = GB
 470  ST                     = Test State or Province
 471  L                      = Test Locality
 472  O                      = Organization Name
 473  OU                     = Organizational Unit Name
 474  CN                     = Common Name
 475  emailAddress           = test@email.address
 476
 477  [ req_attributes ]
 478  challengePassword              = A challenge password
 479
 480
 481 =head1 NOTES
 482
 483 The header and footer lines in the B<PEM> format are normally:
 484
 485  -----BEGIN CERTIFICATE REQUEST----
 486  -----END CERTIFICATE REQUEST----
 487
 488 some software (some versions of Netscape certificate server) instead needs:
 489
 490  -----BEGIN NEW CERTIFICATE REQUEST----
 491  -----END NEW CERTIFICATE REQUEST----
 492
 493 which is produced with the B<-newhdr> option but is otherwise compatible.
 494 Either form is accepted transparently on input.
 495
 496 The certificate requests generated by B<Xenroll> with MSIE have extensions
 497 added. It includes the B<keyUsage> extension which determines the type of
 498 key (signature only or general purpose) and any additional OIDs entered
 499 by the script in an extendedKeyUsage extension.
 500
 501 =head1 DIAGNOSTICS
 502
 503 The following messages are frequently asked about:
 504
 505         Using configuration from /some/path/openssl.cnf
 506         Unable to load config info
 507
 508 This is followed some time later by...
 509
 510         unable to find 'distinguished_name' in config
 511         problems making Certificate Request
 512
 513 The first error message is the clue: it can't find the configuration
 514 file! Certain operations (like examining a certificate request) don't
 515 need a configuration file so its use isn't enforced. Generation of
 516 certificates or requests however does need a configuration file. This
 517 could be regarded as a bug.
 518
 519 Another puzzling message is this:
 520
 521         Attributes:
 522             a0:00
 523
 524 this is displayed when no attributes are present and the request includes
 525 the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
 526 0x00). If you just see:
 527
 528         Attributes:
 529
 530 then the B<SET OF> is missing and the encoding is technically invalid (but
 531 it is tolerated). See the description of the command line option B<-asn1-kludge>
 532 for more information.
 533
 534 =head1 ENVIRONMENT VARIABLES
 535
 536 The variable B<OPENSSL_CONF> if defined allows an alternative configuration
 537 file location to be specified, it will be overridden by the B<-config> command
 538 line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
 539 environment variable serves the same purpose but its use is discouraged.
 540
 541 =head1 BUGS
 542
 543 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
 544 treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
 545 This can cause problems if you need characters that aren't available in
 546 PrintableStrings and you don't want to or can't use BMPStrings.
 547
 548 As a consequence of the T61String handling the only correct way to represent
 549 accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
 550 currently chokes on these. If you have to use accented characters with Netscape
 551 and MSIE then you currently need to use the invalid T61String form.
 552
 553 The current prompting is not very friendly. It doesn't allow you to confirm what
 554 you've just entered. Other things like extensions in certificate requests are
 555 statically defined in the configuration file. Some of these: like an email
 556 address in subjectAltName should be input by the user.
 557
 558 =head1 SEE ALSO
 559
 560 L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
 561 L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>
 562
 563 =cut