Finish off the X509_ATTRIBUTE string stuff.
[openssl.git] / doc / man / req.pod
1
2 =pod
3
4 =head1 NAME
5
6 req - PKCS#10 certificate and certificate generating utility.
7
8 =head1 SYNOPSIS
9
10 B<openssl> B<req>
11 [B<-inform PEM|DER>]
12 [B<-outform PEM|DER>]
13 [B<-in filename>]
14 [B<-passin password>]
15 [B<-envpassin var>]
16 [B<-out filename>]
17 [B<-passout password>]
18 [B<-envpassout var>]
19 [B<-text>]
20 [B<-noout>]
21 [B<-verify>]
22 [B<-modulus>]
23 [B<-new>]
24 [B<-newkey rsa:bits>]
25 [B<-newkey dsa:file>]
26 [B<-nodes>]
27 [B<-key filename>]
28 [B<-keyform PEM|DER>]
29 [B<-keyout filename>]
30 [B<-[md5|sha1|md2|mdc2]>]
31 [B<-config filename>]
32 [B<-x509>]
33 [B<-days n>]
34 [B<-noasn1-kludge>]
35 [B<-extensions section>]
36 [B<-reqexts section>]
37
38 =head1 DESCRIPTION
39
40 The B<req> command primarily creates and processes certificate requests
41 in PKCS#10 format. It can additionally create self signed certificates
42 for use as root CAs for example.
43
44 =head1 COMMAND OPTIONS
45
46 =over 4
47
48 =item B<-inform DER|PEM>
49
50 This specifies the input format. The B<DER> option uses an ASN1 DER encoded
51 form compatible with the PKCS#10. The B<PEM> form is the default format: it
52 consists of the B<DER> format base64 encoded with additional header and
53 footer lines.
54
55 =item B<-outform DER|PEM>
56
57 This specifies the output format, the options have the same meaning as the 
58 B<-inform> option.
59
60 =item B<-in filename>
61
62 This specifies the input filename to read a request from or standard input
63 if this option is not specified. A request is only read if the creation
64 options (B<-new> and B<-newkey>) are not specified.
65
66 =item B<-passin password>
67
68 the input file password. Since certain utilities like "ps" make the command line
69 visible this option should be used with caution.
70
71 =item B<-envpassin var>
72
73 read the input file password from the environment variable B<var>.
74
75 =item B<-out filename>
76
77 This specifies the output filename to write to or standard output by
78 default.
79
80 =item B<-passout password>
81
82 the output file password. Since certain utilities like "ps" make the command line
83 visible this option should be used with caution.
84
85 =item B<-envpassout var>
86
87 read the output file password from the environment variable B<var>.
88
89 =item B<-text>
90
91 prints out the certificate request in text form.
92
93 =item B<-noout>
94
95 this option prevents output of the encoded version of the request.
96
97 =item B<-modulus>
98
99 this option prints out the value of the modulus of the public key
100 contained in the request.
101
102 =item B<-verify>
103
104 verifies the signature on the request.
105
106 =item B<-new>
107
108 this option generates a new certificate request. It will prompt
109 the user for the relevant field values. The actual fields
110 prompted for and their maximum and minimum sizes are specified
111 in the configuration file and any requested extensions.
112
113 If the B<-key> option is not used it will generate a new RSA private
114 key using information specified in the configuration file.
115
116 =item B<-newkey arg>
117
118 this option creates a new certificate request and a new private
119 key. The argument takes one of two forms. B<rsa:nbits>, where
120 B<nbits> is the number of bits, generates an RSA key B<nbits>
121 in size. B<dsa:filename> generates a DSA key using the parameters
122 in the file B<filename>.
123
124 =item B<-key filename>
125
126 This specifies the file to read the private key from. It also
127 accepts PKCS#8 format private keys for PEM format files.
128
129 =item B<-keyform PEM|DER>
130
131 the format of the private key file specified in the B<-key>
132 argument. PEM is the default.
133
134 =item B<-keyout filename>
135
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 =item B<-nodes>
141
142 if this option is specified then if a private key is created it
143 will not be encrypted.
144
145 =item B<-[md5|sha1|md2|mdc2]>
146
147 this specifies the message digest to sign the request with. This
148 overrides the digest algorithm specified in the configuration file.
149 This option is ignored for DSA requests: they always use SHA1.
150
151 =item B<-config filename>
152
153 this allows an alternative configuration file to be specified,
154 this overrides the compile time filename or any specified in
155 the B<OPENSSL_CONF> environment variable.
156
157 =item B<-x509>
158
159 this option outputs a self signed certificate instead of a certificate
160 request. This is typically used to generate a test certificate or
161 a self signed root CA. The extensions added to the certificate
162 (if any) are specified in the configuration file.
163
164 =item B<-days n>
165
166 when the B<-x509> option is being used this specifies the number of
167 days to certify the certificate for. The default is 30 days.
168
169 =item B<-extensions section>
170 =item B<-reqexts section>
171
172 these options specify alternative sections to include certificate
173 extensions (if the B<-x509> option is present) or certificate
174 request extensions. This allows several different sections to
175 be used in the same configuration file to specify requests for
176 a variety of purposes.
177
178 =item B<-asn1-kludge>
179
180 by default the B<req> command outputs certificate requests containing
181 no attributes in the correct PKCS#10 format. However certain CAs will only
182 accept requests containing no attributes in an invalid form: this
183 option produces this invalid format.
184
185 More precisely the B<Attributes> in a PKCS#10 certificate request
186 are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
187 if no attributes are present then they should be encoded as an
188 empty B<SET OF>. The invalid form does not include the empty
189 B<SET OF> whereas the correct form does.
190
191 It should be noted that very few CAs still require the use of this option.
192
193 =back
194
195 =head1 CONFIGURATION FILE FORMAT
196
197 The configuration options are specified in the B<req> section of
198 the configuration file. As with all configuration files if no
199 value is specified in the specific section (i.e. B<req>) then
200 the initial unnamed or B<default> section is searched too.
201
202 The options available are described in detail below.
203
204 =over 4
205
206 =item B<input_password output_password>
207
208 The passwords for the input private key file (if present) and
209 the output private key file (if one will be created). The
210 command line options B<passin>, B<envpassin>, B<passout> and
211 B<envpassout> override the configuration file values.
212
213 =item B<default_bits>
214
215 This specifies the default key size in bits. If not specified then
216 512 is used. It is used if the B<-new> option is used. It can be
217 overridden by using the B<-newkey> option.
218
219 =item B<default_keyfile>
220
221 This is the default filename to write a private key to. If not
222 specified the key is written to standard output. This can be
223 overridden by the B<-keyout> option.
224
225 =item B<oid_file>
226
227 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
228 Each line of the file should consist of the numerical form of the
229 object identifier followed by white space then the short name followed
230 by white space and finally the long name. 
231
232 =item B<oid_section>
233
234 This specifies a section in the configuration file containing extra
235 object identifiers. Each line should consist of the short name of the
236 object identifier followed by B<=> and the numerical form. The short
237 and long names are the same when this option is used.
238
239 =item B<RANDFILE>
240
241 This specifies a filename in which random number seed information is
242 placed and read from. It is used for private key generation.
243
244 =item B<encrypt_key>
245
246 If this is set to B<no> then if a private key is generated it is
247 B<not> encrypted. This is equivalent to the B<-nodes> command line
248 option. For compatibility B<encrypt_rsa_key> is an equivalent option.
249
250 =item B<default_md>
251
252 This option specifies the digest algorithm to use. Possible values
253 include B<md5 sha1 mdc2>. If not present then MD5 is used. This
254 option can be overridden on the command line.
255
256 =item B<string_mask>
257
258 This option masks out the use of certain string types in certain
259 fields. Most users will not need to change this option.
260
261 It can be set to several values B<default> which is also the default
262 option uses PrintableStrings, T61Strings and BMPStrings if the 
263 B<pkix> value is used then only PrintableStrings and BMPStrings will
264 be used. This follows the PKIX recommendation in RFC2459. If the
265 B<utf8only> option is used then only UTF8Strings will be used: this
266 is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
267 option just uses PrintableStrings and T61Strings: certain software has
268 problems with BMPStrings and UTF8Strings: in particular Netscape.
269
270 =item B<req_extensions>
271
272 this specifies the configuration file section containing a list of
273 extensions to add to the certificate request. It can be overridden
274 by the B<-reqexts> command line switch.
275
276 =item B<x509_extensions>
277
278 this specifies the configuration file section containing a list of
279 extensions to add to certificate generated when the B<-x509> switch
280 is used. It can be overridden by the B<-extensions> command line switch.
281
282 =item B<prompt>
283
284 if set to the value B<no> this disables prompting of certificate fields
285 and just takes values from the config file directly. It also changes the
286 expected format of the B<distinguished_name> and B<attributes> sections.
287
288 =item B<attributes>
289
290 this specifies the section containing any request attributes: its format
291 is the same as B<distinguished_name>. Typically these may contain the
292 challengePassword or unstructuredName types. They are currently ignored
293 by OpenSSL's request signing utilities but some CAs might want them.
294
295 =item B<distinguished_name>
296
297 This specifies the section containing the distinguished name fields to
298 prompt for when generating a certificate or certificate request. The format
299 is described in the next section.
300
301 =back
302
303 =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
304
305 There are two separate formats for the distinguished name and attribute
306 sections. If the B<prompt> option is set to B<no> then these sections
307 just consist of field names and values: for example,
308
309  CN=My Name
310  OU=My Organization
311  emailAddress=someone@somehere.org
312
313 This allows external programs (e.g. GUI based) to generate a template file
314 with all the field names and values and just pass it to B<req>. An example
315 of this kind of configuration files is contained in the B<EXAMPLES> section.
316
317 Alternatively if the B<prompt> option is absent or not set to B<no> the the
318 file contains field prompting information. It consists of lines of the form:
319
320  fieldName="prompt"
321  fieldName_default="default field value"
322  fieldName_min= 2
323  fieldName_max= 4
324
325 "fieldName" is the field name being used, for example commonName (or CN).
326 The "prompt" string is used to ask the user to enter the relevant
327 details. If the user enters nothing then the default value is used if no
328 default value is present then the field is omitted. A field can
329 still be omitted if a default value is present if the user just
330 enters the '.' character.
331
332 The number of characters entered must be between the fieldName_min and
333 fieldName_max limits: there may be additional restrictions based
334 on the field being used (for example countryName can only ever be
335 two characters long and must fit in a PrintableString).
336
337 Some fields (such as organizationName) can be used more than once
338 in a DN. This presents a problem because configuration files will
339 not recognize the same name occurring twice. To avoid this problem
340 if the fieldName contains an some characters followed by a full stop
341 they will be ignored. So for example a second organizationName can
342 be input by calling it "1.organizationName".
343
344 The actual permitted field names are any object identifier short or
345 long names. These are compiled into OpenSSL and include the usual
346 values such as commonName, countryName, localityName, organizationName,
347 organizationUnitName, stateOrPrivinceName. Additionally emailAddress
348 is include as well as name, surname, givenName initials and dnQualifier
349 are supported.
350
351 Additional object identifiers can be defined with the B<oid_file> or
352 B<oid_section> options in the configuration file. Any additional fields
353 will be treated as though they were a DirectoryString.
354
355
356 =head1 EXAMPLES
357
358 Examine and verify certificate request:
359
360  openssl req -in req.pem -text -verify -noout
361
362 Create a private key and then generate a certificate request from it:
363
364  openssl genrsa -out key.pem 1024
365  openssl req -new -key key.pem -out req.pem
366
367 The same but just using req:
368
369  openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
370
371 Generate a self signed root certificate:
372
373  openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
374
375 Example of a file pointed to by the B<oid_file> option:
376
377  1.2.3.4        shortName       A longer Name
378  1.2.3.6        otherName       Other longer Name
379
380 Example of a section pointed to by B<oid_section> making use of variable
381 expansion:
382
383  testoid1=1.2.3.5
384  testoid2=${testoid1}.6
385
386 Sample configuration file prompting for field values:
387
388  [ req ]
389  default_bits           = 1024
390  default_keyfile        = privkey.pem
391  distinguished_name     = req_distinguished_name
392  attributes             = req_attributes
393  x509_extensions        = v3_ca
394
395  dirstring_type = nobmp
396
397  [ req_distinguished_name ]
398  countryName                    = Country Name (2 letter code)
399  countryName_default            = AU
400  countryName_min                = 2
401  countryName_max                = 2
402
403  localityName                   = Locality Name (eg, city)
404
405  organizationalUnitName         = Organizational Unit Name (eg, section)
406
407  commonName                     = Common Name (eg, YOUR name)
408  commonName_max                 = 64
409
410  emailAddress                   = Email Address
411  emailAddress_max               = 40
412
413  [ req_attributes ]
414  challengePassword              = A challenge password
415  challengePassword_min          = 4
416  challengePassword_max          = 20
417
418  [ v3_ca ]
419
420  subjectKeyIdentifier=hash
421  authorityKeyIdentifier=keyid:always,issuer:always
422  basicConstraints = CA:true
423
424 Sample configuration containing all field values:
425
426
427  RANDFILE               = $ENV::HOME/.rnd
428
429  [ req ]
430  default_bits           = 1024
431  default_keyfile        = keyfile.pem
432  distinguished_name     = req_distinguished_name
433  attributes             = req_attributes
434  prompt                 = no
435  output_password        = mypass
436
437  [ req_distinguished_name ]
438  C                      = GB
439  ST                     = Test State or Province
440  L                      = Test Locality
441  O                      = Organization Name
442  OU                     = Organizational Unit Name
443  CN                     = Common Name
444  emailAddress           = test@email.address
445
446  [ req_attributes ]
447  challengePassword              = A challenge password
448
449
450 =head1 NOTES
451
452 The header and footer lines in the B<PEM> format are respectively:
453
454  -----BEGIN CERTIFICATE REQUEST----
455  -----END CERTIFICATE REQUEST----
456
457 some software (some versions of Netscape certificate server) instead needs:
458
459  -----BEGIN NEW CERTIFICATE REQUEST----
460  -----END NEW CERTIFICATE REQUEST----
461
462 but is otherwise compatible. Either form is accepted on input.
463
464 The certificate requests generated by B<Xenroll> with MSIE have extensions
465 added. It includes the B<keyUsage> extension which determines the type of
466 key (signature only or general purpose) and any additional OIDs entered
467 by the script in an extendedKeyUsage extension.
468
469 =head1 DIAGNOSTICS
470
471 The following messages are frequently asked about:
472
473         Using configuration from /some/path/openssl.cnf
474         Unable to load config info
475
476 This is followed some time later by...
477
478         unable to find 'distinguished_name' in config
479         problems making Certificate Request
480
481 The first error message is the clue: it can't find the configuration
482 file! Certain operations (like examining a certificate request) don't
483 need a configuration file so its use isn't enforced. Generation of
484 certificates or requests however does need a configuration file. This
485 could be regarded as a bug.
486
487 Another puzzling message is this:
488
489         Attributes:
490             a0:00
491
492 this is displayed when no attributes are present and the request includes
493 the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
494 0x00). If you just see:
495
496         Attributes:
497
498 then the B<SET OF> is missing and the encoding is technically invalid (but
499 it is tolerated). See the description of the command line option B<-asn1-kludge>
500 for more information.
501
502 =head1 ENVIRONMENT VARIABLES
503
504 The variable B<OPENSSL_CONF> if defined allows an alternative configuration
505 file location to be specified, it will be overridden by the B<-config> command
506 line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
507 environment variable serves the same purpose but its use is discouraged.
508
509 =head1 BUGS
510
511 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
512 treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
513 This can cause problems if you need characters that aren't available in
514 PrintableStrings and you don't want to or can't use BMPStrings.
515
516 As a consequence of the T61String handling the only correct way to represent
517 accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
518 currently chokes on these. If you have to use accented characters with Netscape
519 and MSIE then you currently need to use the invalid T61String form.
520
521 The current prompting is not very friendly. It doesn't allow you to confirm what
522 you've just entered. Other things like extensions in certificate requests are
523 statically defined in the configuration file. Some of these: like an email
524 address in subjectAltName should be input by the user.
525
526 =head1 SEE ALSO
527
528 x509(1), ca(1), genrsa(1), gendsa(1), config(5)
529
530 =cut