46bbfe614e61c28c34c850ceac6cd984ef1b56e4
[openssl.git] / doc / apps / req.pod
1
2 =pod
3
4 =head1 NAME
5
6 req - PKCS#10 certificate request 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 arg>]
15 [B<-out filename>]
16 [B<-passout arg>]
17 [B<-text>]
18 [B<-pubkey>]
19 [B<-noout>]
20 [B<-verify>]
21 [B<-modulus>]
22 [B<-new>]
23 [B<-rand file(s)>]
24 [B<-newkey rsa:bits>]
25 [B<-newkey alg:file>]
26 [B<-nodes>]
27 [B<-key filename>]
28 [B<-keyform PEM|DER>]
29 [B<-keyout filename>]
30 [B<-keygen_engine id>]
31 [B<-[digest]>]
32 [B<-config filename>]
33 [B<-multivalue-rdn>]
34 [B<-x509>]
35 [B<-days n>]
36 [B<-set_serial n>]
37 [B<-asn1-kludge>]
38 [B<-no-asn1-kludge>]
39 [B<-newhdr>]
40 [B<-extensions section>]
41 [B<-reqexts section>]
42 [B<-utf8>]
43 [B<-nameopt>]
44 [B<-reqopt>]
45 [B<-subject>]
46 [B<-subj arg>]
47 [B<-batch>]
48 [B<-verbose>]
49 [B<-engine id>]
50
51 =head1 DESCRIPTION
52
53 The B<req> command primarily creates and processes certificate requests
54 in PKCS#10 format. It can additionally create self signed certificates
55 for use as root CAs for example.
56
57 =head1 COMMAND OPTIONS
58
59 =over 4
60
61 =item B<-inform DER|PEM>
62
63 This specifies the input format. The B<DER> option uses an ASN1 DER encoded
64 form compatible with the PKCS#10. The B<PEM> form is the default format: it
65 consists of the B<DER> format base64 encoded with additional header and
66 footer lines.
67
68 =item B<-outform DER|PEM>
69
70 This specifies the output format, the options have the same meaning as the 
71 B<-inform> option.
72
73 =item B<-in filename>
74
75 This specifies the input filename to read a request from or standard input
76 if this option is not specified. A request is only read if the creation
77 options (B<-new> and B<-newkey>) are not specified.
78
79 =item B<-passin arg>
80
81 the input file password source. For more information about the format of B<arg>
82 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
83
84 =item B<-out filename>
85
86 This specifies the output filename to write to or standard output by
87 default.
88
89 =item B<-passout arg>
90
91 the output file password source. For more information about the format of B<arg>
92 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
93
94 =item B<-text>
95
96 prints out the certificate request in text form.
97
98 =item B<-subject>
99
100 prints out the request subject (or certificate subject if B<-x509> is
101 specified)
102
103 =item B<-pubkey>
104
105 outputs the public key.
106
107 =item B<-noout>
108
109 this option prevents output of the encoded version of the request.
110
111 =item B<-modulus>
112
113 this option prints out the value of the modulus of the public key
114 contained in the request.
115
116 =item B<-verify>
117
118 verifies the signature on the request.
119
120 =item B<-new>
121
122 this option generates a new certificate request. It will prompt
123 the user for the relevant field values. The actual fields
124 prompted for and their maximum and minimum sizes are specified
125 in the configuration file and any requested extensions.
126
127 If the B<-key> option is not used it will generate a new RSA private
128 key using information specified in the configuration file.
129
130 =item B<-rand file(s)>
131
132 a file or files containing random data used to seed the random number
133 generator, or an EGD socket (see L<RAND_egd(3)>).
134 Multiple files can be specified separated by a OS-dependent character.
135 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
136 all others.
137
138 =item B<-newkey arg>
139
140 this option creates a new certificate request and a new private
141 key. The argument takes one of several forms. B<rsa:nbits>, where
142 B<nbits> is the number of bits, generates an RSA key B<nbits>
143 in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified,
144 the default key size, specified in the configuration file is used.
145
146 All other algorithms support the B<-newkey alg:file> form, where file may be
147 an algorithm parameter file, created by the B<genpkey -genparam> command
148 or and X.509 certificate for a key with appropriate algorithm.
149
150 B<param:file> generates a key using the parameter file or certificate B<file>,
151 the algorithm is determined by the parameters. B<algname:file> use algorithm
152 B<algname> and parameter file B<file>: the two algorithms must match or an
153 error occurs. B<algname> just uses algorithm B<algname>, and parameters,
154 if necessary should be specified via B<-pkeyopt> parameter.
155
156 B<dsa:filename> generates a DSA key using the parameters
157 in the file B<filename>. B<ec:filename> generates EC key (usable both with
158 ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R
159 34.10-2001 key (requires B<ccgost> engine configured in the configuration
160 file). If just B<gost2001> is specified a parameter set should be
161 specified by B<-pkeyopt paramset:X>
162
163
164 =item B<-pkeyopt opt:value>
165
166 set the public key algorithm option B<opt> to B<value>. The precise set of
167 options supported depends on the public key algorithm used and its
168 implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page
169 for more details.
170
171 =item B<-key filename>
172
173 This specifies the file to read the private key from. It also
174 accepts PKCS#8 format private keys for PEM format files.
175
176 =item B<-keyform PEM|DER>
177
178 the format of the private key file specified in the B<-key>
179 argument. PEM is the default.
180
181 =item B<-keyout filename>
182
183 this gives the filename to write the newly created private key to.
184 If this option is not specified then the filename present in the
185 configuration file is used.
186
187 =item B<-nodes>
188
189 if this option is specified then if a private key is created it
190 will not be encrypted.
191
192 =item B<-[digest]>
193
194 this specifies the message digest to sign the request.
195 Any digest supported by the OpenSSL B<dgst> command can be used.
196 This overrides the digest algorithm specified in
197 the configuration file.
198
199 Some public key algorithms may override this choice. For instance, DSA
200 signatures always use SHA1, GOST R 34.10 signatures always use
201 GOST R 34.11-94 (B<-md_gost94>).
202
203 =item B<-config filename>
204
205 this allows an alternative configuration file to be specified,
206 this overrides the compile time filename or any specified in
207 the B<OPENSSL_CONF> environment variable.
208
209 =item B<-subj arg>
210
211 sets subject name for new request or supersedes the subject name
212 when processing a request.
213 The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
214 characters may be escaped by \ (backslash), no spaces are skipped.
215
216 =item B<-multivalue-rdn>
217
218 this option causes the -subj argument to be interpreted with full
219 support for multivalued RDNs. Example:
220
221 I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
222
223 If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
224
225 =item B<-x509>
226
227 this option outputs a self signed certificate instead of a certificate
228 request. This is typically used to generate a test certificate or
229 a self signed root CA. The extensions added to the certificate
230 (if any) are specified in the configuration file. Unless specified
231 using the B<set_serial> option, a large random number will be used for
232 the serial number.
233
234 =item B<-days n>
235
236 when the B<-x509> option is being used this specifies the number of
237 days to certify the certificate for. The default is 30 days.
238
239 =item B<-set_serial n>
240
241 serial number to use when outputting a self signed certificate. This
242 may be specified as a decimal value or a hex value if preceded by B<0x>.
243 It is possible to use negative serial numbers but this is not recommended.
244
245 =item B<-extensions section>
246
247 =item B<-reqexts section>
248
249 these options specify alternative sections to include certificate
250 extensions (if the B<-x509> option is present) or certificate
251 request extensions. This allows several different sections to
252 be used in the same configuration file to specify requests for
253 a variety of purposes.
254
255 =item B<-utf8>
256
257 this option causes field values to be interpreted as UTF8 strings, by 
258 default they are interpreted as ASCII. This means that the field
259 values, whether prompted from a terminal or obtained from a
260 configuration file, must be valid UTF8 strings.
261
262 =item B<-nameopt option>
263
264 option which determines how the subject or issuer names are displayed. The
265 B<option> argument can be a single option or multiple options separated by
266 commas.  Alternatively the B<-nameopt> switch may be used more than once to
267 set multiple options. See the L<x509(1)> manual page for details.
268
269 =item B<-reqopt>
270
271 customise the output format used with B<-text>. The B<option> argument can be
272 a single option or multiple options separated by commas. 
273
274 See discussion of the  B<-certopt> parameter in the L<x509(1)>
275 command.
276
277
278 =item B<-asn1-kludge>
279
280 by default the B<req> command outputs certificate requests containing
281 no attributes in the correct PKCS#10 format. However certain CAs will only
282 accept requests containing no attributes in an invalid form: this
283 option produces this invalid format.
284
285 More precisely the B<Attributes> in a PKCS#10 certificate request
286 are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
287 if no attributes are present then they should be encoded as an
288 empty B<SET OF>. The invalid form does not include the empty
289 B<SET OF> whereas the correct form does.
290
291 It should be noted that very few CAs still require the use of this option.
292
293 =item B<-no-asn1-kludge>
294
295 Reverses effect of B<-asn1-kludge>
296
297 =item B<-newhdr>
298
299 Adds the word B<NEW> to the PEM file header and footer lines on the outputted
300 request. Some software (Netscape certificate server) and some CAs need this.
301
302 =item B<-batch>
303
304 non-interactive mode.
305
306 =item B<-verbose>
307
308 print extra details about the operations being performed.
309
310 =item B<-engine id>
311
312 specifying an engine (by its unique B<id> string) will cause B<req>
313 to attempt to obtain a functional reference to the specified engine,
314 thus initialising it if needed. The engine will then be set as the default
315 for all available algorithms.
316
317 =item B<-keygen_engine id>
318
319 specifies an engine (by its unique B<id> string) which would be used
320 for key generation operations.
321
322 =back
323
324 =head1 CONFIGURATION FILE FORMAT
325
326 The configuration options are specified in the B<req> section of
327 the configuration file. As with all configuration files if no
328 value is specified in the specific section (i.e. B<req>) then
329 the initial unnamed or B<default> section is searched too.
330
331 The options available are described in detail below.
332
333 =over 4
334
335 =item B<input_password output_password>
336
337 The passwords for the input private key file (if present) and
338 the output private key file (if one will be created). The
339 command line options B<passin> and B<passout> override the
340 configuration file values.
341
342 =item B<default_bits>
343
344 This specifies the default key size in bits. If not specified then
345 512 is used. It is used if the B<-new> option is used. It can be
346 overridden by using the B<-newkey> option.
347
348 =item B<default_keyfile>
349
350 This is the default filename to write a private key to. If not
351 specified the key is written to standard output. This can be
352 overridden by the B<-keyout> option.
353
354 =item B<oid_file>
355
356 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
357 Each line of the file should consist of the numerical form of the
358 object identifier followed by white space then the short name followed
359 by white space and finally the long name. 
360
361 =item B<oid_section>
362
363 This specifies a section in the configuration file containing extra
364 object identifiers. Each line should consist of the short name of the
365 object identifier followed by B<=> and the numerical form. The short
366 and long names are the same when this option is used.
367
368 =item B<RANDFILE>
369
370 This specifies a filename in which random number seed information is
371 placed and read from, or an EGD socket (see L<RAND_egd(3)>).
372 It is used for private key generation.
373
374 =item B<encrypt_key>
375
376 If this is set to B<no> then if a private key is generated it is
377 B<not> encrypted. This is equivalent to the B<-nodes> command line
378 option. For compatibility B<encrypt_rsa_key> is an equivalent option.
379
380 =item B<default_md>
381
382 This option specifies the digest algorithm to use.
383 Any digest supported by the OpenSSL B<dgst> command can be used.
384 If not present then MD5 is used.
385 This option can be overridden on the command line.
386
387 =item B<string_mask>
388
389 This option masks out the use of certain string types in certain
390 fields. Most users will not need to change this option.
391
392 It can be set to several values B<default> which is also the default
393 option uses PrintableStrings, T61Strings and BMPStrings if the 
394 B<pkix> value is used then only PrintableStrings and BMPStrings will
395 be used. This follows the PKIX recommendation in RFC2459. If the
396 B<utf8only> option is used then only UTF8Strings will be used: this
397 is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
398 option just uses PrintableStrings and T61Strings: certain software has
399 problems with BMPStrings and UTF8Strings: in particular Netscape.
400
401 =item B<req_extensions>
402
403 this specifies the configuration file section containing a list of
404 extensions to add to the certificate request. It can be overridden
405 by the B<-reqexts> command line switch. See the 
406 L<x509v3_config(5)> manual page for details of the
407 extension section format.
408
409 =item B<x509_extensions>
410
411 this specifies the configuration file section containing a list of
412 extensions to add to certificate generated when the B<-x509> switch
413 is used. It can be overridden by the B<-extensions> command line switch.
414
415 =item B<prompt>
416
417 if set to the value B<no> this disables prompting of certificate fields
418 and just takes values from the config file directly. It also changes the
419 expected format of the B<distinguished_name> and B<attributes> sections.
420
421 =item B<utf8>
422
423 if set to the value B<yes> then field values to be interpreted as UTF8
424 strings, by default they are interpreted as ASCII. This means that
425 the field values, whether prompted from a terminal or obtained from a
426 configuration file, must be valid UTF8 strings.
427
428 =item B<attributes>
429
430 this specifies the section containing any request attributes: its format
431 is the same as B<distinguished_name>. Typically these may contain the
432 challengePassword or unstructuredName types. They are currently ignored
433 by OpenSSL's request signing utilities but some CAs might want them.
434
435 =item B<distinguished_name>
436
437 This specifies the section containing the distinguished name fields to
438 prompt for when generating a certificate or certificate request. The format
439 is described in the next section.
440
441 =back
442
443 =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
444
445 There are two separate formats for the distinguished name and attribute
446 sections. If the B<prompt> option is set to B<no> then these sections
447 just consist of field names and values: for example,
448
449  CN=My Name
450  OU=My Organization
451  emailAddress=someone@somewhere.org
452
453 This allows external programs (e.g. GUI based) to generate a template file
454 with all the field names and values and just pass it to B<req>. An example
455 of this kind of configuration file is contained in the B<EXAMPLES> section.
456
457 Alternatively if the B<prompt> option is absent or not set to B<no> then the
458 file contains field prompting information. It consists of lines of the form:
459
460  fieldName="prompt"
461  fieldName_default="default field value"
462  fieldName_min= 2
463  fieldName_max= 4
464
465 "fieldName" is the field name being used, for example commonName (or CN).
466 The "prompt" string is used to ask the user to enter the relevant
467 details. If the user enters nothing then the default value is used if no
468 default value is present then the field is omitted. A field can
469 still be omitted if a default value is present if the user just
470 enters the '.' character.
471
472 The number of characters entered must be between the fieldName_min and
473 fieldName_max limits: there may be additional restrictions based
474 on the field being used (for example countryName can only ever be
475 two characters long and must fit in a PrintableString).
476
477 Some fields (such as organizationName) can be used more than once
478 in a DN. This presents a problem because configuration files will
479 not recognize the same name occurring twice. To avoid this problem
480 if the fieldName contains some characters followed by a full stop
481 they will be ignored. So for example a second organizationName can
482 be input by calling it "1.organizationName".
483
484 The actual permitted field names are any object identifier short or
485 long names. These are compiled into OpenSSL and include the usual
486 values such as commonName, countryName, localityName, organizationName,
487 organizationalUnitName, stateOrProvinceName. Additionally emailAddress
488 is include as well as name, surname, givenName initials and dnQualifier.
489
490 Additional object identifiers can be defined with the B<oid_file> or
491 B<oid_section> options in the configuration file. Any additional fields
492 will be treated as though they were a DirectoryString.
493
494
495 =head1 EXAMPLES
496
497 Examine and verify certificate request:
498
499  openssl req -in req.pem -text -verify -noout
500
501 Create a private key and then generate a certificate request from it:
502
503  openssl genrsa -out key.pem 2048
504  openssl req -new -key key.pem -out req.pem
505
506 The same but just using req:
507
508  openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
509
510 Generate a self signed root certificate:
511
512  openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
513
514 Example of a file pointed to by the B<oid_file> option:
515
516  1.2.3.4        shortName       A longer Name
517  1.2.3.6        otherName       Other longer Name
518
519 Example of a section pointed to by B<oid_section> making use of variable
520 expansion:
521
522  testoid1=1.2.3.5
523  testoid2=${testoid1}.6
524
525 Sample configuration file prompting for field values:
526
527  [ req ]
528  default_bits           = 2048
529  default_keyfile        = privkey.pem
530  distinguished_name     = req_distinguished_name
531  attributes             = req_attributes
532  req_extensions         = v3_ca
533
534  dirstring_type = nobmp
535
536  [ req_distinguished_name ]
537  countryName                    = Country Name (2 letter code)
538  countryName_default            = AU
539  countryName_min                = 2
540  countryName_max                = 2
541
542  localityName                   = Locality Name (eg, city)
543
544  organizationalUnitName         = Organizational Unit Name (eg, section)
545
546  commonName                     = Common Name (eg, YOUR name)
547  commonName_max                 = 64
548
549  emailAddress                   = Email Address
550  emailAddress_max               = 40
551
552  [ req_attributes ]
553  challengePassword              = A challenge password
554  challengePassword_min          = 4
555  challengePassword_max          = 20
556
557  [ v3_ca ]
558
559  subjectKeyIdentifier=hash
560  authorityKeyIdentifier=keyid:always,issuer:always
561  basicConstraints = CA:true
562
563 Sample configuration containing all field values:
564
565
566  RANDFILE               = $ENV::HOME/.rnd
567
568  [ req ]
569  default_bits           = 2048
570  default_keyfile        = keyfile.pem
571  distinguished_name     = req_distinguished_name
572  attributes             = req_attributes
573  prompt                 = no
574  output_password        = mypass
575
576  [ req_distinguished_name ]
577  C                      = GB
578  ST                     = Test State or Province
579  L                      = Test Locality
580  O                      = Organization Name
581  OU                     = Organizational Unit Name
582  CN                     = Common Name
583  emailAddress           = test@email.address
584
585  [ req_attributes ]
586  challengePassword              = A challenge password
587
588
589 =head1 NOTES
590
591 The header and footer lines in the B<PEM> format are normally:
592
593  -----BEGIN CERTIFICATE REQUEST-----
594  -----END CERTIFICATE REQUEST-----
595
596 some software (some versions of Netscape certificate server) instead needs:
597
598  -----BEGIN NEW CERTIFICATE REQUEST-----
599  -----END NEW CERTIFICATE REQUEST-----
600
601 which is produced with the B<-newhdr> option but is otherwise compatible.
602 Either form is accepted transparently on input.
603
604 The certificate requests generated by B<Xenroll> with MSIE have extensions
605 added. It includes the B<keyUsage> extension which determines the type of
606 key (signature only or general purpose) and any additional OIDs entered
607 by the script in an extendedKeyUsage extension.
608
609 =head1 DIAGNOSTICS
610
611 The following messages are frequently asked about:
612
613         Using configuration from /some/path/openssl.cnf
614         Unable to load config info
615
616 This is followed some time later by...
617
618         unable to find 'distinguished_name' in config
619         problems making Certificate Request
620
621 The first error message is the clue: it can't find the configuration
622 file! Certain operations (like examining a certificate request) don't
623 need a configuration file so its use isn't enforced. Generation of
624 certificates or requests however does need a configuration file. This
625 could be regarded as a bug.
626
627 Another puzzling message is this:
628
629         Attributes:
630             a0:00
631
632 this is displayed when no attributes are present and the request includes
633 the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
634 0x00). If you just see:
635
636         Attributes:
637
638 then the B<SET OF> is missing and the encoding is technically invalid (but
639 it is tolerated). See the description of the command line option B<-asn1-kludge>
640 for more information.
641
642 =head1 ENVIRONMENT VARIABLES
643
644 The variable B<OPENSSL_CONF> if defined allows an alternative configuration
645 file location to be specified, it will be overridden by the B<-config> command
646 line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
647 environment variable serves the same purpose but its use is discouraged.
648
649 =head1 BUGS
650
651 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
652 treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
653 This can cause problems if you need characters that aren't available in
654 PrintableStrings and you don't want to or can't use BMPStrings.
655
656 As a consequence of the T61String handling the only correct way to represent
657 accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
658 currently chokes on these. If you have to use accented characters with Netscape
659 and MSIE then you currently need to use the invalid T61String form.
660
661 The current prompting is not very friendly. It doesn't allow you to confirm what
662 you've just entered. Other things like extensions in certificate requests are
663 statically defined in the configuration file. Some of these: like an email
664 address in subjectAltName should be input by the user.
665
666 =head1 SEE ALSO
667
668 L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
669 L<gendsa(1)>, L<config(5)>,
670 L<x509v3_config(5)> 
671
672 =cut