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