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