1REQ(1) OpenSSL REQ(1)
2
6 req - PKCS#10 certificate request and certificate generating utility.
7
9 openssl req [-inform PEM⎪DER] [-outform PEM⎪DER] [-in filename]
10 [-passin arg] [-out filename] [-passout arg] [-text] [-pubkey] [-noout]
11 [-verify] [-modulus] [-new] [-rand file(s)] [-newkey rsa:bits] [-newkey
12 dsa:file] [-nodes] [-key filename] [-keyform PEM⎪DER] [-keyout file‐
13 name] [-[md5⎪sha1⎪md2⎪mdc2]] [-config filename] [-subj arg] [-multi‐
14 value-rdn] [-x509] [-days n] [-set_serial n] [-asn1-kludge] [-newhdr]
15 [-extensions section] [-reqexts section] [-utf8] [-nameopt] [-batch]
16 [-verbose] [-engine id]
17
19 The req command primarily creates and processes certificate requests in
20 PKCS#10 format. It can additionally create self signed certificates for
21 use as root CAs for example.
22
24 -inform DER⎪PEM
25 This specifies the input format. The DER option uses an ASN1 DER
26 encoded form compatible with the PKCS#10. The PEM form is the
27 default format: it consists of the DER format base64 encoded with
28 additional header and footer lines.
29 -outform DER⎪PEM
31 This specifies the output format, the options have the same meaning
32 as the -inform option.
33 -in filename
35 This specifies the input filename to read a request from or stan‐
36 dard input if this option is not specified. A request is only read
37 if the creation options (-new and -newkey) are not specified.
38 -passin arg
40 the input file password source. For more information about the for‐
41 mat of arg see the PASS PHRASE ARGUMENTS section in openssl(1).
42 -out filename
44 This specifies the output filename to write to or standard output
45 by default.
46 -passout arg
48 the output file password source. For more information about the
49 format of arg see the PASS PHRASE ARGUMENTS section in openssl(1).
50 -text
52 prints out the certificate request in text form.
53 -pubkey
55 outputs the public key.
56 -noout
58 this option prevents output of the encoded version of the request.
59 -modulus
61 this option prints out the value of the modulus of the public key
62 contained in the request.
63 -verify
65 verifies the signature on the request.
66 -new
68 this option generates a new certificate request. It will prompt the
69 user for the relevant field values. The actual fields prompted for
70 and their maximum and minimum sizes are specified in the configura‐
71 tion file and any requested extensions.
72 If the -key option is not used it will generate a new RSA private
74 key using information specified in the configuration file.
75 -rand file(s)
77 a file or files containing random data used to seed the random num‐
78 ber generator, or an EGD socket (see RAND_egd(3)). Multiple files
79 can be specified separated by a OS-dependent character. The sepa‐
80 rator is ; for MS-Windows, , for OpenVMS, and : for all others.
81 -newkey arg
83 this option creates a new certificate request and a new private
84 key. The argument takes one of two forms. rsa:nbits, where nbits is
85 the number of bits, generates an RSA key nbits in size. dsa:file‐
86 name generates a DSA key using the parameters in the file filename.
87 -key filename
89 This specifies the file to read the private key from. It also
90 accepts PKCS#8 format private keys for PEM format files.
91 -keyform PEM⎪DER
93 the format of the private key file specified in the -key argument.
94 PEM is the default.
95 -keyout filename
97 this gives the filename to write the newly created private key to.
98 If this option is not specified then the filename present in the
99 configuration file is used.
100 -nodes
102 if this option is specified then if a private key is created it
103 will not be encrypted.
104 -[md5⎪sha1⎪md2⎪mdc2]
106 this specifies the message digest to sign the request with. This
107 overrides the digest algorithm specified in the configuration file.
108 This option is ignored for DSA requests: they always use SHA1.
109 -config filename
111 this allows an alternative configuration file to be specified, this
112 overrides the compile time filename or any specified in the
113 OPENSSL_CONF environment variable.
114 -subj arg
116 sets subject name for new request or supersedes the subject name
117 when processing a request. The arg must be formatted as
118 /type0=value0/type1=value1/type2=..., characters may be escaped by
119 \ (backslash), no spaces are skipped.
120 -multivalue-rdn
122 this option causes the -subj argument to be interpreted with full
123 support for multivalued RDNs. Example:
124 /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
126 If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
128 -x509
130 this option outputs a self signed certificate instead of a certifi‐
131 cate request. This is typically used to generate a test certificate
132 or a self signed root CA. The extensions added to the certificate
133 (if any) are specified in the configuration file. Unless specified
134 using the set_serial option 0 will be used for the serial number.
135 -days n
137 when the -x509 option is being used this specifies the number of
138 days to certify the certificate for. The default is 30 days.
139 -set_serial n
141 serial number to use when outputting a self signed certificate.
142 This may be specified as a decimal value or a hex value if preceded
143 by 0x. It is possible to use negative serial numbers but this is
144 not recommended.
145 -extensions section
147 -reqexts section
148 these options specify alternative sections to include certificate
149 extensions (if the -x509 option is present) or certificate request
150 extensions. This allows several different sections to be used in
151 the same configuration file to specify requests for a variety of
152 purposes.
153 -utf8
155 this option causes field values to be interpreted as UTF8 strings,
156 by default they are interpreted as ASCII. This means that the field
157 values, whether prompted from a terminal or obtained from a config‐
158 uration file, must be valid UTF8 strings.
159 -nameopt option
161 option which determines how the subject or issuer names are dis‐
162 played. The option argument can be a single option or multiple
163 options separated by commas. Alternatively the -nameopt switch may
164 be used more than once to set multiple options. See the x509(1)
165 manual page for details.
166 -asn1-kludge
168 by default the req command outputs certificate requests containing
169 no attributes in the correct PKCS#10 format. However certain CAs
170 will only accept requests containing no attributes in an invalid
171 form: this option produces this invalid format.
172 More precisely the Attributes in a PKCS#10 certificate request are
174 defined as a SET OF Attribute. They are not OPTIONAL so if no
175 attributes are present then they should be encoded as an empty SET
176 OF. The invalid form does not include the empty SET OF whereas the
177 correct form does.
178 It should be noted that very few CAs still require the use of this
180 option.
181 -newhdr
183 Adds the word NEW to the PEM file header and footer lines on the
184 outputed request. Some software (Netscape certificate server) and
185 some CAs need this.
186 -batch
188 non-interactive mode.
189 -verbose
191 print extra details about the operations being performed.
192 -engine id
194 specifying an engine (by it's unique id string) will cause req to
195 attempt to obtain a functional reference to the specified engine,
196 thus initialising it if needed. The engine will then be set as the
197 default for all available algorithms.
198
200 The configuration options are specified in the req section of the con‐
201 figuration file. As with all configuration files if no value is speci‐
202 fied in the specific section (i.e. req) then the initial unnamed or
203 default section is searched too.
204 The options available are described in detail below.
206 input_password output_password
208 The passwords for the input private key file (if present) and the
209 output private key file (if one will be created). The command line
210 options passin and passout override the configuration file values.
211 default_bits
213 This specifies the default key size in bits. If not specified then
214 512 is used. It is used if the -new option is used. It can be over‐
215 ridden by using the -newkey option.
216 default_keyfile
218 This is the default filename to write a private key to. If not
219 specified the key is written to standard output. This can be over‐
220 ridden by the -keyout option.
221 oid_file
223 This specifies a file containing additional OBJECT IDENTIFIERS.
224 Each line of the file should consist of the numerical form of the
225 object identifier followed by white space then the short name fol‐
226 lowed by white space and finally the long name.
227 oid_section
229 This specifies a section in the configuration file containing extra
230 object identifiers. Each line should consist of the short name of
231 the object identifier followed by = and the numerical form. The
232 short and long names are the same when this option is used.
233 RANDFILE
235 This specifies a filename in which random number seed information
236 is placed and read from, or an EGD socket (see RAND_egd(3)). It is
237 used for private key generation.
238 encrypt_key
240 If this is set to no then if a private key is generated it is not
241 encrypted. This is equivalent to the -nodes command line option.
242 For compatibility encrypt_rsa_key is an equivalent option.
243 default_md
245 This option specifies the digest algorithm to use. Possible values
246 include md5 sha1 mdc2. If not present then MD5 is used. This option
247 can be overridden on the command line.
248 string_mask
250 This option masks out the use of certain string types in certain
251 fields. Most users will not need to change this option.
252 It can be set to several values default which is also the default
254 option uses PrintableStrings, T61Strings and BMPStrings if the pkix
255 value is used then only PrintableStrings and BMPStrings will be
256 used. This follows the PKIX recommendation in RFC2459. If the
257 utf8only option is used then only UTF8Strings will be used: this is
258 the PKIX recommendation in RFC2459 after 2003. Finally the nombstr
259 option just uses PrintableStrings and T61Strings: certain software
260 has problems with BMPStrings and UTF8Strings: in particular Net‐
261 scape.
262 req_extensions
264 this specifies the configuration file section containing a list of
265 extensions to add to the certificate request. It can be overridden
266 by the -reqexts command line switch.
267 x509_extensions
269 this specifies the configuration file section containing a list of
270 extensions to add to certificate generated when the -x509 switch is
271 used. It can be overridden by the -extensions command line switch.
272 prompt
274 if set to the value no this disables prompting of certificate
275 fields and just takes values from the config file directly. It also
276 changes the expected format of the distinguished_name and
277 attributes sections.
278 utf8
280 if set to the value yes then field values to be interpreted as UTF8
281 strings, by default they are interpreted as ASCII. This means that
282 the field values, whether prompted from a terminal or obtained from
283 a configuration file, must be valid UTF8 strings.
284 attributes
286 this specifies the section containing any request attributes: its
287 format is the same as distinguished_name. Typically these may con‐
288 tain the challengePassword or unstructuredName types. They are cur‐
289 rently ignored by OpenSSL's request signing utilities but some CAs
290 might want them.
291 distinguished_name
293 This specifies the section containing the distinguished name fields
294 to prompt for when generating a certificate or certificate request.
295 The format is described in the next section.
296
298 There are two separate formats for the distinguished name and attribute
299 sections. If the prompt option is set to no then these sections just
300 consist of field names and values: for example,
301 CN=My Name
303 OU=My Organization
304 emailAddress=someone@somewhere.org
305 This allows external programs (e.g. GUI based) to generate a template
307 file with all the field names and values and just pass it to req. An
308 example of this kind of configuration file is contained in the EXAMPLES
309 section.
310 Alternatively if the prompt option is absent or not set to no then the
312 file contains field prompting information. It consists of lines of the
313 form:
314 fieldName="prompt"
316 fieldName_default="default field value"
317 fieldName_min= 2
318 fieldName_max= 4
319 "fieldName" is the field name being used, for example commonName (or
321 CN). The "prompt" string is used to ask the user to enter the relevant
322 details. If the user enters nothing then the default value is used if
323 no default value is present then the field is omitted. A field can
324 still be omitted if a default value is present if the user just enters
325 the '.' character.
326 The number of characters entered must be between the fieldName_min and
328 fieldName_max limits: there may be additional restrictions based on the
329 field being used (for example countryName can only ever be two charac‐
330 ters long and must fit in a PrintableString).
331 Some fields (such as organizationName) can be used more than once in a
333 DN. This presents a problem because configuration files will not recog‐
334 nize the same name occurring twice. To avoid this problem if the field‐
335 Name contains some characters followed by a full stop they will be
336 ignored. So for example a second organizationName can be input by call‐
337 ing it "1.organizationName".
338 The actual permitted field names are any object identifier short or
340 long names. These are compiled into OpenSSL and include the usual val‐
341 ues such as commonName, countryName, localityName, organizationName,
342 organizationUnitName, stateOrProvinceName. Additionally emailAddress is
343 include as well as name, surname, givenName initials and dnQualifier.
344 Additional object identifiers can be defined with the oid_file or
346 oid_section options in the configuration file. Any additional fields
347 will be treated as though they were a DirectoryString.
348
350 Examine and verify certificate request:
351 openssl req -in req.pem -text -verify -noout
353 Create a private key and then generate a certificate request from it:
355 openssl genrsa -out key.pem 1024
357 openssl req -new -key key.pem -out req.pem
358 The same but just using req:
360 openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
362 Generate a self signed root certificate:
364 openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
366 Example of a file pointed to by the oid_file option:
368 1.2.3.4 shortName A longer Name
370 1.2.3.6 otherName Other longer Name
371 Example of a section pointed to by oid_section making use of variable
373 expansion:
374 testoid1=1.2.3.5
376 testoid2=${testoid1}.6
377 Sample configuration file prompting for field values:
379 [ req ]
381 default_bits = 1024
382 default_keyfile = privkey.pem
383 distinguished_name = req_distinguished_name
384 attributes = req_attributes
385 x509_extensions = v3_ca
386 dirstring_type = nobmp
388 [ req_distinguished_name ]
390 countryName = Country Name (2 letter code)
391 countryName_default = AU
392 countryName_min = 2
393 countryName_max = 2
394 localityName = Locality Name (eg, city)
396 organizationalUnitName = Organizational Unit Name (eg, section)
398 commonName = Common Name (eg, YOUR name)
400 commonName_max = 64
401 emailAddress = Email Address
403 emailAddress_max = 40
404 [ req_attributes ]
406 challengePassword = A challenge password
407 challengePassword_min = 4
408 challengePassword_max = 20
409 [ v3_ca ]
411 subjectKeyIdentifier=hash
413 authorityKeyIdentifier=keyid:always,issuer:always
414 basicConstraints = CA:true
415 Sample configuration containing all field values:
417 RANDFILE = $ENV::HOME/.rnd
419 [ req ]
421 default_bits = 1024
422 default_keyfile = keyfile.pem
423 distinguished_name = req_distinguished_name
424 attributes = req_attributes
425 prompt = no
426 output_password = mypass
427 [ req_distinguished_name ]
429 C = GB
430 ST = Test State or Province
431 L = Test Locality
432 O = Organization Name
433 OU = Organizational Unit Name
434 CN = Common Name
435 emailAddress = test@email.address
436 [ req_attributes ]
438 challengePassword = A challenge password
439
441 The header and footer lines in the PEM format are normally:
442 -----BEGIN CERTIFICATE REQUEST-----
444 -----END CERTIFICATE REQUEST-----
445 some software (some versions of Netscape certificate server) instead
447 needs:
448 -----BEGIN NEW CERTIFICATE REQUEST-----
450 -----END NEW CERTIFICATE REQUEST-----
451 which is produced with the -newhdr option but is otherwise compatible.
453 Either form is accepted transparently on input.
454 The certificate requests generated by Xenroll with MSIE have extensions
456 added. It includes the keyUsage extension which determines the type of
457 key (signature only or general purpose) and any additional OIDs entered
458 by the script in an extendedKeyUsage extension.
459
461 The following messages are frequently asked about:
462 Using configuration from /some/path/openssl.cnf
464 Unable to load config info
465 This is followed some time later by...
467 unable to find 'distinguished_name' in config
469 problems making Certificate Request
470 The first error message is the clue: it can't find the configuration
472 file! Certain operations (like examining a certificate request) don't
473 need a configuration file so its use isn't enforced. Generation of cer‐
474 tificates or requests however does need a configuration file. This
475 could be regarded as a bug.
476 Another puzzling message is this:
478 Attributes:
480 a0:00
481 this is displayed when no attributes are present and the request
483 includes the correct empty SET OF structure (the DER encoding of which
484 is 0xa0 0x00). If you just see:
485 Attributes:
487 then the SET OF is missing and the encoding is technically invalid (but
489 it is tolerated). See the description of the command line option
490 -asn1-kludge for more information.
491
493 The variable OPENSSL_CONF if defined allows an alternative configura‐
494 tion file location to be specified, it will be overridden by the -con‐
495 fig command line switch if it is present. For compatibility reasons the
496 SSLEAY_CONF environment variable serves the same purpose but its use is
497 discouraged.
498
500 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it
501 effectively treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have
502 similar behaviour. This can cause problems if you need characters that
503 aren't available in PrintableStrings and you don't want to or can't use
504 BMPStrings.
505 As a consequence of the T61String handling the only correct way to rep‐
507 resent accented characters in OpenSSL is to use a BMPString: unfortu‐
508 nately Netscape currently chokes on these. If you have to use accented
509 characters with Netscape and MSIE then you currently need to use the
510 invalid T61String form.
511 The current prompting is not very friendly. It doesn't allow you to
513 confirm what you've just entered. Other things like extensions in cer‐
514 tificate requests are statically defined in the configuration file.
515 Some of these: like an email address in subjectAltName should be input
516 by the user.
517
519 x509(1), ca(1), genrsa(1), gendsa(1), config(5)
5200.9.8b 2005-07-15 REQ(1)