1REQ(1)                              OpenSSL                             REQ(1)
2
3
4

NAME

6       openssl-req, req - PKCS#10 certificate request and certificate
7       generating utility
8

SYNOPSIS

10       openssl req [-help] [-inform PEM|DER] [-outform PEM|DER] [-in filename]
11       [-passin arg] [-out filename] [-passout arg] [-text] [-pubkey] [-noout]
12       [-verify] [-modulus] [-new] [-rand file...]  [-writerand file] [-newkey
13       rsa:bits] [-newkey alg:file] [-nodes] [-key filename] [-keyform
14       PEM|DER] [-keyout filename] [-keygen_engine id] [-digest] [-config
15       filename] [-multivalue-rdn] [-x509] [-days n] [-set_serial n] [-newhdr]
16       [-addext ext] [-extensions section] [-reqexts section] [-precert]
17       [-utf8] [-nameopt] [-reqopt] [-subject] [-subj arg] [-sigopt nm:v]
18       [-batch] [-verbose] [-engine id]
19

DESCRIPTION

21       The req command primarily creates and processes certificate requests in
22       PKCS#10 format. It can additionally create self signed certificates for
23       use as root CAs for example.
24

OPTIONS

26       -help
27           Print out a usage message.
28
29       -inform DER|PEM
30           This specifies the input format. The DER option uses an ASN1 DER
31           encoded form compatible with the PKCS#10. The PEM form is the
32           default format: it consists of the DER format base64 encoded with
33           additional header and footer lines.
34
35       -outform DER|PEM
36           This specifies the output format, the options have the same meaning
37           and default as the -inform option.
38
39       -in filename
40           This specifies the input filename to read a request from or
41           standard input if this option is not specified. A request is only
42           read if the creation options (-new and -newkey) are not specified.
43
44       -sigopt nm:v
45           Pass options to the signature algorithm during sign or verify
46           operations.  Names and values of these options are algorithm-
47           specific.
48
49       -passin arg
50           The input file password source. For more information about the
51           format of arg see "Pass Phrase Options" in openssl(1).
52
53       -out filename
54           This specifies the output filename to write to or standard output
55           by default.
56
57       -passout arg
58           The output file password source. For more information about the
59           format of arg see "Pass Phrase Options" in openssl(1).
60
61       -text
62           Prints out the certificate request in text form.
63
64       -subject
65           Prints out the request subject (or certificate subject if -x509 is
66           specified)
67
68       -pubkey
69           Outputs the public key.
70
71       -noout
72           This option prevents output of the encoded version of the request.
73
74       -modulus
75           This option prints out the value of the modulus of the public key
76           contained in the request.
77
78       -verify
79           Verifies the signature on the request.
80
81       -new
82           This option generates a new certificate request. It will prompt the
83           user for the relevant field values. The actual fields prompted for
84           and their maximum and minimum sizes are specified in the
85           configuration file and any requested extensions.
86
87           If the -key option is not used it will generate a new RSA private
88           key using information specified in the configuration file.
89
90       -rand file...
91           A file or files containing random data used to seed the random
92           number generator.  Multiple files can be specified separated by an
93           OS-dependent character.  The separator is ; for MS-Windows, , for
94           OpenVMS, and : for all others.
95
96       [-writerand file]
97           Writes random data to the specified file upon exit.  This can be
98           used with a subsequent -rand flag.
99
100       -newkey arg
101           This option creates a new certificate request and a new private
102           key. The argument takes one of several forms. rsa:nbits, where
103           nbits is the number of bits, generates an RSA key nbits in size. If
104           nbits is omitted, i.e. -newkey rsa specified, the default key size,
105           specified in the configuration file is used.
106
107           All other algorithms support the -newkey alg:file form, where file
108           may be an algorithm parameter file, created by the genpkey
109           -genparam command or and X.509 certificate for a key with
110           appropriate algorithm.
111
112           param:file generates a key using the parameter file or certificate
113           file, the algorithm is determined by the parameters. algname:file
114           use algorithm algname and parameter file file: the two algorithms
115           must match or an error occurs. algname just uses algorithm algname,
116           and parameters, if necessary should be specified via -pkeyopt
117           parameter.
118
119           dsa:filename generates a DSA key using the parameters in the file
120           filename. ec:filename generates EC key (usable both with ECDSA or
121           ECDH algorithms), gost2001:filename generates GOST R 34.10-2001 key
122           (requires ccgost engine configured in the configuration file). If
123           just gost2001 is specified a parameter set should be specified by
124           -pkeyopt paramset:X
125
126       -pkeyopt opt:value
127           Set the public key algorithm option opt to value. The precise set
128           of options supported depends on the public key algorithm used and
129           its implementation. See KEY GENERATION OPTIONS in the genpkey
130           manual page for more details.
131
132       -key filename
133           This specifies the file to read the private key from. It also
134           accepts PKCS#8 format private keys for PEM format files.
135
136       -keyform PEM|DER
137           The format of the private key file specified in the -key argument.
138           PEM is the default.
139
140       -keyout filename
141           This gives the filename to write the newly created private key to.
142           If this option is not specified then the filename present in the
143           configuration file is used.
144
145       -nodes
146           If this option is specified then if a private key is created it
147           will not be encrypted.
148
149       -digest
150           This specifies the message digest to sign the request.  Any digest
151           supported by the OpenSSL dgst command can be used.  This overrides
152           the digest algorithm specified in the configuration file.
153
154           Some public key algorithms may override this choice. For instance,
155           DSA signatures always use SHA1, GOST R 34.10 signatures always use
156           GOST R 34.11-94 (-md_gost94), Ed25519 and Ed448 never use any
157           digest.
158
159       -config filename
160           This allows an alternative configuration file to be specified.
161           Optional; for a description of the default value, see "COMMAND
162           SUMMARY" in openssl(1).
163
164       -subj arg
165           Sets subject name for new request or supersedes the subject name
166           when processing a request.  The arg must be formatted as
167           /type0=value0/type1=value1/type2=....  Keyword characters may be
168           escaped by \ (backslash), and whitespace is retained.  Empty values
169           are permitted, but the corresponding type will not be included in
170           the request.
171
172       -multivalue-rdn
173           This option causes the -subj argument to be interpreted with full
174           support for multivalued RDNs. Example:
175
176           /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
177
178           If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
179
180       -x509
181           This option outputs a self signed certificate instead of a
182           certificate request. This is typically used to generate a test
183           certificate or a self signed root CA. The extensions added to the
184           certificate (if any) are specified in the configuration file.
185           Unless specified using the set_serial option, a large random number
186           will be used for the serial number.
187
188           If existing request is specified with the -in option, it is
189           converted to the self signed certificate otherwise new request is
190           created.
191
192       -days n
193           When the -x509 option is being used this specifies the number of
194           days to certify the certificate for, otherwise it is ignored. n
195           should be a positive integer. The default is 30 days.
196
197       -set_serial n
198           Serial number to use when outputting a self signed certificate.
199           This may be specified as a decimal value or a hex value if preceded
200           by 0x.
201
202       -addext ext
203           Add a specific extension to the certificate (if the -x509 option is
204           present) or certificate request.  The argument must have the form
205           of a key=value pair as it would appear in a config file.
206
207           This option can be given multiple times.
208
209       -extensions section
210       -reqexts section
211           These options specify alternative sections to include certificate
212           extensions (if the -x509 option is present) or certificate request
213           extensions. This allows several different sections to be used in
214           the same configuration file to specify requests for a variety of
215           purposes.
216
217       -precert
218           A poison extension will be added to the certificate, making it a
219           "pre-certificate" (see RFC6962). This can be submitted to
220           Certificate Transparency logs in order to obtain signed certificate
221           timestamps (SCTs).  These SCTs can then be embedded into the pre-
222           certificate as an extension, before removing the poison and signing
223           the certificate.
224
225           This implies the -new flag.
226
227       -utf8
228           This option causes field values to be interpreted as UTF8 strings,
229           by default they are interpreted as ASCII. This means that the field
230           values, whether prompted from a terminal or obtained from a
231           configuration file, must be valid UTF8 strings.
232
233       -nameopt option
234           Option which determines how the subject or issuer names are
235           displayed. The option argument can be a single option or multiple
236           options separated by commas.  Alternatively the -nameopt switch may
237           be used more than once to set multiple options. See the x509(1)
238           manual page for details.
239
240       -reqopt
241           Customise the output format used with -text. The option argument
242           can be a single option or multiple options separated by commas.
243
244           See discussion of the  -certopt parameter in the x509(1) command.
245
246       -newhdr
247           Adds the word NEW to the PEM file header and footer lines on the
248           outputted request. Some software (Netscape certificate server) and
249           some CAs need this.
250
251       -batch
252           Non-interactive mode.
253
254       -verbose
255           Print extra details about the operations being performed.
256
257       -engine id
258           Specifying an engine (by its unique id string) will cause req to
259           attempt to obtain a functional reference to the specified engine,
260           thus initialising it if needed. The engine will then be set as the
261           default for all available algorithms.
262
263       -keygen_engine id
264           Specifies an engine (by its unique id string) which would be used
265           for key generation operations.
266

CONFIGURATION FILE FORMAT

268       The configuration options are specified in the req section of the
269       configuration file. As with all configuration files if no value is
270       specified in the specific section (i.e. req) then the initial unnamed
271       or default section is searched too.
272
273       The options available are described in detail below.
274
275       input_password output_password
276           The passwords for the input private key file (if present) and the
277           output private key file (if one will be created). The command line
278           options passin and passout override the configuration file values.
279
280       default_bits
281           Specifies the default key size in bits.
282
283           This option is used in conjunction with the -new option to generate
284           a new key. It can be overridden by specifying an explicit key size
285           in the -newkey option. The smallest accepted key size is 512 bits.
286           If no key size is specified then 2048 bits is used.
287
288       default_keyfile
289           This is the default filename to write a private key to. If not
290           specified the key is written to standard output. This can be
291           overridden by the -keyout option.
292
293       oid_file
294           This specifies a file containing additional OBJECT IDENTIFIERS.
295           Each line of the file should consist of the numerical form of the
296           object identifier followed by white space then the short name
297           followed by white space and finally the long name.
298
299       oid_section
300           This specifies a section in the configuration file containing extra
301           object identifiers. Each line should consist of the short name of
302           the object identifier followed by = and the numerical form. The
303           short and long names are the same when this option is used.
304
305       RANDFILE
306           At startup the specified file is loaded into the random number
307           generator, and at exit 256 bytes will be written to it.  It is used
308           for private key generation.
309
310       encrypt_key
311           If this is set to no then if a private key is generated it is not
312           encrypted. This is equivalent to the -nodes command line option.
313           For compatibility encrypt_rsa_key is an equivalent option.
314
315       default_md
316           This option specifies the digest algorithm to use. Any digest
317           supported by the OpenSSL dgst command can be used. This option can
318           be overridden on the command line. Certain signing algorithms (i.e.
319           Ed25519 and Ed448) will ignore any digest that has been set.
320
321       string_mask
322           This option masks out the use of certain string types in certain
323           fields. Most users will not need to change this option.
324
325           It can be set to several values default which is also the default
326           option uses PrintableStrings, T61Strings and BMPStrings if the pkix
327           value is used then only PrintableStrings and BMPStrings will be
328           used. This follows the PKIX recommendation in RFC2459. If the
329           utf8only option is used then only UTF8Strings will be used: this is
330           the PKIX recommendation in RFC2459 after 2003. Finally the nombstr
331           option just uses PrintableStrings and T61Strings: certain software
332           has problems with BMPStrings and UTF8Strings: in particular
333           Netscape.
334
335       req_extensions
336           This specifies the configuration file section containing a list of
337           extensions to add to the certificate request. It can be overridden
338           by the -reqexts command line switch. See the x509v3_config(5)
339           manual page for details of the extension section format.
340
341       x509_extensions
342           This specifies the configuration file section containing a list of
343           extensions to add to certificate generated when the -x509 switch is
344           used. It can be overridden by the -extensions command line switch.
345
346       prompt
347           If set to the value no this disables prompting of certificate
348           fields and just takes values from the config file directly. It also
349           changes the expected format of the distinguished_name and
350           attributes sections.
351
352       utf8
353           If set to the value yes then field values to be interpreted as UTF8
354           strings, by default they are interpreted as ASCII. This means that
355           the field values, whether prompted from a terminal or obtained from
356           a configuration file, must be valid UTF8 strings.
357
358       attributes
359           This specifies the section containing any request attributes: its
360           format is the same as distinguished_name. Typically these may
361           contain the challengePassword or unstructuredName types. They are
362           currently ignored by OpenSSL's request signing utilities but some
363           CAs might want them.
364
365       distinguished_name
366           This specifies the section containing the distinguished name fields
367           to prompt for when generating a certificate or certificate request.
368           The format is described in the next section.
369

DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT

371       There are two separate formats for the distinguished name and attribute
372       sections. If the prompt option is set to no then these sections just
373       consist of field names and values: for example,
374
375        CN=My Name
376        OU=My Organization
377        emailAddress=someone@somewhere.org
378
379       This allows external programs (e.g. GUI based) to generate a template
380       file with all the field names and values and just pass it to req. An
381       example of this kind of configuration file is contained in the EXAMPLES
382       section.
383
384       Alternatively if the prompt option is absent or not set to no then the
385       file contains field prompting information. It consists of lines of the
386       form:
387
388        fieldName="prompt"
389        fieldName_default="default field value"
390        fieldName_min= 2
391        fieldName_max= 4
392
393       "fieldName" is the field name being used, for example commonName (or
394       CN).  The "prompt" string is used to ask the user to enter the relevant
395       details. If the user enters nothing then the default value is used if
396       no default value is present then the field is omitted. A field can
397       still be omitted if a default value is present if the user just enters
398       the '.' character.
399
400       The number of characters entered must be between the fieldName_min and
401       fieldName_max limits: there may be additional restrictions based on the
402       field being used (for example countryName can only ever be two
403       characters long and must fit in a PrintableString).
404
405       Some fields (such as organizationName) can be used more than once in a
406       DN. This presents a problem because configuration files will not
407       recognize the same name occurring twice. To avoid this problem if the
408       fieldName contains some characters followed by a full stop they will be
409       ignored. So for example a second organizationName can be input by
410       calling it "1.organizationName".
411
412       The actual permitted field names are any object identifier short or
413       long names. These are compiled into OpenSSL and include the usual
414       values such as commonName, countryName, localityName, organizationName,
415       organizationalUnitName, stateOrProvinceName. Additionally emailAddress
416       is included as well as name, surname, givenName, initials, and
417       dnQualifier.
418
419       Additional object identifiers can be defined with the oid_file or
420       oid_section options in the configuration file. Any additional fields
421       will be treated as though they were a DirectoryString.
422

EXAMPLES

424       Examine and verify certificate request:
425
426        openssl req -in req.pem -text -verify -noout
427
428       Create a private key and then generate a certificate request from it:
429
430        openssl genrsa -out key.pem 2048
431        openssl req -new -key key.pem -out req.pem
432
433       The same but just using req:
434
435        openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
436
437       Generate a self signed root certificate:
438
439        openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
440
441       Example of a file pointed to by the oid_file option:
442
443        1.2.3.4        shortName       A longer Name
444        1.2.3.6        otherName       Other longer Name
445
446       Example of a section pointed to by oid_section making use of variable
447       expansion:
448
449        testoid1=1.2.3.5
450        testoid2=${testoid1}.6
451
452       Sample configuration file prompting for field values:
453
454        [ req ]
455        default_bits           = 2048
456        default_keyfile        = privkey.pem
457        distinguished_name     = req_distinguished_name
458        attributes             = req_attributes
459        req_extensions         = v3_ca
460
461        dirstring_type = nobmp
462
463        [ req_distinguished_name ]
464        countryName                    = Country Name (2 letter code)
465        countryName_default            = AU
466        countryName_min                = 2
467        countryName_max                = 2
468
469        localityName                   = Locality Name (eg, city)
470
471        organizationalUnitName         = Organizational Unit Name (eg, section)
472
473        commonName                     = Common Name (eg, YOUR name)
474        commonName_max                 = 64
475
476        emailAddress                   = Email Address
477        emailAddress_max               = 40
478
479        [ req_attributes ]
480        challengePassword              = A challenge password
481        challengePassword_min          = 4
482        challengePassword_max          = 20
483
484        [ v3_ca ]
485
486        subjectKeyIdentifier=hash
487        authorityKeyIdentifier=keyid:always,issuer:always
488        basicConstraints = critical, CA:true
489
490       Sample configuration containing all field values:
491
492        RANDFILE               = $ENV::HOME/.rnd
493
494        [ req ]
495        default_bits           = 2048
496        default_keyfile        = keyfile.pem
497        distinguished_name     = req_distinguished_name
498        attributes             = req_attributes
499        prompt                 = no
500        output_password        = mypass
501
502        [ req_distinguished_name ]
503        C                      = GB
504        ST                     = Test State or Province
505        L                      = Test Locality
506        O                      = Organization Name
507        OU                     = Organizational Unit Name
508        CN                     = Common Name
509        emailAddress           = test@email.address
510
511        [ req_attributes ]
512        challengePassword              = A challenge password
513
514       Example of giving the most common attributes (subject and extensions)
515       on the command line:
516
517        openssl req -new -subj "/C=GB/CN=foo" \
518                         -addext "subjectAltName = DNS:foo.co.uk" \
519                         -addext "certificatePolicies = 1.2.3.4" \
520                         -newkey rsa:2048 -keyout key.pem -out req.pem
521

NOTES

523       The header and footer lines in the PEM format are normally:
524
525        -----BEGIN CERTIFICATE REQUEST-----
526        -----END CERTIFICATE REQUEST-----
527
528       some software (some versions of Netscape certificate server) instead
529       needs:
530
531        -----BEGIN NEW CERTIFICATE REQUEST-----
532        -----END NEW CERTIFICATE REQUEST-----
533
534       which is produced with the -newhdr option but is otherwise compatible.
535       Either form is accepted transparently on input.
536
537       The certificate requests generated by Xenroll with MSIE have extensions
538       added. It includes the keyUsage extension which determines the type of
539       key (signature only or general purpose) and any additional OIDs entered
540       by the script in an extendedKeyUsage extension.
541

DIAGNOSTICS

543       The following messages are frequently asked about:
544
545               Using configuration from /some/path/openssl.cnf
546               Unable to load config info
547
548       This is followed some time later by...
549
550               unable to find 'distinguished_name' in config
551               problems making Certificate Request
552
553       The first error message is the clue: it can't find the configuration
554       file! Certain operations (like examining a certificate request) don't
555       need a configuration file so its use isn't enforced. Generation of
556       certificates or requests however does need a configuration file. This
557       could be regarded as a bug.
558
559       Another puzzling message is this:
560
561               Attributes:
562                   a0:00
563
564       this is displayed when no attributes are present and the request
565       includes the correct empty SET OF structure (the DER encoding of which
566       is 0xa0 0x00). If you just see:
567
568               Attributes:
569
570       then the SET OF is missing and the encoding is technically invalid (but
571       it is tolerated). See the description of the command line option
572       -asn1-kludge for more information.
573

BUGS

575       OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it
576       effectively treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have
577       similar behaviour.  This can cause problems if you need characters that
578       aren't available in PrintableStrings and you don't want to or can't use
579       BMPStrings.
580
581       As a consequence of the T61String handling the only correct way to
582       represent accented characters in OpenSSL is to use a BMPString:
583       unfortunately Netscape currently chokes on these. If you have to use
584       accented characters with Netscape and MSIE then you currently need to
585       use the invalid T61String form.
586
587       The current prompting is not very friendly. It doesn't allow you to
588       confirm what you've just entered. Other things like extensions in
589       certificate requests are statically defined in the configuration file.
590       Some of these: like an email address in subjectAltName should be input
591       by the user.
592

SEE ALSO

594       x509(1), ca(1), genrsa(1), gendsa(1), config(5), x509v3_config(5)
595
597       Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
598
599       Licensed under the OpenSSL license (the "License").  You may not use
600       this file except in compliance with the License.  You can obtain a copy
601       in the file LICENSE in the source distribution or at
602       <https://www.openssl.org/source/license.html>.
603
604
605
6061.1.1k                            2021-03-26                            REQ(1)
Impressum