doc/apps/req.pod

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