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

CONFIGURATION FILE FORMAT

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

DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT

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

EXAMPLES

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

NOTES

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

DIAGNOSTICS

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

BUGS

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

SEE ALSO

589       x509(1), ca(1), genrsa(1), gendsa(1), config(5), x509v3_config(5)
590
592       Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
593
594       Licensed under the OpenSSL license (the "License").  You may not use
595       this file except in compliance with the License.  You can obtain a copy
596       in the file LICENSE in the source distribution or at
597       <https://www.openssl.org/source/license.html>.
598
599
600
6011.1.1d                            2019-10-03                            REQ(1)
Impressum