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>]
36 [B<-CA> I<filename>|I<uri>]
37 [B<-CAkey> I<filename>|I<uri>]
41 [B<-copy_extensions> I<arg>]
43 [B<-extensions> I<section>]
44 [B<-reqexts> I<section>]
51 [B<-sigopt> I<nm>:I<v>]
52 [B<-vfyopt> I<nm>:I<v>]
55 {- $OpenSSL::safe::opt_name_synopsis -}
56 {- $OpenSSL::safe::opt_r_synopsis -}
57 {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
59 =for openssl ifdef engine keygen_engine
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>, B<-outform> B<DER>|B<PEM>
77 The input and output formats; the default is B<PEM>.
78 See L<openssl-format-options(1)> for details.
80 The data is a PKCS#10 object.
82 =item B<-in> I<filename>
84 This specifies the input filename to read a request from or standard input
85 if this option is not specified. A request is only read if the creation
86 options (B<-new> or B<-newkey>) are not specified.
88 =item B<-sigopt> I<nm>:I<v>
90 Pass options to the signature algorithm during sign operations.
91 Names and values of these options are algorithm-specific.
93 =item B<-vfyopt> I<nm>:I<v>
95 Pass options to the signature algorithm during verify operations.
96 Names and values of these options are algorithm-specific.
100 Maybe it would be preferable to only have -opts instead of -sigopt and
101 -vfyopt? They are both present here to be compatible with L<openssl-ca(1)>,
102 which supports both options for good reasons.
106 =item B<-passin> I<arg>
108 The password source for the request input file and the certificate input.
109 For more information about the format of B<arg>
110 see L<openssl-passphrase-options(1)>.
112 =item B<-passout> I<arg>
114 The password source for the output file.
115 For more information about the format of B<arg>
116 see L<openssl-passphrase-options(1)>.
118 =item B<-out> I<filename>
120 This specifies the output filename to write to or standard output by default.
124 Prints out the certificate request in text form.
128 Prints out the certificate request subject
129 (or certificate subject if B<-x509> is specified).
133 Prints out the public key.
137 This option prevents output of the encoded version of the certificate request.
141 Prints out the value of the modulus of the public key contained in the request.
145 Verifies the signature on the request.
149 This option generates a new certificate request. It will prompt
150 the user for the relevant field values. The actual fields
151 prompted for and their maximum and minimum sizes are specified
152 in the configuration file and any requested extensions.
154 If the B<-key> option is not given it will generate a new RSA private key
155 using information specified in the configuration file or given with
156 the B<-newkey> and B<-pkeyopt> options, else by default with 2048 bits length.
158 =item B<-newkey> I<arg>
160 This option creates a new certificate request and a new private
161 key. The argument takes one of several forms.
163 B<rsa:>I<nbits>, where
164 I<nbits> is the number of bits, generates an RSA key I<nbits>
165 in size. If I<nbits> is omitted, i.e. B<-newkey> I<rsa> specified,
166 the default key size, specified in the configuration file is used.
168 All other algorithms support the B<-newkey> I<alg>:I<file> form, where file
169 may be an algorithm parameter file, created with C<openssl genpkey -genparam>
170 or an X.509 certificate for a key with appropriate algorithm.
172 B<param:>I<file> generates a key using the parameter file or certificate
173 I<file>, the algorithm is determined by the parameters. I<algname>:I<file>
174 use algorithm I<algname> and parameter file I<file>: the two algorithms must
175 match or an error occurs. I<algname> just uses algorithm I<algname>, and
176 parameters, if necessary should be specified via B<-pkeyopt> parameter.
178 B<dsa:>I<filename> generates a DSA key using the parameters
179 in the file I<filename>. B<ec:>I<filename> generates EC key (usable both with
180 ECDSA or ECDH algorithms), B<gost2001:>I<filename> generates GOST R
181 34.10-2001 key (requires B<gost> engine configured in the configuration
182 file). If just B<gost2001> is specified a parameter set should be
183 specified by B<-pkeyopt> I<paramset:X>
185 =item B<-pkeyopt> I<opt>:I<value>
187 Set the public key algorithm option I<opt> to I<value>. The precise set of
188 options supported depends on the public key algorithm used and its
190 See L<openssl-genpkey(1)/KEY GENERATION OPTIONS> for more details.
192 =item B<-key> I<filename>|I<uri>
194 This specifies the private key to use for request self-signature
195 and signing certificates produced using the B<-x509> option.
196 It also accepts PKCS#8 format private keys for PEM format files.
198 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
200 The format of the private key; the default is B<PEM>.
201 The only value with effect is B<ENGINE>; all others have become obsolete.
202 See L<openssl-format-options(1)> for details.
204 =item B<-keyout> I<filename>
206 This gives the filename to write the newly created private key to.
207 If this option is not specified then the filename present in the
208 configuration file is used.
212 If this option is specified then if a private key is created it
213 will not be encrypted.
217 This option is deprecated since OpenSSL 3.0; use B<-noenc> instead.
221 This specifies the message digest to sign the request.
222 Any digest supported by the OpenSSL B<dgst> command can be used.
223 This overrides the digest algorithm specified in
224 the configuration file.
226 Some public key algorithms may override this choice. For instance, DSA
227 signatures always use SHA1, GOST R 34.10 signatures always use
228 GOST R 34.11-94 (B<-md_gost94>), Ed25519 and Ed448 never use any digest.
230 =item B<-config> I<filename>
232 This allows an alternative configuration file to be specified.
233 Optional; for a description of the default value,
234 see L<openssl(1)/COMMAND SUMMARY>.
236 =item B<-section> I<name>
238 Specifies the name of the section to use; the default is B<req>.
240 =item B<-subj> I<arg>
242 Sets subject name for new request or supersedes the subject name
243 when processing a certificate request.
245 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
246 Special characters may be escaped by C<\> (backslash), whitespace is retained.
247 Empty values are permitted, but the corresponding type will not be included
249 Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
250 Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
251 between the AttributeValueAssertions (AVAs) that specify the members of the set.
254 C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
256 =item B<-multivalue-rdn>
258 This option has been deprecated and has no effect.
262 This option outputs a certificate instead of a certificate request.
263 This is typically used to generate test certificates.
265 If an existing request is specified with the B<-in> option, it is converted
266 to the a certificate; otherwise a request is created from scratch.
268 Unless specified using the B<-set_serial> option,
269 a large random number will be used for the serial number.
271 Unless the B<-copy_extensions> option is used,
272 X.509 extensions are not copied from any provided request input file.
273 X.509 extensions to be added can be specified in the configuration file
274 or using the B<-addext> option.
276 =item B<-CA> I<filename>|I<uri>
278 Specifies the "CA" certificate to be used for signing with the B<-x509> option.
279 When present, this behaves like a "micro CA" as follows:
280 The subject name of the "CA" certificate is placed as issuer name in the new
281 certificate, which is then signed using the "CA" key given as specified below.
283 =item B<-CAkey> I<filename>|I<uri>
285 Sets the "CA" private key to sign a certificate with.
286 The private key must match the public key of the certificate given with B<-CA>.
287 If this option is not provided then the key must be present in the B<-CA> input.
291 When the B<-x509> option is being used this specifies the number of
292 days to certify the certificate for, otherwise it is ignored. I<n> should
293 be a positive integer. The default is 30 days.
295 =item B<-set_serial> I<n>
297 Serial number to use when outputting a self-signed certificate. This
298 may be specified as a decimal value or a hex value if preceded by C<0x>.
300 =item B<-copy_extensions> I<arg>
302 Determines how extensions in certificate requests should be handled when B<-x509> is given.
303 If I<arg> is B<none> or this option is not present
304 then extensions present in the request are ignored.
305 If I<arg> is B<copy> or B<copyall> then
306 any extensions present in the request are copied to the certificate.
308 The main use of this option is to allow a certificate request to supply
309 values for certain extensions such as subjectAltName.
311 =item B<-addext> I<ext>
313 Add a specific extension to the certificate (if the B<-x509> option is
314 present) or certificate request. The argument must have the form of
315 a key=value pair as it would appear in a config file.
317 This option can be given multiple times.
319 =item B<-extensions> I<section>
321 =item B<-reqexts> I<section>
323 These options specify alternative sections to include certificate
324 extensions (if the B<-x509> option is present) or certificate
325 request extensions. This allows several different sections to
326 be used in the same configuration file to specify requests for
327 a variety of purposes.
331 A poison extension will be added to the certificate, making it a
332 "pre-certificate" (see RFC6962). This can be submitted to Certificate
333 Transparency logs in order to obtain signed certificate timestamps (SCTs).
334 These SCTs can then be embedded into the pre-certificate as an extension, before
335 removing the poison and signing the certificate.
337 This implies the B<-new> flag.
341 This option causes field values to be interpreted as UTF8 strings, by
342 default they are interpreted as ASCII. This means that the field
343 values, whether prompted from a terminal or obtained from a
344 configuration file, must be valid UTF8 strings.
346 =item B<-reqopt> I<option>
348 Customise the printing format used with B<-text>. The I<option> argument can be
349 a single option or multiple options separated by commas.
351 See discussion of the B<-certopt> parameter in the L<openssl-x509(1)>
356 Adds the word B<NEW> to the PEM file header and footer lines on the outputted
357 request. Some software (Netscape certificate server) and some CAs need this.
361 Non-interactive mode.
365 Print extra details about the operations being performed.
367 =item B<-keygen_engine> I<id>
369 Specifies an engine (by its unique I<id> string) which would be used
370 for key generation operations.
372 {- $OpenSSL::safe::opt_name_item -}
374 {- $OpenSSL::safe::opt_r_item -}
376 {- $OpenSSL::safe::opt_engine_item -}
378 {- $OpenSSL::safe::opt_provider_item -}
382 =head1 CONFIGURATION FILE FORMAT
384 The configuration options are specified in the B<req> section of
385 the configuration file. An alternate name be specified by using the
387 As with all configuration files, if no
388 value is specified in the specific section then
389 the initial unnamed or B<default> section is searched too.
391 The options available are described in detail below.
395 =item B<input_password output_password>
397 The passwords for the input private key file (if present) and
398 the output private key file (if one will be created). The
399 command line options B<passin> and B<passout> override the
400 configuration file values.
402 =item B<default_bits>
404 Specifies the default key size in bits.
406 This option is used in conjunction with the B<-new> option to generate
407 a new key. It can be overridden by specifying an explicit key size in
408 the B<-newkey> option. The smallest accepted key size is 512 bits. If
409 no key size is specified then 2048 bits is used.
411 =item B<default_keyfile>
413 This is the default filename to write a private key to. If not
414 specified the key is written to standard output. This can be
415 overridden by the B<-keyout> option.
419 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
420 Each line of the file should consist of the numerical form of the
421 object identifier followed by whitespace then the short name followed
422 by whitespace and finally the long name.
426 This specifies a section in the configuration file containing extra
427 object identifiers. Each line should consist of the short name of the
428 object identifier followed by B<=> and the numerical form. The short
429 and long names are the same when this option is used.
433 At startup the specified file is loaded into the random number generator,
434 and at exit 256 bytes will be written to it.
435 It is used for private key generation.
439 If this is set to B<no> then if a private key is generated it is
440 B<not> encrypted. This is equivalent to the B<-noenc> command line
441 option. For compatibility B<encrypt_rsa_key> is an equivalent option.
445 This option specifies the digest algorithm to use. Any digest supported by the
446 OpenSSL B<dgst> command can be used. This option can be overridden on the
447 command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore
448 any digest that has been set.
452 This option masks out the use of certain string types in certain
453 fields. Most users will not need to change this option.
455 It can be set to several values B<default> which is also the default
456 option uses PrintableStrings, T61Strings and BMPStrings if the
457 B<pkix> value is used then only PrintableStrings and BMPStrings will
458 be used. This follows the PKIX recommendation in RFC2459. If the
459 B<utf8only> option is used then only UTF8Strings will be used: this
460 is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
461 option just uses PrintableStrings and T61Strings: certain software has
462 problems with BMPStrings and UTF8Strings: in particular Netscape.
464 =item B<req_extensions>
466 This specifies the configuration file section containing a list of
467 extensions to add to the certificate request. It can be overridden
468 by the B<-reqexts> command line switch. See the
469 L<x509v3_config(5)> manual page for details of the
470 extension section format.
472 =item B<x509_extensions>
474 This specifies the configuration file section containing a list of
475 extensions to add to certificate generated when the B<-x509> switch
476 is used. It can be overridden by the B<-extensions> command line switch.
480 If set to the value B<no> this disables prompting of certificate fields
481 and just takes values from the config file directly. It also changes the
482 expected format of the B<distinguished_name> and B<attributes> sections.
486 If set to the value B<yes> then field values to be interpreted as UTF8
487 strings, by default they are interpreted as ASCII. This means that
488 the field values, whether prompted from a terminal or obtained from a
489 configuration file, must be valid UTF8 strings.
493 This specifies the section containing any request attributes: its format
494 is the same as B<distinguished_name>. Typically these may contain the
495 challengePassword or unstructuredName types. They are currently ignored
496 by OpenSSL's request signing utilities but some CAs might want them.
498 =item B<distinguished_name>
500 This specifies the section containing the distinguished name fields to
501 prompt for when generating a certificate or certificate request. The format
502 is described in the next section.
506 =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
508 There are two separate formats for the distinguished name and attribute
509 sections. If the B<prompt> option is set to B<no> then these sections
510 just consist of field names and values: for example,
514 emailAddress=someone@somewhere.org
516 This allows external programs (e.g. GUI based) to generate a template file with
517 all the field names and values and just pass it to this command. An example
518 of this kind of configuration file is contained in the B<EXAMPLES> section.
520 Alternatively if the B<prompt> option is absent or not set to B<no> then the
521 file contains field prompting information. It consists of lines of the form:
524 fieldName_default="default field value"
528 "fieldName" is the field name being used, for example commonName (or CN).
529 The "prompt" string is used to ask the user to enter the relevant
530 details. If the user enters nothing then the default value is used if no
531 default value is present then the field is omitted. A field can
532 still be omitted if a default value is present if the user just
533 enters the '.' character.
535 The number of characters entered must be between the fieldName_min and
536 fieldName_max limits: there may be additional restrictions based
537 on the field being used (for example countryName can only ever be
538 two characters long and must fit in a PrintableString).
540 Some fields (such as organizationName) can be used more than once
541 in a DN. This presents a problem because configuration files will
542 not recognize the same name occurring twice. To avoid this problem
543 if the fieldName contains some characters followed by a full stop
544 they will be ignored. So for example a second organizationName can
545 be input by calling it "1.organizationName".
547 The actual permitted field names are any object identifier short or
548 long names. These are compiled into OpenSSL and include the usual
549 values such as commonName, countryName, localityName, organizationName,
550 organizationalUnitName, stateOrProvinceName. Additionally emailAddress
551 is included as well as name, surname, givenName, initials, and dnQualifier.
553 Additional object identifiers can be defined with the B<oid_file> or
554 B<oid_section> options in the configuration file. Any additional fields
555 will be treated as though they were a DirectoryString.
560 Examine and verify certificate request:
562 openssl req -in req.pem -text -verify -noout
564 Create a private key and then generate a certificate request from it:
566 openssl genrsa -out key.pem 2048
567 openssl req -new -key key.pem -out req.pem
569 The same but just using req:
571 openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
573 Generate a self-signed root certificate:
575 openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
577 Create an SM2 private key and then generate a certificate request from it:
579 openssl ecparam -genkey -name SM2 -out sm2.key
580 openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt "distid:1234567812345678"
582 Examine and verify an SM2 certificate request:
584 openssl req -verify -in sm2.csr -sm3 -vfyopt "distid:1234567812345678"
586 Example of a file pointed to by the B<oid_file> option:
588 1.2.3.4 shortName A longer Name
589 1.2.3.6 otherName Other longer Name
591 Example of a section pointed to by B<oid_section> making use of variable
595 testoid2=${testoid1}.6
597 Sample configuration file prompting for field values:
601 default_keyfile = privkey.pem
602 distinguished_name = req_distinguished_name
603 attributes = req_attributes
604 req_extensions = v3_ca
606 dirstring_type = nobmp
608 [ req_distinguished_name ]
609 countryName = Country Name (2 letter code)
610 countryName_default = AU
614 localityName = Locality Name (eg, city)
616 organizationalUnitName = Organizational Unit Name (eg, section)
618 commonName = Common Name (eg, YOUR name)
621 emailAddress = Email Address
622 emailAddress_max = 40
625 challengePassword = A challenge password
626 challengePassword_min = 4
627 challengePassword_max = 20
631 subjectKeyIdentifier=hash
632 authorityKeyIdentifier=keyid:always,issuer:always
633 basicConstraints = critical, CA:true
635 Sample configuration containing all field values:
640 default_keyfile = keyfile.pem
641 distinguished_name = req_distinguished_name
642 attributes = req_attributes
644 output_password = mypass
646 [ req_distinguished_name ]
648 ST = Test State or Province
650 O = Organization Name
651 OU = Organizational Unit Name
653 emailAddress = test@email.address
656 challengePassword = A challenge password
658 Example of giving the most common attributes (subject and extensions)
661 openssl req -new -subj "/C=GB/CN=foo" \
662 -addext "subjectAltName = DNS:foo.co.uk" \
663 -addext "certificatePolicies = 1.2.3.4" \
664 -newkey rsa:2048 -keyout key.pem -out req.pem
669 The certificate requests generated by B<Xenroll> with MSIE have extensions
670 added. It includes the B<keyUsage> extension which determines the type of
671 key (signature only or general purpose) and any additional OIDs entered
672 by the script in an B<extendedKeyUsage> extension.
676 The following messages are frequently asked about:
678 Using configuration from /some/path/openssl.cnf
679 Unable to load config info
681 This is followed some time later by:
683 unable to find 'distinguished_name' in config
684 problems making Certificate Request
686 The first error message is the clue: it can't find the configuration
687 file! Certain operations (like examining a certificate request) don't
688 need a configuration file so its use isn't enforced. Generation of
689 certificates or requests however does need a configuration file. This
690 could be regarded as a bug.
692 Another puzzling message is this:
697 this is displayed when no attributes are present and the request includes
698 the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
699 0x00). If you just see:
703 then the B<SET OF> is missing and the encoding is technically invalid (but
704 it is tolerated). See the description of the command line option B<-asn1-kludge>
705 for more information.
709 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
710 treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
711 This can cause problems if you need characters that aren't available in
712 PrintableStrings and you don't want to or can't use BMPStrings.
714 As a consequence of the T61String handling the only correct way to represent
715 accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
716 currently chokes on these. If you have to use accented characters with Netscape
717 and MSIE then you currently need to use the invalid T61String form.
719 The current prompting is not very friendly. It doesn't allow you to confirm what
720 you've just entered. Other things like extensions in certificate requests are
721 statically defined in the configuration file. Some of these: like an email
722 address in subjectAltName should be input by the user.
729 L<openssl-genrsa(1)>,
730 L<openssl-gendsa(1)>,
736 The B<-section> option was added in OpenSSL 3.0.0.
738 All B<-keyform> values except B<ENGINE> and the B<-multivalue-rdn> option
739 have become obsolete in OpenSSL 3.0.0 and have no effect.
741 The B<-engine> option was deprecated in OpenSSL 3.0.
742 The <-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead.
746 Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
748 Licensed under the Apache License 2.0 (the "License"). You may not use
749 this file except in compliance with the License. You can obtain a copy
750 in the file LICENSE in the source distribution or at
751 L<https://www.openssl.org/source/license.html>.