2 {- OpenSSL::safe::output_do_not_edit_headers(); -}
6 openssl-req - PKCS#10 certificate request and certificate generating utility
12 [B<-inform> B<DER>|B<PEM>]
13 [B<-outform> B<DER>|B<PEM>]
25 [B<-pkeyopt> I<opt>:I<value>]
28 [B<-keyform> B<DER>|B<PEM>]
29 [B<-keyout> I<filename>]
30 [B<-keygen_engine> I<id>]
32 [B<-config> I<filename>]
39 [B<-extensions> I<section>]
40 [B<-reqexts> I<section>]
46 [B<-sigopt> I<nm>:I<v>]
49 [B<-sm2-id> I<string>]
50 [B<-sm2-hex-id> I<hex-string>]
51 {- $OpenSSL::safe::opt_name_synopsis -}
52 {- $OpenSSL::safe::opt_r_synopsis -}
53 {- $OpenSSL::safe::opt_engine_synopsis -}
55 =for openssl ifdef engine keygen_engine sm2-id sm2-hex-id
59 This command primarily creates and processes certificate requests
60 in PKCS#10 format. It can additionally create self signed certificates
61 for use as root CAs for example.
69 Print out a usage message.
71 =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM>
73 The input and formats; the default is B<PEM>.
74 See L<openssl(1)/Format Options> for details.
76 The data is a PKCS#10 object.
78 =item B<-in> I<filename>
80 This specifies the input filename to read a request from or standard input
81 if this option is not specified. A request is only read if the creation
82 options (B<-new> and B<-newkey>) are not specified.
84 =item B<-sigopt> I<nm>:I<v>
86 Pass options to the signature algorithm during sign or verify operations.
87 Names and values of these options are algorithm-specific.
89 =item B<-passin> I<arg>, B<-passout> I<arg>
91 The password source for the input and output file.
92 For more information about the format of B<arg>
93 see L<openssl(1)/Pass Phrase Options>.
95 =item B<-out> I<filename>
97 This specifies the output filename to write to or standard output by
102 Prints out the certificate request in text form.
106 Prints out the request subject (or certificate subject if B<-x509> is
111 Outputs the public key.
115 This option prevents output of the encoded version of the request.
119 This option prints out the value of the modulus of the public key
120 contained in the request.
124 Verifies the signature on the request.
128 This option generates a new certificate request. It will prompt
129 the user for the relevant field values. The actual fields
130 prompted for and their maximum and minimum sizes are specified
131 in the configuration file and any requested extensions.
133 If the B<-key> option is not used it will generate a new RSA private
134 key using information specified in the configuration file.
136 =item B<-newkey> I<arg>
138 This option creates a new certificate request and a new private
139 key. The argument takes one of several forms.
141 B<rsa:>I<nbits>, where
142 I<nbits> is the number of bits, generates an RSA key I<nbits>
143 in size. If I<nbits> is omitted, i.e. B<-newkey> I<rsa> specified,
144 the default key size, specified in the configuration file is used.
146 All other algorithms support the B<-newkey> I<alg>:I<file> form, where file
147 may be an algorithm parameter file, created with C<openssl genpkey -genparam>
148 or an X.509 certificate for a key with appropriate algorithm.
150 B<param:>I<file> generates a key using the parameter file or certificate
151 I<file>, the algorithm is determined by the parameters. I<algname>:I<file>
152 use algorithm I<algname> and parameter file I<file>: the two algorithms must
153 match or an error occurs. I<algname> just uses algorithm I<algname>, and
154 parameters, if necessary should be specified via B<-pkeyopt> parameter.
156 B<dsa:>I<filename> generates a DSA key using the parameters
157 in the file I<filename>. B<ec:>I<filename> generates EC key (usable both with
158 ECDSA or ECDH algorithms), B<gost2001:>I<filename> generates GOST R
159 34.10-2001 key (requires B<gost> engine configured in the configuration
160 file). If just B<gost2001> is specified a parameter set should be
161 specified by B<-pkeyopt> I<paramset:X>
163 =item B<-pkeyopt> I<opt>:I<value>
165 Set the public key algorithm option I<opt> to I<value>. The precise set of
166 options supported depends on the public key algorithm used and its
168 See L<openssl-genpkey(1)/KEY GENERATION OPTIONS> for more details.
170 =item B<-key> I<filename>
172 This specifies the file to read the private key from. It also
173 accepts PKCS#8 format private keys for PEM format files.
175 =item B<-keyform> B<DER>|B<PEM>
177 The format of the private key; the default is B<PEM>.
178 See L<openssl(1)/Format Options> for details.
180 =item B<-keyout> I<filename>
182 This gives the filename to write the newly created private key to.
183 If this option is not specified then the filename present in the
184 configuration file is used.
188 If this option is specified then if a private key is created it
189 will not be encrypted.
193 This specifies the message digest to sign the request.
194 Any digest supported by the OpenSSL B<dgst> command can be used.
195 This overrides the digest algorithm specified in
196 the configuration file.
198 Some public key algorithms may override this choice. For instance, DSA
199 signatures always use SHA1, GOST R 34.10 signatures always use
200 GOST R 34.11-94 (B<-md_gost94>), Ed25519 and Ed448 never use any digest.
202 =item B<-config> I<filename>
204 This allows an alternative configuration file to be specified.
205 Optional; for a description of the default value,
206 see L<openssl(1)/COMMAND SUMMARY>.
208 =item B<-subj> I<arg>
210 Sets subject name for new request or supersedes the subject name
211 when processing a request.
212 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
213 Keyword characters may be escaped by \ (backslash), and whitespace is retained.
214 Empty values are permitted, but the corresponding type will not be included
217 =item B<-multivalue-rdn>
219 This option causes the -subj argument to be interpreted with full
220 support for multivalued RDNs. Example:
222 C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
224 If -multi-rdn is not used then the UID value is C<123456+CN=John Doe>.
228 This option outputs a self signed certificate instead of a certificate
229 request. This is typically used to generate a test certificate or
230 a self signed root CA. The extensions added to the certificate
231 (if any) are specified in the configuration file. Unless specified
232 using the B<-set_serial> option, a large random number will be used for
235 If existing request is specified with the B<-in> option, it is converted
236 to the self signed certificate otherwise new request is created.
240 When the B<-x509> option is being used this specifies the number of
241 days to certify the certificate for, otherwise it is ignored. I<n> should
242 be a positive integer. The default is 30 days.
244 =item B<-set_serial> I<n>
246 Serial number to use when outputting a self signed certificate. This
247 may be specified as a decimal value or a hex value if preceded by C<0x>.
249 =item B<-addext> I<ext>
251 Add a specific extension to the certificate (if the B<-x509> option is
252 present) or certificate request. The argument must have the form of
253 a key=value pair as it would appear in a config file.
255 This option can be given multiple times.
257 =item B<-extensions> I<section>
259 =item B<-reqexts> I<section>
261 These options specify alternative sections to include certificate
262 extensions (if the B<-x509> option is present) or certificate
263 request extensions. This allows several different sections to
264 be used in the same configuration file to specify requests for
265 a variety of purposes.
269 A poison extension will be added to the certificate, making it a
270 "pre-certificate" (see RFC6962). This can be submitted to Certificate
271 Transparency logs in order to obtain signed certificate timestamps (SCTs).
272 These SCTs can then be embedded into the pre-certificate as an extension, before
273 removing the poison and signing the certificate.
275 This implies the B<-new> flag.
279 This option causes field values to be interpreted as UTF8 strings, by
280 default they are interpreted as ASCII. This means that the field
281 values, whether prompted from a terminal or obtained from a
282 configuration file, must be valid UTF8 strings.
284 =item B<-reqopt> I<option>
286 Customise the output format used with B<-text>. The I<option> argument can be
287 a single option or multiple options separated by commas.
289 See discussion of the B<-certopt> parameter in the L<openssl-x509(1)>
294 Adds the word B<NEW> to the PEM file header and footer lines on the outputted
295 request. Some software (Netscape certificate server) and some CAs need this.
299 Non-interactive mode.
303 Print extra details about the operations being performed.
305 =item B<-keygen_engine> I<id>
307 Specifies an engine (by its unique I<id> string) which would be used
308 for key generation operations.
312 Specify the ID string to use when verifying an SM2 certificate request. The ID
313 string is required by the SM2 signature algorithm for signing and verification.
317 Specify a binary ID string to use when verifying an SM2 certificate request. The
318 argument for this option is string of hexadecimal digits.
320 {- $OpenSSL::safe::opt_name_item -}
322 {- $OpenSSL::safe::opt_r_item -}
324 {- $OpenSSL::safe::opt_engine_item -}
328 =head1 CONFIGURATION FILE FORMAT
330 The configuration options are specified in the B<req> section of
331 the configuration file. As with all configuration files if no
332 value is specified in the specific section (i.e. B<req>) then
333 the initial unnamed or B<default> section is searched too.
335 The options available are described in detail below.
339 =item B<input_password output_password>
341 The passwords for the input private key file (if present) and
342 the output private key file (if one will be created). The
343 command line options B<passin> and B<passout> override the
344 configuration file values.
346 =item B<default_bits>
348 Specifies the default key size in bits.
350 This option is used in conjunction with the B<-new> option to generate
351 a new key. It can be overridden by specifying an explicit key size in
352 the B<-newkey> option. The smallest accepted key size is 512 bits. If
353 no key size is specified then 2048 bits is used.
355 =item B<default_keyfile>
357 This is the default filename to write a private key to. If not
358 specified the key is written to standard output. This can be
359 overridden by the B<-keyout> option.
363 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
364 Each line of the file should consist of the numerical form of the
365 object identifier followed by white space then the short name followed
366 by white space and finally the long name.
370 This specifies a section in the configuration file containing extra
371 object identifiers. Each line should consist of the short name of the
372 object identifier followed by B<=> and the numerical form. The short
373 and long names are the same when this option is used.
377 At startup the specified file is loaded into the random number generator,
378 and at exit 256 bytes will be written to it.
379 It is used for private key generation.
383 If this is set to B<no> then if a private key is generated it is
384 B<not> encrypted. This is equivalent to the B<-nodes> command line
385 option. For compatibility B<encrypt_rsa_key> is an equivalent option.
389 This option specifies the digest algorithm to use. Any digest supported by the
390 OpenSSL B<dgst> command can be used. This option can be overridden on the
391 command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore
392 any digest that has been set.
396 This option masks out the use of certain string types in certain
397 fields. Most users will not need to change this option.
399 It can be set to several values B<default> which is also the default
400 option uses PrintableStrings, T61Strings and BMPStrings if the
401 B<pkix> value is used then only PrintableStrings and BMPStrings will
402 be used. This follows the PKIX recommendation in RFC2459. If the
403 B<utf8only> option is used then only UTF8Strings will be used: this
404 is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
405 option just uses PrintableStrings and T61Strings: certain software has
406 problems with BMPStrings and UTF8Strings: in particular Netscape.
408 =item B<req_extensions>
410 This specifies the configuration file section containing a list of
411 extensions to add to the certificate request. It can be overridden
412 by the B<-reqexts> command line switch. See the
413 L<x509v3_config(5)> manual page for details of the
414 extension section format.
416 =item B<x509_extensions>
418 This specifies the configuration file section containing a list of
419 extensions to add to certificate generated when the B<-x509> switch
420 is used. It can be overridden by the B<-extensions> command line switch.
424 If set to the value B<no> this disables prompting of certificate fields
425 and just takes values from the config file directly. It also changes the
426 expected format of the B<distinguished_name> and B<attributes> sections.
430 If set to the value B<yes> then field values to be interpreted as UTF8
431 strings, by default they are interpreted as ASCII. This means that
432 the field values, whether prompted from a terminal or obtained from a
433 configuration file, must be valid UTF8 strings.
437 This specifies the section containing any request attributes: its format
438 is the same as B<distinguished_name>. Typically these may contain the
439 challengePassword or unstructuredName types. They are currently ignored
440 by OpenSSL's request signing utilities but some CAs might want them.
442 =item B<distinguished_name>
444 This specifies the section containing the distinguished name fields to
445 prompt for when generating a certificate or certificate request. The format
446 is described in the next section.
450 =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
452 There are two separate formats for the distinguished name and attribute
453 sections. If the B<prompt> option is set to B<no> then these sections
454 just consist of field names and values: for example,
458 emailAddress=someone@somewhere.org
460 This allows external programs (e.g. GUI based) to generate a template file with
461 all the field names and values and just pass it to this command. An example
462 of this kind of configuration file is contained in the B<EXAMPLES> section.
464 Alternatively if the B<prompt> option is absent or not set to B<no> then the
465 file contains field prompting information. It consists of lines of the form:
468 fieldName_default="default field value"
472 "fieldName" is the field name being used, for example commonName (or CN).
473 The "prompt" string is used to ask the user to enter the relevant
474 details. If the user enters nothing then the default value is used if no
475 default value is present then the field is omitted. A field can
476 still be omitted if a default value is present if the user just
477 enters the '.' character.
479 The number of characters entered must be between the fieldName_min and
480 fieldName_max limits: there may be additional restrictions based
481 on the field being used (for example countryName can only ever be
482 two characters long and must fit in a PrintableString).
484 Some fields (such as organizationName) can be used more than once
485 in a DN. This presents a problem because configuration files will
486 not recognize the same name occurring twice. To avoid this problem
487 if the fieldName contains some characters followed by a full stop
488 they will be ignored. So for example a second organizationName can
489 be input by calling it "1.organizationName".
491 The actual permitted field names are any object identifier short or
492 long names. These are compiled into OpenSSL and include the usual
493 values such as commonName, countryName, localityName, organizationName,
494 organizationalUnitName, stateOrProvinceName. Additionally emailAddress
495 is included as well as name, surname, givenName, initials, and dnQualifier.
497 Additional object identifiers can be defined with the B<oid_file> or
498 B<oid_section> options in the configuration file. Any additional fields
499 will be treated as though they were a DirectoryString.
504 Examine and verify certificate request:
506 openssl req -in req.pem -text -verify -noout
508 Create a private key and then generate a certificate request from it:
510 openssl genrsa -out key.pem 2048
511 openssl req -new -key key.pem -out req.pem
513 The same but just using req:
515 openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
517 Generate a self signed root certificate:
519 openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
521 Create an SM2 private key and then generate a certificate request from it:
523 openssl ecparam -genkey -name SM2 -out sm2.key
524 openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt "sm2_id:1234567812345678"
526 Examine and verify an SM2 certificate request:
528 openssl req -verify -in sm2.csr -sm3 -sm2-id 1234567812345678
530 Example of a file pointed to by the B<oid_file> option:
532 1.2.3.4 shortName A longer Name
533 1.2.3.6 otherName Other longer Name
535 Example of a section pointed to by B<oid_section> making use of variable
539 testoid2=${testoid1}.6
541 Sample configuration file prompting for field values:
545 default_keyfile = privkey.pem
546 distinguished_name = req_distinguished_name
547 attributes = req_attributes
548 req_extensions = v3_ca
550 dirstring_type = nobmp
552 [ req_distinguished_name ]
553 countryName = Country Name (2 letter code)
554 countryName_default = AU
558 localityName = Locality Name (eg, city)
560 organizationalUnitName = Organizational Unit Name (eg, section)
562 commonName = Common Name (eg, YOUR name)
565 emailAddress = Email Address
566 emailAddress_max = 40
569 challengePassword = A challenge password
570 challengePassword_min = 4
571 challengePassword_max = 20
575 subjectKeyIdentifier=hash
576 authorityKeyIdentifier=keyid:always,issuer:always
577 basicConstraints = critical, CA:true
579 Sample configuration containing all field values:
584 default_keyfile = keyfile.pem
585 distinguished_name = req_distinguished_name
586 attributes = req_attributes
588 output_password = mypass
590 [ req_distinguished_name ]
592 ST = Test State or Province
594 O = Organization Name
595 OU = Organizational Unit Name
597 emailAddress = test@email.address
600 challengePassword = A challenge password
602 Example of giving the most common attributes (subject and extensions)
605 openssl req -new -subj "/C=GB/CN=foo" \
606 -addext "subjectAltName = DNS:foo.co.uk" \
607 -addext "certificatePolicies = 1.2.3.4" \
608 -newkey rsa:2048 -keyout key.pem -out req.pem
613 The certificate requests generated by B<Xenroll> with MSIE have extensions
614 added. It includes the B<keyUsage> extension which determines the type of
615 key (signature only or general purpose) and any additional OIDs entered
616 by the script in an B<extendedKeyUsage> extension.
620 The following messages are frequently asked about:
622 Using configuration from /some/path/openssl.cnf
623 Unable to load config info
625 This is followed some time later by:
627 unable to find 'distinguished_name' in config
628 problems making Certificate Request
630 The first error message is the clue: it can't find the configuration
631 file! Certain operations (like examining a certificate request) don't
632 need a configuration file so its use isn't enforced. Generation of
633 certificates or requests however does need a configuration file. This
634 could be regarded as a bug.
636 Another puzzling message is this:
641 this is displayed when no attributes are present and the request includes
642 the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
643 0x00). If you just see:
647 then the B<SET OF> is missing and the encoding is technically invalid (but
648 it is tolerated). See the description of the command line option B<-asn1-kludge>
649 for more information.
653 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
654 treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
655 This can cause problems if you need characters that aren't available in
656 PrintableStrings and you don't want to or can't use BMPStrings.
658 As a consequence of the T61String handling the only correct way to represent
659 accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
660 currently chokes on these. If you have to use accented characters with Netscape
661 and MSIE then you currently need to use the invalid T61String form.
663 The current prompting is not very friendly. It doesn't allow you to confirm what
664 you've just entered. Other things like extensions in certificate requests are
665 statically defined in the configuration file. Some of these: like an email
666 address in subjectAltName should be input by the user.
673 L<openssl-genrsa(1)>,
674 L<openssl-gendsa(1)>,
680 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
682 Licensed under the Apache License 2.0 (the "License"). You may not use
683 this file except in compliance with the License. You can obtain a copy
684 in the file LICENSE in the source distribution or at
685 L<https://www.openssl.org/source/license.html>.