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