req.pod revision 340704
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>. This option can be overridden on the command line. 397 398=item B<string_mask> 399 400This option masks out the use of certain string types in certain 401fields. Most users will not need to change this option. 402 403It can be set to several values B<default> which is also the default 404option uses PrintableStrings, T61Strings and BMPStrings if the 405B<pkix> value is used then only PrintableStrings and BMPStrings will 406be used. This follows the PKIX recommendation in RFC2459. If the 407B<utf8only> option is used then only UTF8Strings will be used: this 408is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr> 409option just uses PrintableStrings and T61Strings: certain software has 410problems with BMPStrings and UTF8Strings: in particular Netscape. 411 412=item B<req_extensions> 413 414this specifies the configuration file section containing a list of 415extensions to add to the certificate request. It can be overridden 416by the B<-reqexts> command line switch. See the 417L<x509v3_config(5)|x509v3_config(5)> manual page for details of the 418extension section format. 419 420=item B<x509_extensions> 421 422this specifies the configuration file section containing a list of 423extensions to add to certificate generated when the B<-x509> switch 424is used. It can be overridden by the B<-extensions> command line switch. 425 426=item B<prompt> 427 428if set to the value B<no> this disables prompting of certificate fields 429and just takes values from the config file directly. It also changes the 430expected format of the B<distinguished_name> and B<attributes> sections. 431 432=item B<utf8> 433 434if set to the value B<yes> then field values to be interpreted as UTF8 435strings, by default they are interpreted as ASCII. This means that 436the field values, whether prompted from a terminal or obtained from a 437configuration file, must be valid UTF8 strings. 438 439=item B<attributes> 440 441this specifies the section containing any request attributes: its format 442is the same as B<distinguished_name>. Typically these may contain the 443challengePassword or unstructuredName types. They are currently ignored 444by OpenSSL's request signing utilities but some CAs might want them. 445 446=item B<distinguished_name> 447 448This specifies the section containing the distinguished name fields to 449prompt for when generating a certificate or certificate request. The format 450is described in the next section. 451 452=back 453 454=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT 455 456There are two separate formats for the distinguished name and attribute 457sections. If the B<prompt> option is set to B<no> then these sections 458just consist of field names and values: for example, 459 460 CN=My Name 461 OU=My Organization 462 emailAddress=someone@somewhere.org 463 464This allows external programs (e.g. GUI based) to generate a template file 465with all the field names and values and just pass it to B<req>. An example 466of this kind of configuration file is contained in the B<EXAMPLES> section. 467 468Alternatively if the B<prompt> option is absent or not set to B<no> then the 469file contains field prompting information. It consists of lines of the form: 470 471 fieldName="prompt" 472 fieldName_default="default field value" 473 fieldName_min= 2 474 fieldName_max= 4 475 476"fieldName" is the field name being used, for example commonName (or CN). 477The "prompt" string is used to ask the user to enter the relevant 478details. If the user enters nothing then the default value is used if no 479default value is present then the field is omitted. A field can 480still be omitted if a default value is present if the user just 481enters the '.' character. 482 483The number of characters entered must be between the fieldName_min and 484fieldName_max limits: there may be additional restrictions based 485on the field being used (for example countryName can only ever be 486two characters long and must fit in a PrintableString). 487 488Some fields (such as organizationName) can be used more than once 489in a DN. This presents a problem because configuration files will 490not recognize the same name occurring twice. To avoid this problem 491if the fieldName contains some characters followed by a full stop 492they will be ignored. So for example a second organizationName can 493be input by calling it "1.organizationName". 494 495The actual permitted field names are any object identifier short or 496long names. These are compiled into OpenSSL and include the usual 497values such as commonName, countryName, localityName, organizationName, 498organizationalUnitName, stateOrProvinceName. Additionally emailAddress 499is include as well as name, surname, givenName initials and dnQualifier. 500 501Additional object identifiers can be defined with the B<oid_file> or 502B<oid_section> options in the configuration file. Any additional fields 503will be treated as though they were a DirectoryString. 504 505 506=head1 EXAMPLES 507 508Examine and verify certificate request: 509 510 openssl req -in req.pem -text -verify -noout 511 512Create a private key and then generate a certificate request from it: 513 514 openssl genrsa -out key.pem 2048 515 openssl req -new -key key.pem -out req.pem 516 517The same but just using req: 518 519 openssl req -newkey rsa:2048 -keyout key.pem -out req.pem 520 521Generate a self signed root certificate: 522 523 openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem 524 525Example of a file pointed to by the B<oid_file> option: 526 527 1.2.3.4 shortName A longer Name 528 1.2.3.6 otherName Other longer Name 529 530Example of a section pointed to by B<oid_section> making use of variable 531expansion: 532 533 testoid1=1.2.3.5 534 testoid2=${testoid1}.6 535 536Sample configuration file prompting for field values: 537 538 [ req ] 539 default_bits = 2048 540 default_keyfile = privkey.pem 541 distinguished_name = req_distinguished_name 542 attributes = req_attributes 543 x509_extensions = v3_ca 544 545 dirstring_type = nobmp 546 547 [ req_distinguished_name ] 548 countryName = Country Name (2 letter code) 549 countryName_default = AU 550 countryName_min = 2 551 countryName_max = 2 552 553 localityName = Locality Name (eg, city) 554 555 organizationalUnitName = Organizational Unit Name (eg, section) 556 557 commonName = Common Name (eg, YOUR name) 558 commonName_max = 64 559 560 emailAddress = Email Address 561 emailAddress_max = 40 562 563 [ req_attributes ] 564 challengePassword = A challenge password 565 challengePassword_min = 4 566 challengePassword_max = 20 567 568 [ v3_ca ] 569 570 subjectKeyIdentifier=hash 571 authorityKeyIdentifier=keyid:always,issuer:always 572 basicConstraints = CA:true 573 574Sample configuration containing all field values: 575 576 577 RANDFILE = $ENV::HOME/.rnd 578 579 [ req ] 580 default_bits = 2048 581 default_keyfile = keyfile.pem 582 distinguished_name = req_distinguished_name 583 attributes = req_attributes 584 prompt = no 585 output_password = mypass 586 587 [ req_distinguished_name ] 588 C = GB 589 ST = Test State or Province 590 L = Test Locality 591 O = Organization Name 592 OU = Organizational Unit Name 593 CN = Common Name 594 emailAddress = test@email.address 595 596 [ req_attributes ] 597 challengePassword = A challenge password 598 599 600=head1 NOTES 601 602The header and footer lines in the B<PEM> format are normally: 603 604 -----BEGIN CERTIFICATE REQUEST----- 605 -----END CERTIFICATE REQUEST----- 606 607some software (some versions of Netscape certificate server) instead needs: 608 609 -----BEGIN NEW CERTIFICATE REQUEST----- 610 -----END NEW CERTIFICATE REQUEST----- 611 612which is produced with the B<-newhdr> option but is otherwise compatible. 613Either form is accepted transparently on input. 614 615The certificate requests generated by B<Xenroll> with MSIE have extensions 616added. It includes the B<keyUsage> extension which determines the type of 617key (signature only or general purpose) and any additional OIDs entered 618by the script in an extendedKeyUsage extension. 619 620=head1 DIAGNOSTICS 621 622The following messages are frequently asked about: 623 624 Using configuration from /some/path/openssl.cnf 625 Unable to load config info 626 627This is followed some time later by... 628 629 unable to find 'distinguished_name' in config 630 problems making Certificate Request 631 632The first error message is the clue: it can't find the configuration 633file! Certain operations (like examining a certificate request) don't 634need a configuration file so its use isn't enforced. Generation of 635certificates or requests however does need a configuration file. This 636could be regarded as a bug. 637 638Another puzzling message is this: 639 640 Attributes: 641 a0:00 642 643this is displayed when no attributes are present and the request includes 644the correct empty B<SET OF> structure (the DER encoding of which is 0xa0 6450x00). If you just see: 646 647 Attributes: 648 649then the B<SET OF> is missing and the encoding is technically invalid (but 650it is tolerated). See the description of the command line option B<-asn1-kludge> 651for more information. 652 653=head1 ENVIRONMENT VARIABLES 654 655The variable B<OPENSSL_CONF> if defined allows an alternative configuration 656file location to be specified, it will be overridden by the B<-config> command 657line switch if it is present. For compatibility reasons the B<SSLEAY_CONF> 658environment variable serves the same purpose but its use is discouraged. 659 660=head1 BUGS 661 662OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively 663treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. 664This can cause problems if you need characters that aren't available in 665PrintableStrings and you don't want to or can't use BMPStrings. 666 667As a consequence of the T61String handling the only correct way to represent 668accented characters in OpenSSL is to use a BMPString: unfortunately Netscape 669currently chokes on these. If you have to use accented characters with Netscape 670and MSIE then you currently need to use the invalid T61String form. 671 672The current prompting is not very friendly. It doesn't allow you to confirm what 673you've just entered. Other things like extensions in certificate requests are 674statically defined in the configuration file. Some of these: like an email 675address in subjectAltName should be input by the user. 676 677=head1 SEE ALSO 678 679L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, 680L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>, 681L<x509v3_config(5)|x509v3_config(5)> 682 683=cut 684