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