1 2=pod 3 4=head1 NAME 5 6req - PKCS#10 certificate request and certificate generating utility. 7 8=head1 SYNOPSIS 9 10B<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<-subj arg>] 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 B<0> will be used for the serial 239number. 240 241=item B<-days n> 242 243when the B<-x509> option is being used this specifies the number of 244days to certify the certificate for. The default is 30 days. 245 246=item B<-set_serial n> 247 248serial number to use when outputting a self signed certificate. This 249may be specified as a decimal value or a hex value if preceded by B<0x>. 250It is possible to use negative serial numbers but this is not recommended. 251 252=item B<-extensions section> 253 254=item B<-reqexts section> 255 256these options specify alternative sections to include certificate 257extensions (if the B<-x509> option is present) or certificate 258request extensions. This allows several different sections to 259be used in the same configuration file to specify requests for 260a variety of purposes. 261 262=item B<-utf8> 263 264this option causes field values to be interpreted as UTF8 strings, by 265default they are interpreted as ASCII. This means that the field 266values, whether prompted from a terminal or obtained from a 267configuration file, must be valid UTF8 strings. 268 269=item B<-nameopt option> 270 271option which determines how the subject or issuer names are displayed. The 272B<option> argument can be a single option or multiple options separated by 273commas. Alternatively the B<-nameopt> switch may be used more than once to 274set multiple options. See the L<x509(1)|x509(1)> manual page for details. 275 276=item B<-reqopt> 277 278customise the output format used with B<-text>. The B<option> argument can be 279a single option or multiple options separated by commas. 280 281See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)> 282command. 283 284 285=item B<-asn1-kludge> 286 287by default the B<req> command outputs certificate requests containing 288no attributes in the correct PKCS#10 format. However certain CAs will only 289accept requests containing no attributes in an invalid form: this 290option produces this invalid format. 291 292More precisely the B<Attributes> in a PKCS#10 certificate request 293are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so 294if no attributes are present then they should be encoded as an 295empty B<SET OF>. The invalid form does not include the empty 296B<SET OF> whereas the correct form does. 297 298It should be noted that very few CAs still require the use of this option. 299 300=item B<-no-asn1-kludge> 301 302Reverses effect of B<-asn1-kludge> 303 304=item B<-newhdr> 305 306Adds the word B<NEW> to the PEM file header and footer lines on the outputted 307request. Some software (Netscape certificate server) and some CAs need this. 308 309=item B<-batch> 310 311non-interactive mode. 312 313=item B<-verbose> 314 315print extra details about the operations being performed. 316 317=item B<-engine id> 318 319specifying an engine (by its unique B<id> string) will cause B<req> 320to attempt to obtain a functional reference to the specified engine, 321thus initialising it if needed. The engine will then be set as the default 322for all available algorithms. 323 324=item B<-keygen_engine id> 325 326specifies an engine (by its unique B<id> string) which would be used 327for key generation operations. 328 329=back 330 331=head1 CONFIGURATION FILE FORMAT 332 333The configuration options are specified in the B<req> section of 334the configuration file. As with all configuration files if no 335value is specified in the specific section (i.e. B<req>) then 336the initial unnamed or B<default> section is searched too. 337 338The options available are described in detail below. 339 340=over 4 341 342=item B<input_password output_password> 343 344The passwords for the input private key file (if present) and 345the output private key file (if one will be created). The 346command line options B<passin> and B<passout> override the 347configuration file values. 348 349=item B<default_bits> 350 351This specifies the default key size in bits. If not specified then 352512 is used. It is used if the B<-new> option is used. It can be 353overridden by using the B<-newkey> option. 354 355=item B<default_keyfile> 356 357This is the default filename to write a private key to. If not 358specified the key is written to standard output. This can be 359overridden by the B<-keyout> option. 360 361=item B<oid_file> 362 363This specifies a file containing additional B<OBJECT IDENTIFIERS>. 364Each line of the file should consist of the numerical form of the 365object identifier followed by white space then the short name followed 366by white space and finally the long name. 367 368=item B<oid_section> 369 370This specifies a section in the configuration file containing extra 371object identifiers. Each line should consist of the short name of the 372object identifier followed by B<=> and the numerical form. The short 373and long names are the same when this option is used. 374 375=item B<RANDFILE> 376 377This specifies a filename in which random number seed information is 378placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 379It is used for private key generation. 380 381=item B<encrypt_key> 382 383If this is set to B<no> then if a private key is generated it is 384B<not> encrypted. This is equivalent to the B<-nodes> command line 385option. For compatibility B<encrypt_rsa_key> is an equivalent option. 386 387=item B<default_md> 388 389This option specifies the digest algorithm to use. Possible values 390include B<md5 sha1 mdc2>. If not present then MD5 is used. This 391option can be overridden on the command line. 392 393=item B<string_mask> 394 395This option masks out the use of certain string types in certain 396fields. Most users will not need to change this option. 397 398It can be set to several values B<default> which is also the default 399option uses PrintableStrings, T61Strings and BMPStrings if the 400B<pkix> value is used then only PrintableStrings and BMPStrings will 401be used. This follows the PKIX recommendation in RFC2459. If the 402B<utf8only> option is used then only UTF8Strings will be used: this 403is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr> 404option just uses PrintableStrings and T61Strings: certain software has 405problems with BMPStrings and UTF8Strings: in particular Netscape. 406 407=item B<req_extensions> 408 409this specifies the configuration file section containing a list of 410extensions to add to the certificate request. It can be overridden 411by the B<-reqexts> command line switch. See the 412L<x509v3_config(5)|x509v3_config(5)> manual page for details of the 413extension section format. 414 415=item B<x509_extensions> 416 417this specifies the configuration file section containing a list of 418extensions to add to certificate generated when the B<-x509> switch 419is used. It can be overridden by the B<-extensions> command line switch. 420 421=item B<prompt> 422 423if set to the value B<no> this disables prompting of certificate fields 424and just takes values from the config file directly. It also changes the 425expected format of the B<distinguished_name> and B<attributes> sections. 426 427=item B<utf8> 428 429if set to the value B<yes> then field values to be interpreted as UTF8 430strings, by default they are interpreted as ASCII. This means that 431the field values, whether prompted from a terminal or obtained from a 432configuration file, must be valid UTF8 strings. 433 434=item B<attributes> 435 436this specifies the section containing any request attributes: its format 437is the same as B<distinguished_name>. Typically these may contain the 438challengePassword or unstructuredName types. They are currently ignored 439by OpenSSL's request signing utilities but some CAs might want them. 440 441=item B<distinguished_name> 442 443This specifies the section containing the distinguished name fields to 444prompt for when generating a certificate or certificate request. The format 445is described in the next section. 446 447=back 448 449=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT 450 451There are two separate formats for the distinguished name and attribute 452sections. If the B<prompt> option is set to B<no> then these sections 453just consist of field names and values: for example, 454 455 CN=My Name 456 OU=My Organization 457 emailAddress=someone@somewhere.org 458 459This allows external programs (e.g. GUI based) to generate a template file 460with all the field names and values and just pass it to B<req>. An example 461of this kind of configuration file is contained in the B<EXAMPLES> section. 462 463Alternatively if the B<prompt> option is absent or not set to B<no> then the 464file contains field prompting information. It consists of lines of the form: 465 466 fieldName="prompt" 467 fieldName_default="default field value" 468 fieldName_min= 2 469 fieldName_max= 4 470 471"fieldName" is the field name being used, for example commonName (or CN). 472The "prompt" string is used to ask the user to enter the relevant 473details. If the user enters nothing then the default value is used if no 474default value is present then the field is omitted. A field can 475still be omitted if a default value is present if the user just 476enters the '.' character. 477 478The number of characters entered must be between the fieldName_min and 479fieldName_max limits: there may be additional restrictions based 480on the field being used (for example countryName can only ever be 481two characters long and must fit in a PrintableString). 482 483Some fields (such as organizationName) can be used more than once 484in a DN. This presents a problem because configuration files will 485not recognize the same name occurring twice. To avoid this problem 486if the fieldName contains some characters followed by a full stop 487they will be ignored. So for example a second organizationName can 488be input by calling it "1.organizationName". 489 490The actual permitted field names are any object identifier short or 491long names. These are compiled into OpenSSL and include the usual 492values such as commonName, countryName, localityName, organizationName, 493organizationUnitName, stateOrProvinceName. Additionally emailAddress 494is include as well as name, surname, givenName initials and dnQualifier. 495 496Additional object identifiers can be defined with the B<oid_file> or 497B<oid_section> options in the configuration file. Any additional fields 498will be treated as though they were a DirectoryString. 499 500 501=head1 EXAMPLES 502 503Examine and verify certificate request: 504 505 openssl req -in req.pem -text -verify -noout 506 507Create a private key and then generate a certificate request from it: 508 509 openssl genrsa -out key.pem 1024 510 openssl req -new -key key.pem -out req.pem 511 512The same but just using req: 513 514 openssl req -newkey rsa:1024 -keyout key.pem -out req.pem 515 516Generate a self signed root certificate: 517 518 openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem 519 520Example of a file pointed to by the B<oid_file> option: 521 522 1.2.3.4 shortName A longer Name 523 1.2.3.6 otherName Other longer Name 524 525Example of a section pointed to by B<oid_section> making use of variable 526expansion: 527 528 testoid1=1.2.3.5 529 testoid2=${testoid1}.6 530 531Sample configuration file prompting for field values: 532 533 [ req ] 534 default_bits = 1024 535 default_keyfile = privkey.pem 536 distinguished_name = req_distinguished_name 537 attributes = req_attributes 538 x509_extensions = v3_ca 539 540 dirstring_type = nobmp 541 542 [ req_distinguished_name ] 543 countryName = Country Name (2 letter code) 544 countryName_default = AU 545 countryName_min = 2 546 countryName_max = 2 547 548 localityName = Locality Name (eg, city) 549 550 organizationalUnitName = Organizational Unit Name (eg, section) 551 552 commonName = Common Name (eg, YOUR name) 553 commonName_max = 64 554 555 emailAddress = Email Address 556 emailAddress_max = 40 557 558 [ req_attributes ] 559 challengePassword = A challenge password 560 challengePassword_min = 4 561 challengePassword_max = 20 562 563 [ v3_ca ] 564 565 subjectKeyIdentifier=hash 566 authorityKeyIdentifier=keyid:always,issuer:always 567 basicConstraints = CA:true 568 569Sample configuration containing all field values: 570 571 572 RANDFILE = $ENV::HOME/.rnd 573 574 [ req ] 575 default_bits = 1024 576 default_keyfile = keyfile.pem 577 distinguished_name = req_distinguished_name 578 attributes = req_attributes 579 prompt = no 580 output_password = mypass 581 582 [ req_distinguished_name ] 583 C = GB 584 ST = Test State or Province 585 L = Test Locality 586 O = Organization Name 587 OU = Organizational Unit Name 588 CN = Common Name 589 emailAddress = test@email.address 590 591 [ req_attributes ] 592 challengePassword = A challenge password 593 594 595=head1 NOTES 596 597The header and footer lines in the B<PEM> format are normally: 598 599 -----BEGIN CERTIFICATE REQUEST----- 600 -----END CERTIFICATE REQUEST----- 601 602some software (some versions of Netscape certificate server) instead needs: 603 604 -----BEGIN NEW CERTIFICATE REQUEST----- 605 -----END NEW CERTIFICATE REQUEST----- 606 607which is produced with the B<-newhdr> option but is otherwise compatible. 608Either form is accepted transparently on input. 609 610The certificate requests generated by B<Xenroll> with MSIE have extensions 611added. It includes the B<keyUsage> extension which determines the type of 612key (signature only or general purpose) and any additional OIDs entered 613by the script in an extendedKeyUsage extension. 614 615=head1 DIAGNOSTICS 616 617The following messages are frequently asked about: 618 619 Using configuration from /some/path/openssl.cnf 620 Unable to load config info 621 622This is followed some time later by... 623 624 unable to find 'distinguished_name' in config 625 problems making Certificate Request 626 627The first error message is the clue: it can't find the configuration 628file! Certain operations (like examining a certificate request) don't 629need a configuration file so its use isn't enforced. Generation of 630certificates or requests however does need a configuration file. This 631could be regarded as a bug. 632 633Another puzzling message is this: 634 635 Attributes: 636 a0:00 637 638this is displayed when no attributes are present and the request includes 639the correct empty B<SET OF> structure (the DER encoding of which is 0xa0 6400x00). If you just see: 641 642 Attributes: 643 644then the B<SET OF> is missing and the encoding is technically invalid (but 645it is tolerated). See the description of the command line option B<-asn1-kludge> 646for more information. 647 648=head1 ENVIRONMENT VARIABLES 649 650The variable B<OPENSSL_CONF> if defined allows an alternative configuration 651file location to be specified, it will be overridden by the B<-config> command 652line switch if it is present. For compatibility reasons the B<SSLEAY_CONF> 653environment variable serves the same purpose but its use is discouraged. 654 655=head1 BUGS 656 657OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively 658treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. 659This can cause problems if you need characters that aren't available in 660PrintableStrings and you don't want to or can't use BMPStrings. 661 662As a consequence of the T61String handling the only correct way to represent 663accented characters in OpenSSL is to use a BMPString: unfortunately Netscape 664currently chokes on these. If you have to use accented characters with Netscape 665and MSIE then you currently need to use the invalid T61String form. 666 667The current prompting is not very friendly. It doesn't allow you to confirm what 668you've just entered. Other things like extensions in certificate requests are 669statically defined in the configuration file. Some of these: like an email 670address in subjectAltName should be input by the user. 671 672=head1 SEE ALSO 673 674L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, 675L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>, 676L<x509v3_config(5)|x509v3_config(5)> 677 678=cut 679