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