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