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