2 {- OpenSSL::safe::output_do_not_edit_headers(); -}
6 openssl-req - PKCS#10 certificate request and certificate generating command
12 [B<-inform> B<DER>|B<PEM>]
13 [B<-outform> B<DER>|B<PEM>]
25 [B<-pkeyopt> I<opt>:I<value>]
28 [B<-key> I<filename>|I<uri>]
29 [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
30 [B<-keyout> I<filename>]
31 [B<-keygen_engine> I<id>]
33 [B<-config> I<filename>]
37 [B<-CA> I<filename>|I<uri>]
38 [B<-CAkey> I<filename>|I<uri>]
42 [B<-copy_extensions> I<arg>]
43 [B<-extensions> I<section>]
44 [B<-reqexts> I<section>]
52 [B<-sigopt> I<nm>:I<v>]
53 [B<-vfyopt> I<nm>:I<v>]
57 {- $OpenSSL::safe::opt_name_synopsis -}
58 {- $OpenSSL::safe::opt_r_synopsis -}
59 {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
63 This command primarily creates and processes certificate requests (CSRs)
64 in PKCS#10 format. It can additionally create self-signed certificates
65 for use as root CAs for example.
73 Print out a usage message.
75 =item B<-inform> B<DER>|B<PEM>
77 The CSR input file format to use; by default PEM is tried first.
78 See L<openssl-format-options(1)> for details.
80 =item B<-outform> B<DER>|B<PEM>
82 The output format; unspecified by default.
83 See L<openssl-format-options(1)> for details.
85 The data is a PKCS#10 object.
87 =item B<-in> I<filename>
89 This specifies the input filename to read a request from.
90 This defaults to standard input unless B<-x509> or B<-CA> is specified.
91 A request is only read if the creation options
92 (B<-new> or B<-newkey> or B<-precert>) are not specified.
94 =item B<-sigopt> I<nm>:I<v>
96 Pass options to the signature algorithm during sign operations.
97 Names and values of these options are algorithm-specific.
99 =item B<-vfyopt> I<nm>:I<v>
101 Pass options to the signature algorithm during verify operations.
102 Names and values of these options are algorithm-specific.
106 Maybe it would be preferable to only have -opts instead of -sigopt and
107 -vfyopt? They are both present here to be compatible with L<openssl-ca(1)>,
108 which supports both options for good reasons.
112 =item B<-passin> I<arg>
114 The password source for private key and certificate input.
115 For more information about the format of B<arg>
116 see L<openssl-passphrase-options(1)>.
118 =item B<-passout> I<arg>
120 The password source for the output file.
121 For more information about the format of B<arg>
122 see L<openssl-passphrase-options(1)>.
124 =item B<-out> I<filename>
126 This specifies the output filename to write to or standard output by default.
130 Prints out the certificate request in text form.
134 Prints out the certificate request subject
135 (or certificate subject if B<-x509> is in use).
139 Prints out the public key.
143 This option prevents output of the encoded version of the certificate request.
147 Prints out the value of the modulus of the public key contained in the request.
151 Verifies the self-signature on the request.
155 This option generates a new certificate request. It will prompt
156 the user for the relevant field values. The actual fields
157 prompted for and their maximum and minimum sizes are specified
158 in the configuration file and any requested extensions.
160 If the B<-key> option is not given it will generate a new private key
161 using information specified in the configuration file or given with
162 the B<-newkey> and B<-pkeyopt> options,
163 else by default an RSA key with 2048 bits length.
165 =item B<-newkey> I<arg>
167 This option is used to generate a new private key unless B<-key> is given.
168 It is subsequently used as if it was given using the B<-key> option.
170 This option implies the B<-new> flag to create a new certificate request
171 or a new certificate in case B<-x509> is used.
173 The argument takes one of several forms.
175 [B<rsa:>]I<nbits> generates an RSA key I<nbits> in size.
176 If I<nbits> is omitted, i.e., B<-newkey> B<rsa> is specified,
177 the default key size specified in the configuration file
178 with the B<default_bits> option is used if present, else 2048.
180 All other algorithms support the B<-newkey> I<algname>:I<file> form, where
181 I<file> is an algorithm parameter file, created with C<openssl genpkey -genparam>
182 or an X.509 certificate for a key with appropriate algorithm.
184 B<param:>I<file> generates a key using the parameter file or certificate
185 I<file>, the algorithm is determined by the parameters.
187 I<algname>[:I<file>] generates a key using the given algorithm I<algname>.
188 If a parameter file I<file> is given then the parameters specified there
189 are used, where the algorithm parameters must match I<algname>.
190 If algorithm parameters are not given,
191 any necessary parameters should be specified via the B<-pkeyopt> option.
193 B<dsa:>I<filename> generates a DSA key using the parameters
194 in the file I<filename>. B<ec:>I<filename> generates EC key (usable both with
195 ECDSA or ECDH algorithms), B<gost2001:>I<filename> generates GOST R
196 34.10-2001 key (requires B<gost> engine configured in the configuration
197 file). If just B<gost2001> is specified a parameter set should be
198 specified by B<-pkeyopt> I<paramset:X>
200 =item B<-pkeyopt> I<opt>:I<value>
202 Set the public key algorithm option I<opt> to I<value>. The precise set of
203 options supported depends on the public key algorithm used and its
205 See L<openssl-genpkey(1)/KEY GENERATION OPTIONS> for more details.
207 =item B<-key> I<filename>|I<uri>
209 This option provides the private key for signing a new certificate or
211 Unless B<-in> is given, the corresponding public key is placed in
212 the new certificate or certificate request, resulting in a self-signature.
214 For certificate signing this option is overridden by the B<-CA> option.
216 This option also accepts PKCS#8 format private keys for PEM format files.
218 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
220 The format of the private key; unspecified by default.
221 See L<openssl-format-options(1)> for details.
223 =item B<-keyout> I<filename>
225 This gives the filename to write any private key to that has been newly created
226 or read from B<-key>. If neither the B<-keyout> option nor the B<-key> option
227 are given then the filename specified in the configuration file with the
228 B<default_keyfile> option is used, if present. Thus, if you want to write the
229 private key and the B<-key> option is provided, you should provide the
230 B<-keyout> option explicitly. If a new key is generated and no filename is
231 specified the key is written to standard output.
235 If this option is specified then if a private key is created it
236 will not be encrypted.
240 This option is deprecated since OpenSSL 3.0; use B<-noenc> instead.
244 This specifies the message digest to sign the request.
245 Any digest supported by the OpenSSL B<dgst> command can be used.
246 This overrides the digest algorithm specified in
247 the configuration file.
249 Some public key algorithms may override this choice. For instance, DSA
250 signatures always use SHA1, GOST R 34.10 signatures always use
251 GOST R 34.11-94 (B<-md_gost94>), Ed25519 and Ed448 never use any digest.
253 =item B<-config> I<filename>
255 This allows an alternative configuration file to be specified.
256 Optional; for a description of the default value,
257 see L<openssl(1)/COMMAND SUMMARY>.
259 =item B<-section> I<name>
261 Specifies the name of the section to use; the default is B<req>.
263 =item B<-subj> I<arg>
265 Sets subject name for new request or supersedes the subject name
266 when processing a certificate request.
268 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
269 Special characters may be escaped by C<\> (backslash), whitespace is retained.
270 Empty values are permitted, but the corresponding type will not be included
272 Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
273 Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
274 between the AttributeValueAssertions (AVAs) that specify the members of the set.
277 C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
279 =item B<-multivalue-rdn>
281 This option has been deprecated and has no effect.
285 This option outputs a certificate instead of a certificate request.
286 This is typically used to generate test certificates.
287 It is implied by the B<-CA> option.
289 This option implies the B<-new> flag if B<-in> is not given.
291 If an existing request is specified with the B<-in> option, it is converted
292 to the a certificate; otherwise a request is created from scratch.
294 Unless specified using the B<-set_serial> option,
295 a large random number will be used for the serial number.
297 Unless the B<-copy_extensions> option is used,
298 X.509 extensions are not copied from any provided request input file.
300 X.509 extensions to be added can be specified in the configuration file,
301 possibly using the B<-config> and B<-extensions> options,
302 and/or using the B<-addext> option.
304 Unless B<-x509v1> is given, generated certificates bear X.509 version 3.
305 Unless specified otherwise,
306 key identifier extensions are included as described in L<x509v3_config(5)>.
310 Request generation of certificates with X.509 version 1.
311 This implies B<-x509>.
312 If X.509 extensions are given, anyway X.509 version 3 is set.
314 =item B<-CA> I<filename>|I<uri>
316 Specifies the "CA" certificate to be used for signing a new certificate
317 and implies use of B<-x509>.
318 When present, this behaves like a "micro CA" as follows:
319 The subject name of the "CA" certificate is placed as issuer name in the new
320 certificate, which is then signed using the "CA" key given as specified below.
322 =item B<-CAkey> I<filename>|I<uri>
324 Sets the "CA" private key to sign a certificate with.
325 The private key must match the public key of the certificate given with B<-CA>.
326 If this option is not provided then the key must be present in the B<-CA> input.
330 When B<-x509> is in use this specifies the number of
331 days to certify the certificate for, otherwise it is ignored. I<n> should
332 be a positive integer. The default is 30 days.
334 =item B<-set_serial> I<n>
336 Serial number to use when outputting a self-signed certificate.
337 This may be specified as a decimal value or a hex value if preceded by C<0x>.
338 If not given, a large random number will be used.
340 =item B<-copy_extensions> I<arg>
342 Determines how X.509 extensions in certificate requests should be handled
343 when B<-x509> is in use.
344 If I<arg> is B<none> or this option is not present then extensions are ignored.
345 If I<arg> is B<copy> or B<copyall> then
346 all extensions in the request are copied to the certificate.
348 The main use of this option is to allow a certificate request to supply
349 values for certain extensions such as subjectAltName.
351 =item B<-extensions> I<section>,
352 B<-reqexts> I<section>
354 Can be used to override the name of the configuration file section
355 from which X.509 extensions are included
356 in the certificate (when B<-x509> is in use) or certificate request.
357 This allows several different sections to be used in the same configuration
358 file to specify requests for a variety of purposes.
360 =item B<-addext> I<ext>
362 Add a specific extension to the certificate (if B<-x509> is in use)
363 or certificate request. The argument must have the form of
364 a C<key=value> pair as it would appear in a config file.
366 This option can be given multiple times.
370 A poison extension will be added to the certificate, making it a
371 "pre-certificate" (see RFC6962). This can be submitted to Certificate
372 Transparency logs in order to obtain signed certificate timestamps (SCTs).
373 These SCTs can then be embedded into the pre-certificate as an extension, before
374 removing the poison and signing the certificate.
376 This implies the B<-new> flag.
380 This option causes field values to be interpreted as UTF8 strings, by
381 default they are interpreted as ASCII. This means that the field
382 values, whether prompted from a terminal or obtained from a
383 configuration file, must be valid UTF8 strings.
385 =item B<-reqopt> I<option>
387 Customise the printing format used with B<-text>. The I<option> argument can be
388 a single option or multiple options separated by commas.
390 See discussion of the B<-certopt> parameter in the L<openssl-x509(1)>
395 Adds the word B<NEW> to the PEM file header and footer lines on the outputted
396 request. Some software (Netscape certificate server) and some CAs need this.
400 Non-interactive mode.
404 Print extra details about the operations being performed.
408 Print fewer details about the operations being performed, which may be
409 handy during batch scripts or pipelines (specifically "progress dots"
410 during key generation are suppressed).
412 =item B<-keygen_engine> I<id>
414 Specifies an engine (by its unique I<id> string) which would be used
415 for key generation operations.
417 {- $OpenSSL::safe::opt_name_item -}
419 {- $OpenSSL::safe::opt_r_item -}
421 {- $OpenSSL::safe::opt_engine_item -}
423 {- $OpenSSL::safe::opt_provider_item -}
427 =head1 CONFIGURATION FILE FORMAT
429 The configuration options are specified in the B<req> section of
430 the configuration file. An alternate name be specified by using the
432 As with all configuration files, if no
433 value is specified in the specific section then
434 the initial unnamed or B<default> section is searched too.
436 The options available are described in detail below.
440 =item B<input_password>, B<output_password>
442 The passwords for the input private key file (if present) and
443 the output private key file (if one will be created). The
444 command line options B<passin> and B<passout> override the
445 configuration file values.
447 =item B<default_bits>
449 Specifies the default key size in bits.
451 This option is used in conjunction with the B<-new> option to generate
452 a new key. It can be overridden by specifying an explicit key size in
453 the B<-newkey> option. The smallest accepted key size is 512 bits. If
454 no key size is specified then 2048 bits is used.
456 =item B<default_keyfile>
458 This is the default filename to write a private key to. If not
459 specified the key is written to standard output. This can be
460 overridden by the B<-keyout> option.
464 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
465 Each line of the file should consist of the numerical form of the
466 object identifier followed by whitespace then the short name followed
467 by whitespace and finally the long name.
471 This specifies a section in the configuration file containing extra
472 object identifiers. Each line should consist of the short name of the
473 object identifier followed by B<=> and the numerical form. The short
474 and long names are the same when this option is used.
478 At startup the specified file is loaded into the random number generator,
479 and at exit 256 bytes will be written to it.
480 It is used for private key generation.
484 If this is set to B<no> then if a private key is generated it is
485 B<not> encrypted. This is equivalent to the B<-noenc> command line
486 option. For compatibility B<encrypt_rsa_key> is an equivalent option.
490 This option specifies the digest algorithm to use. Any digest supported by the
491 OpenSSL B<dgst> command can be used. This option can be overridden on the
492 command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore
493 any digest that has been set.
497 This option masks out the use of certain string types in certain
498 fields. Most users will not need to change this option.
500 It can be set to several values B<default> which is also the default
501 option uses PrintableStrings, T61Strings and BMPStrings if the
502 B<pkix> value is used then only PrintableStrings and BMPStrings will
503 be used. This follows the PKIX recommendation in RFC2459. If the
504 B<utf8only> option is used then only UTF8Strings will be used: this
505 is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
506 option just uses PrintableStrings and T61Strings: certain software has
507 problems with BMPStrings and UTF8Strings: in particular Netscape.
509 =item B<req_extensions>
511 This specifies the configuration file section containing a list of
512 extensions to add to the certificate request. It can be overridden
513 by the B<-reqexts> command line switch. See the
514 L<x509v3_config(5)> manual page for details of the
515 extension section format.
517 =item B<x509_extensions>
519 This specifies the configuration file section containing a list of
520 extensions to add to certificate generated when B<-x509> is in use.
521 It can be overridden by the B<-extensions> command line switch.
525 If set to the value B<no> this disables prompting of certificate fields
526 and just takes values from the config file directly. It also changes the
527 expected format of the B<distinguished_name> and B<attributes> sections.
531 If set to the value B<yes> then field values to be interpreted as UTF8
532 strings, by default they are interpreted as ASCII. This means that
533 the field values, whether prompted from a terminal or obtained from a
534 configuration file, must be valid UTF8 strings.
538 This specifies the section containing any request attributes: its format
539 is the same as B<distinguished_name>. Typically these may contain the
540 challengePassword or unstructuredName types. They are currently ignored
541 by OpenSSL's request signing utilities but some CAs might want them.
543 =item B<distinguished_name>
545 This specifies the section containing the distinguished name fields to
546 prompt for when generating a certificate or certificate request. The format
547 is described in the next section.
551 =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
553 There are two separate formats for the distinguished name and attribute
554 sections. If the B<prompt> option is set to B<no> then these sections
555 just consist of field names and values: for example,
559 emailAddress=someone@somewhere.org
561 This allows external programs (e.g. GUI based) to generate a template file with
562 all the field names and values and just pass it to this command. An example
563 of this kind of configuration file is contained in the B<EXAMPLES> section.
565 Alternatively if the B<prompt> option is absent or not set to B<no> then the
566 file contains field prompting information. It consists of lines of the form:
569 fieldName_default="default field value"
573 "fieldName" is the field name being used, for example commonName (or CN).
574 The "prompt" string is used to ask the user to enter the relevant
575 details. If the user enters nothing then the default value is used if no
576 default value is present then the field is omitted. A field can
577 still be omitted if a default value is present if the user just
578 enters the '.' character.
580 The number of characters entered must be between the fieldName_min and
581 fieldName_max limits: there may be additional restrictions based
582 on the field being used (for example countryName can only ever be
583 two characters long and must fit in a PrintableString).
585 Some fields (such as organizationName) can be used more than once
586 in a DN. This presents a problem because configuration files will
587 not recognize the same name occurring twice. To avoid this problem
588 if the fieldName contains some characters followed by a full stop
589 they will be ignored. So for example a second organizationName can
590 be input by calling it "1.organizationName".
592 The actual permitted field names are any object identifier short or
593 long names. These are compiled into OpenSSL and include the usual
594 values such as commonName, countryName, localityName, organizationName,
595 organizationalUnitName, stateOrProvinceName. Additionally emailAddress
596 is included as well as name, surname, givenName, initials, and dnQualifier.
598 Additional object identifiers can be defined with the B<oid_file> or
599 B<oid_section> options in the configuration file. Any additional fields
600 will be treated as though they were a DirectoryString.
605 Examine and verify certificate request:
607 openssl req -in req.pem -text -verify -noout
609 Create a private key and then generate a certificate request from it:
611 openssl genrsa -out key.pem 2048
612 openssl req -new -key key.pem -out req.pem
614 The same but just using req:
616 openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
618 Generate a self-signed root certificate:
620 openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
622 Create an SM2 private key and then generate a certificate request from it:
624 openssl ecparam -genkey -name SM2 -out sm2.key
625 openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt "distid:1234567812345678"
627 Examine and verify an SM2 certificate request:
629 openssl req -verify -in sm2.csr -sm3 -vfyopt "distid:1234567812345678"
631 Example of a file pointed to by the B<oid_file> option:
633 1.2.3.4 shortName A longer Name
634 1.2.3.6 otherName Other longer Name
636 Example of a section pointed to by B<oid_section> making use of variable
640 testoid2=${testoid1}.6
642 Sample configuration file prompting for field values:
646 default_keyfile = privkey.pem
647 distinguished_name = req_distinguished_name
648 attributes = req_attributes
649 req_extensions = v3_ca
651 dirstring_type = nobmp
653 [ req_distinguished_name ]
654 countryName = Country Name (2 letter code)
655 countryName_default = AU
659 localityName = Locality Name (eg, city)
661 organizationalUnitName = Organizational Unit Name (eg, section)
663 commonName = Common Name (eg, YOUR name)
666 emailAddress = Email Address
667 emailAddress_max = 40
670 challengePassword = A challenge password
671 challengePassword_min = 4
672 challengePassword_max = 20
676 subjectKeyIdentifier=hash
677 authorityKeyIdentifier=keyid:always,issuer:always
678 basicConstraints = critical, CA:true
680 Sample configuration containing all field values:
685 default_keyfile = keyfile.pem
686 distinguished_name = req_distinguished_name
687 attributes = req_attributes
689 output_password = mypass
691 [ req_distinguished_name ]
693 ST = Test State or Province
695 O = Organization Name
696 OU = Organizational Unit Name
698 emailAddress = test@email.address
701 challengePassword = A challenge password
703 Example of giving the most common attributes (subject and extensions)
706 openssl req -new -subj "/C=GB/CN=foo" \
707 -addext "subjectAltName = DNS:foo.co.uk" \
708 -addext "certificatePolicies = 1.2.3.4" \
709 -newkey rsa:2048 -keyout key.pem -out req.pem
714 The certificate requests generated by B<Xenroll> with MSIE have extensions
715 added. It includes the B<keyUsage> extension which determines the type of
716 key (signature only or general purpose) and any additional OIDs entered
717 by the script in an B<extendedKeyUsage> extension.
721 The following messages are frequently asked about:
723 Using configuration from /some/path/openssl.cnf
724 Unable to load config info
726 This is followed some time later by:
728 unable to find 'distinguished_name' in config
729 problems making Certificate Request
731 The first error message is the clue: it can't find the configuration
732 file! Certain operations (like examining a certificate request) don't
733 need a configuration file so its use isn't enforced. Generation of
734 certificates or requests however does need a configuration file. This
735 could be regarded as a bug.
737 Another puzzling message is this:
742 this is displayed when no attributes are present and the request includes
743 the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
744 0x00). If you just see:
748 then the B<SET OF> is missing and the encoding is technically invalid (but
749 it is tolerated). See the description of the command line option B<-asn1-kludge>
750 for more information.
754 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
755 treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
756 This can cause problems if you need characters that aren't available in
757 PrintableStrings and you don't want to or can't use BMPStrings.
759 As a consequence of the T61String handling the only correct way to represent
760 accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
761 currently chokes on these. If you have to use accented characters with Netscape
762 and MSIE then you currently need to use the invalid T61String form.
764 The current prompting is not very friendly. It doesn't allow you to confirm what
765 you've just entered. Other things like extensions in certificate requests are
766 statically defined in the configuration file. Some of these: like an email
767 address in subjectAltName should be input by the user.
774 L<openssl-genrsa(1)>,
775 L<openssl-gendsa(1)>,
781 The B<-section> option was added in OpenSSL 3.0.0.
783 The B<-multivalue-rdn> option has become obsolete in OpenSSL 3.0.0 and
786 The B<-engine> option was deprecated in OpenSSL 3.0.
787 The <-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead.
789 The B<-reqexts> option has been made an alias of B<-extensions> in OpenSSL 3.2.
792 generated certificates bear X.509 version 3 unless B<-x509v1> is given,
793 and key identifier extensions are included by default.
797 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
799 Licensed under the Apache License 2.0 (the "License"). You may not use
800 this file except in compliance with the License. You can obtain a copy
801 in the file LICENSE in the source distribution or at
802 L<https://www.openssl.org/source/license.html>.