req.pod revision 325335
1296633Sdes 2261287Sdes=pod 3261287Sdes 4261287Sdes=head1 NAME 5261287Sdes 6261287Sdesreq - PKCS#10 certificate request and certificate generating utility. 7261287Sdes 8261287Sdes=head1 SYNOPSIS 9261287Sdes 10261287SdesB<openssl> B<req> 11261287Sdes[B<-inform PEM|DER>] 12261287Sdes[B<-outform PEM|DER>] 13261287Sdes[B<-in filename>] 14261287Sdes[B<-passin arg>] 15261287Sdes[B<-out filename>] 16261287Sdes[B<-passout arg>] 17261287Sdes[B<-text>] 18261287Sdes[B<-pubkey>] 19261287Sdes[B<-noout>] 20261287Sdes[B<-verify>] 21261287Sdes[B<-modulus>] 22261287Sdes[B<-new>] 23261287Sdes[B<-rand file(s)>] 24261287Sdes[B<-newkey rsa:bits>] 25261287Sdes[B<-newkey alg:file>] 26261287Sdes[B<-nodes>] 27261287Sdes[B<-key filename>] 28261287Sdes[B<-keyform PEM|DER>] 29261287Sdes[B<-keyout filename>] 30294336Sdes[B<-keygen_engine id>] 31261287Sdes[B<-[digest]>] 32261287Sdes[B<-config filename>] 33261287Sdes[B<-multivalue-rdn>] 34294332Sdes[B<-x509>] 35261287Sdes[B<-days n>] 36294332Sdes[B<-set_serial n>] 37261287Sdes[B<-asn1-kludge>] 38261287Sdes[B<-no-asn1-kludge>] 39261287Sdes[B<-newhdr>] 40261287Sdes[B<-extensions section>] 41294332Sdes[B<-reqexts section>] 42294332Sdes[B<-utf8>] 43261287Sdes[B<-nameopt>] 44294332Sdes[B<-reqopt>] 45294332Sdes[B<-subject>] 46294332Sdes[B<-subj arg>] 47294332Sdes[B<-batch>] 48261287Sdes[B<-verbose>] 49294332Sdes[B<-engine id>] 50294332Sdes 51294332Sdes=head1 DESCRIPTION 52294332Sdes 53294332SdesThe B<req> command primarily creates and processes certificate requests 54294332Sdesin PKCS#10 format. It can additionally create self signed certificates 55294332Sdesfor use as root CAs for example. 56294332Sdes 57294332Sdes=head1 COMMAND OPTIONS 58294332Sdes 59294332Sdes=over 4 60294332Sdes 61261287Sdes=item B<-inform DER|PEM> 62261287Sdes 63261287SdesThis specifies the input format. The B<DER> option uses an ASN1 DER encoded 64261287Sdesform compatible with the PKCS#10. The B<PEM> form is the default format: it 65294332Sdesconsists of the B<DER> format base64 encoded with additional header and 66294332Sdesfooter lines. 67294332Sdes 68261287Sdes=item B<-outform DER|PEM> 69261287Sdes 70261287SdesThis specifies the output format, the options have the same meaning as the 71261287SdesB<-inform> option. 72261287Sdes 73261287Sdes=item B<-in filename> 74261287Sdes 75294332SdesThis specifies the input filename to read a request from or standard input 76294332Sdesif this option is not specified. A request is only read if the creation 77294332Sdesoptions (B<-new> and B<-newkey>) are not specified. 78294332Sdes 79294332Sdes=item B<-passin arg> 80294332Sdes 81294332Sdesthe input file password source. For more information about the format of B<arg> 82294332Sdessee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 83294332Sdes 84294332Sdes=item B<-out filename> 85294332Sdes 86294332SdesThis specifies the output filename to write to or standard output by 87261287Sdesdefault. 88294332Sdes 89294332Sdes=item B<-passout arg> 90294332Sdes 91294332Sdesthe output file password source. For more information about the format of B<arg> 92294332Sdessee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 93294332Sdes 94294332Sdes=item B<-text> 95261287Sdes 96261287Sdesprints out the certificate request in text form. 97261287Sdes 98261287Sdes=item B<-subject> 99294332Sdes 100294332Sdesprints out the request subject (or certificate subject if B<-x509> is 101294332Sdesspecified) 102294332Sdes 103294332Sdes=item B<-pubkey> 104294332Sdes 105294332Sdesoutputs the public key. 106261287Sdes 107261287Sdes=item B<-noout> 108294332Sdes 109294332Sdesthis option prevents output of the encoded version of the request. 110294332Sdes 111294332Sdes=item B<-modulus> 112294332Sdes 113261287Sdesthis option prints out the value of the modulus of the public key 114261287Sdescontained in the request. 115261287Sdes 116294332Sdes=item B<-verify> 117294332Sdes 118261287Sdesverifies the signature on the request. 119261287Sdes 120261287Sdes=item B<-new> 121294332Sdes 122294332Sdesthis option generates a new certificate request. It will prompt 123294332Sdesthe user for the relevant field values. The actual fields 124261287Sdesprompted for and their maximum and minimum sizes are specified 125261287Sdesin the configuration file and any requested extensions. 126261287Sdes 127261287SdesIf the B<-key> option is not used it will generate a new RSA private 128294332Sdeskey using information specified in the configuration file. 129294332Sdes 130294332Sdes=item B<-subj arg> 131294332Sdes 132294332SdesReplaces subject field of input request with specified data and outputs 133261287Sdesmodified request. The arg must be formatted as 134261287SdesI</type0=value0/type1=value1/type2=...>, 135261287Sdescharacters may be escaped by \ (backslash), no spaces are skipped. 136261287Sdes 137296633Sdes=item B<-rand file(s)> 138296633Sdes 139294332Sdesa file or files containing random data used to seed the random number 140261287Sdesgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 141261287SdesMultiple files can be specified separated by a OS-dependent character. 142294332SdesThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 143294332Sdesall others. 144294332Sdes 145294332Sdes=item B<-newkey arg> 146294332Sdes 147294332Sdesthis option creates a new certificate request and a new private 148261287Sdeskey. The argument takes one of several forms. B<rsa:nbits>, where 149294332SdesB<nbits> is the number of bits, generates an RSA key B<nbits> 150294332Sdesin size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified, 151294332Sdesthe default key size, specified in the configuration file is used. 152294332Sdes 153294332SdesAll other algorithms support the B<-newkey alg:file> form, where file may be 154294332Sdesan algorithm parameter file, created by the B<genpkey -genparam> command 155261287Sdesor and X.509 certificate for a key with approriate algorithm. 156261287Sdes 157294332SdesB<param:file> generates a key using the parameter file or certificate B<file>, 158294332Sdesthe algorithm is determined by the parameters. B<algname:file> use algorithm 159261287SdesB<algname> and parameter file B<file>: the two algorithms must match or an 160error occurs. B<algname> just uses algorithm B<algname>, and parameters, 161if neccessary should be specified via B<-pkeyopt> parameter. 162 163B<dsa:filename> generates a DSA key using the parameters 164in the file B<filename>. B<ec:filename> generates EC key (usable both with 165ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R 16634.10-2001 key (requires B<ccgost> engine configured in the configuration 167file). If just B<gost2001> is specified a parameter set should be 168specified by B<-pkeyopt paramset:X> 169 170 171=item B<-pkeyopt opt:value> 172 173set the public key algorithm option B<opt> to B<value>. The precise set of 174options supported depends on the public key algorithm used and its 175implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page 176for more details. 177 178=item B<-key filename> 179 180This specifies the file to read the private key from. It also 181accepts PKCS#8 format private keys for PEM format files. 182 183=item B<-keyform PEM|DER> 184 185the format of the private key file specified in the B<-key> 186argument. PEM is the default. 187 188=item B<-keyout filename> 189 190this gives the filename to write the newly created private key to. 191If this option is not specified then the filename present in the 192configuration file is used. 193 194=item B<-nodes> 195 196if this option is specified then if a private key is created it 197will not be encrypted. 198 199=item B<-[digest]> 200 201this specifies the message digest to sign the request with (such as 202B<-md5>, B<-sha1>). This overrides the digest algorithm specified in 203the configuration file. 204 205Some public key algorithms may override this choice. For instance, DSA 206signatures always use SHA1, GOST R 34.10 signatures always use 207GOST R 34.11-94 (B<-md_gost94>). 208 209=item B<-config filename> 210 211this allows an alternative configuration file to be specified, 212this overrides the compile time filename or any specified in 213the B<OPENSSL_CONF> environment variable. 214 215=item B<-subj arg> 216 217sets subject name for new request or supersedes the subject name 218when processing a request. 219The arg must be formatted as I</type0=value0/type1=value1/type2=...>, 220characters may be escaped by \ (backslash), no spaces are skipped. 221 222=item B<-multivalue-rdn> 223 224this option causes the -subj argument to be interpreted with full 225support for multivalued RDNs. Example: 226 227I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> 228 229If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>. 230 231=item B<-x509> 232 233this option outputs a self signed certificate instead of a certificate 234request. This is typically used to generate a test certificate or 235a self signed root CA. The extensions added to the certificate 236(if any) are specified in the configuration file. Unless specified 237using the B<set_serial> option, a large random number will be used for 238the serial number. 239 240If existing request is specified with the B<-in> option, it is converted 241to the self signed certificate otherwise new request is created. 242 243=item B<-days n> 244 245when the B<-x509> option is being used this specifies the number of 246days to certify the certificate for. The default is 30 days. 247 248=item B<-set_serial n> 249 250serial number to use when outputting a self signed certificate. This 251may be specified as a decimal value or a hex value if preceded by B<0x>. 252It is possible to use negative serial numbers but this is not recommended. 253 254=item B<-extensions section> 255 256=item B<-reqexts section> 257 258these options specify alternative sections to include certificate 259extensions (if the B<-x509> option is present) or certificate 260request extensions. This allows several different sections to 261be used in the same configuration file to specify requests for 262a variety of purposes. 263 264=item B<-utf8> 265 266this option causes field values to be interpreted as UTF8 strings, by 267default they are interpreted as ASCII. This means that the field 268values, whether prompted from a terminal or obtained from a 269configuration file, must be valid UTF8 strings. 270 271=item B<-nameopt option> 272 273option which determines how the subject or issuer names are displayed. The 274B<option> argument can be a single option or multiple options separated by 275commas. Alternatively the B<-nameopt> switch may be used more than once to 276set multiple options. See the L<x509(1)|x509(1)> manual page for details. 277 278=item B<-reqopt> 279 280customise the output format used with B<-text>. The B<option> argument can be 281a single option or multiple options separated by commas. 282 283See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)> 284command. 285 286 287=item B<-asn1-kludge> 288 289by default the B<req> command outputs certificate requests containing 290no attributes in the correct PKCS#10 format. However certain CAs will only 291accept requests containing no attributes in an invalid form: this 292option produces this invalid format. 293 294More precisely the B<Attributes> in a PKCS#10 certificate request 295are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so 296if no attributes are present then they should be encoded as an 297empty B<SET OF>. The invalid form does not include the empty 298B<SET OF> whereas the correct form does. 299 300It should be noted that very few CAs still require the use of this option. 301 302=item B<-no-asn1-kludge> 303 304Reverses effect of B<-asn1-kludge> 305 306=item B<-newhdr> 307 308Adds the word B<NEW> to the PEM file header and footer lines on the outputted 309request. Some software (Netscape certificate server) and some CAs need this. 310 311=item B<-batch> 312 313non-interactive mode. 314 315=item B<-verbose> 316 317print extra details about the operations being performed. 318 319=item B<-engine id> 320 321specifying an engine (by its unique B<id> string) will cause B<req> 322to attempt to obtain a functional reference to the specified engine, 323thus initialising it if needed. The engine will then be set as the default 324for all available algorithms. 325 326=item B<-keygen_engine id> 327 328specifies an engine (by its unique B<id> string) which would be used 329for key generation operations. 330 331=back 332 333=head1 CONFIGURATION FILE FORMAT 334 335The configuration options are specified in the B<req> section of 336the configuration file. As with all configuration files if no 337value is specified in the specific section (i.e. B<req>) then 338the initial unnamed or B<default> section is searched too. 339 340The options available are described in detail below. 341 342=over 4 343 344=item B<input_password output_password> 345 346The passwords for the input private key file (if present) and 347the output private key file (if one will be created). The 348command line options B<passin> and B<passout> override the 349configuration file values. 350 351=item B<default_bits> 352 353Specifies the default key size in bits. 354 355This option is used in conjunction with the B<-new> option to generate 356a new key. It can be overridden by specifying an explicit key size in 357the B<-newkey> option. The smallest accepted key size is 512 bits. If 358no key size is specified then 2048 bits is used. 359 360=item B<default_keyfile> 361 362This is the default filename to write a private key to. If not 363specified the key is written to standard output. This can be 364overridden by the B<-keyout> option. 365 366=item B<oid_file> 367 368This specifies a file containing additional B<OBJECT IDENTIFIERS>. 369Each line of the file should consist of the numerical form of the 370object identifier followed by white space then the short name followed 371by white space and finally the long name. 372 373=item B<oid_section> 374 375This specifies a section in the configuration file containing extra 376object identifiers. Each line should consist of the short name of the 377object identifier followed by B<=> and the numerical form. The short 378and long names are the same when this option is used. 379 380=item B<RANDFILE> 381 382This specifies a filename in which random number seed information is 383placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 384It is used for private key generation. 385 386=item B<encrypt_key> 387 388If this is set to B<no> then if a private key is generated it is 389B<not> encrypted. This is equivalent to the B<-nodes> command line 390option. For compatibility B<encrypt_rsa_key> is an equivalent option. 391 392=item B<default_md> 393 394This option specifies the digest algorithm to use. Possible values 395include B<md5 sha1 mdc2>. If not present then MD5 is used. This 396option 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