Add copy_extensions option to 'ca' utility.
[openssl.git] / doc / apps / ca.pod
1
2 =pod
3
4 =head1 NAME
5
6 ca - sample minimal CA application
7
8 =head1 SYNOPSIS
9
10 B<openssl> B<ca>
11 [B<-verbose>]
12 [B<-config filename>]
13 [B<-name section>]
14 [B<-gencrl>]
15 [B<-revoke file>]
16 [B<-subj arg>]
17 [B<-crldays days>]
18 [B<-crlhours hours>]
19 [B<-crlexts section>]
20 [B<-startdate date>]
21 [B<-enddate date>]
22 [B<-days arg>]
23 [B<-md arg>]
24 [B<-policy arg>]
25 [B<-keyfile arg>]
26 [B<-key arg>]
27 [B<-passin arg>]
28 [B<-cert file>]
29 [B<-in file>]
30 [B<-out file>]
31 [B<-notext>]
32 [B<-outdir dir>]
33 [B<-infiles>]
34 [B<-spkac file>]
35 [B<-ss_cert file>]
36 [B<-preserveDN>]
37 [B<-batch>]
38 [B<-msie_hack>]
39 [B<-extensions section>]
40 [B<-extfile section>]
41
42 =head1 DESCRIPTION
43
44 The B<ca> command is a minimal CA application. It can be used
45 to sign certificate requests in a variety of forms and generate
46 CRLs it also maintains a text database of issued certificates
47 and their status.
48
49 The options descriptions will be divided into each purpose.
50
51 =head1 CA OPTIONS
52
53 =over 4
54
55 =item B<-config filename>
56
57 specifies the configuration file to use.
58
59 =item B<-in filename>
60
61 an input filename containing a single certificate request to be
62 signed by the CA.
63
64 =item B<-ss_cert filename>
65
66 a single self signed certificate to be signed by the CA.
67
68 =item B<-spkac filename>
69
70 a file containing a single Netscape signed public key and challenge
71 and additional field values to be signed by the CA. See the B<NOTES>
72 section for information on the required format.
73
74 =item B<-infiles>
75
76 if present this should be the last option, all subsequent arguments
77 are assumed to the the names of files containing certificate requests. 
78
79 =item B<-out filename>
80
81 the output file to output certificates to. The default is standard
82 output. The certificate details will also be printed out to this
83 file.
84
85 =item B<-outdir directory>
86
87 the directory to output certificates to. The certificate will be
88 written to a filename consisting of the serial number in hex with
89 ".pem" appended.
90
91 =item B<-cert>
92
93 the CA certificate file.
94
95 =item B<-keyfile filename>
96
97 the private key to sign requests with.
98
99 =item B<-key password>
100
101 the password used to encrypt the private key. Since on some
102 systems the command line arguments are visible (e.g. Unix with
103 the 'ps' utility) this option should be used with caution.
104
105 =item B<-passin arg>
106
107 the key password source. For more information about the format of B<arg>
108 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
109
110 =item B<-verbose>
111
112 this prints extra details about the operations being performed.
113
114 =item B<-notext>
115
116 don't output the text form of a certificate to the output file.
117
118 =item B<-startdate date>
119
120 this allows the start date to be explicitly set. The format of the
121 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
122
123 =item B<-enddate date>
124
125 this allows the expiry date to be explicitly set. The format of the
126 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
127
128 =item B<-days arg>
129
130 the number of days to certify the certificate for.
131
132 =item B<-md alg>
133
134 the message digest to use. Possible values include md5, sha1 and mdc2.
135 This option also applies to CRLs.
136
137 =item B<-policy arg>
138
139 this option defines the CA "policy" to use. This is a section in
140 the configuration file which decides which fields should be mandatory
141 or match the CA certificate. Check out the B<POLICY FORMAT> section
142 for more information.
143
144 =item B<-msie_hack>
145
146 this is a legacy option to make B<ca> work with very old versions of
147 the IE certificate enrollment control "certenr3". It used UniversalStrings
148 for almost everything. Since the old control has various security bugs
149 its use is strongly discouraged. The newer control "Xenroll" does not
150 need this option.
151
152 =item B<-preserveDN>
153
154 Normally the DN order of a certificate is the same as the order of the
155 fields in the relevant policy section. When this option is set the order 
156 is the same as the request. This is largely for compatibility with the
157 older IE enrollment control which would only accept certificates if their
158 DNs match the order of the request. This is not needed for Xenroll.
159
160 =item B<-batch>
161
162 this sets the batch mode. In this mode no questions will be asked
163 and all certificates will be certified automatically.
164
165 =item B<-extensions section>
166
167 the section of the configuration file containing certificate extensions
168 to be added when a certificate is issued (defaults to B<x509_extensions>
169 unless the B<-extfile> option is used). If no extension section is
170 present then, a V1 certificate is created. If the extension section
171 is present (even if it is empty), then a V3 certificate is created.
172
173 =item B<-extfile file>
174
175 an additional configuration file to read certificate extensions from
176 (using the default section unless the B<-extensions> option is also
177 used).
178
179 =back
180
181 =head1 CRL OPTIONS
182
183 =over 4
184
185 =item B<-gencrl>
186
187 this option generates a CRL based on information in the index file.
188
189 =item B<-crldays num>
190
191 the number of days before the next CRL is due. That is the days from
192 now to place in the CRL nextUpdate field.
193
194 =item B<-crlhours num>
195
196 the number of hours before the next CRL is due.
197
198 =item B<-revoke filename>
199
200 a filename containing a certificate to revoke.
201
202 =item B<-subj arg>
203
204 supersedes subject name given in the request
205
206 =item B<-crlexts section>
207
208 the section of the configuration file containing CRL extensions to
209 include. If no CRL extension section is present then a V1 CRL is
210 created, if the CRL extension section is present (even if it is
211 empty) then a V2 CRL is created. The CRL extensions specified are
212 CRL extensions and B<not> CRL entry extensions.  It should be noted
213 that some software (for example Netscape) can't handle V2 CRLs. 
214
215 =back
216
217 =head1 CONFIGURATION FILE OPTIONS
218
219 The options for B<ca> are contained in the B<ca> section of the
220 configuration file. Many of these are identical to command line
221 options. Where the option is present in the configuration file
222 and the command line the command line value is used. Where an
223 option is described as mandatory then it must be present in
224 the configuration file or the command line equivalent (if
225 any) used.
226
227 =over 4
228
229 =item B<oid_file>
230
231 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
232 Each line of the file should consist of the numerical form of the
233 object identifier followed by white space then the short name followed
234 by white space and finally the long name. 
235
236 =item B<oid_section>
237
238 This specifies a section in the configuration file containing extra
239 object identifiers. Each line should consist of the short name of the
240 object identifier followed by B<=> and the numerical form. The short
241 and long names are the same when this option is used.
242
243 =item B<new_certs_dir>
244
245 the same as the B<-outdir> command line option. It specifies
246 the directory where new certificates will be placed. Mandatory.
247
248 =item B<certificate>
249
250 the same as B<-cert>. It gives the file containing the CA
251 certificate. Mandatory.
252
253 =item B<private_key>
254
255 same as the B<-keyfile> option. The file containing the
256 CA private key. Mandatory.
257
258 =item B<RANDFILE>
259
260 a file used to read and write random number seed information, or
261 an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
262
263 =item B<default_days>
264
265 the same as the B<-days> option. The number of days to certify
266 a certificate for. 
267
268 =item B<default_startdate>
269
270 the same as the B<-startdate> option. The start date to certify
271 a certificate for. If not set the current time is used.
272
273 =item B<default_enddate>
274
275 the same as the B<-enddate> option. Either this option or
276 B<default_days> (or the command line equivalents) must be
277 present.
278
279 =item B<default_crl_hours default_crl_days>
280
281 the same as the B<-crlhours> and the B<-crldays> options. These
282 will only be used if neither command line option is present. At
283 least one of these must be present to generate a CRL.
284
285 =item B<default_md>
286
287 the same as the B<-md> option. The message digest to use. Mandatory.
288
289 =item B<database>
290
291 the text database file to use. Mandatory. This file must be present
292 though initially it will be empty.
293
294 =item B<serialfile>
295
296 a text file containing the next serial number to use in hex. Mandatory.
297 This file must be present and contain a valid serial number.
298
299 =item B<x509_extensions>
300
301 the same as B<-extensions>.
302
303 =item B<crl_extensions>
304
305 the same as B<-crlexts>.
306
307 =item B<preserve>
308
309 the same as B<-preserveDN>
310
311 =item B<msie_hack>
312
313 the same as B<-msie_hack>
314
315 =item B<policy>
316
317 the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
318 for more information.
319
320 =item B<nameopt>, B<certopt>
321
322 these options allow the format used to display the certificate details
323 when asking the user to confirm signing. All the options supported by
324 the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
325 here, except the B<no_signame> and B<no_sigdump> are permanently set
326 and cannot be disabled (this is because the certificate signature cannot
327 be displayed because the certificate has not been signed at this point).
328
329 For convenience the values B<default_ca> are accepted by both to produce
330 a reasonable output.
331
332 If neither option is present the format used in earlier versions of
333 OpenSSL is used. Use of the old format is B<strongly> discouraged because
334 it only displays fields mentioned in the B<policy> section, mishandles
335 multicharacter string types and does not display extensions.
336
337 =item B<copy_extensions>
338
339 determines how extensions in certificate requests should be handled.
340 If set to B<none> or this option is not present then extensions are
341 ignored and not copied to the certificate. If set to B<copy> then any
342 extensions present in the request that are not already present are copied
343 to the certificate. If set to B<copyall> then all extensions in the
344 request are copied to the certificate: if the extension is already present
345 in the certificate it is deleted first. See the B<WARNINGS> section before
346 using this option.
347
348 The main use of this option is to allow a certificate request to supply
349 values for certain extensions such as subjectAltName.
350
351 =back
352
353 =head1 POLICY FORMAT
354
355 The policy section consists of a set of variables corresponding to
356 certificate DN fields. If the value is "match" then the field value
357 must match the same field in the CA certificate. If the value is
358 "supplied" then it must be present. If the value is "optional" then
359 it may be present. Any fields not mentioned in the policy section
360 are silently deleted, unless the B<-preserveDN> option is set but
361 this can be regarded more of a quirk than intended behaviour.
362
363 =head1 SPKAC FORMAT
364
365 The input to the B<-spkac> command line option is a Netscape
366 signed public key and challenge. This will usually come from
367 the B<KEYGEN> tag in an HTML form to create a new private key. 
368 It is however possible to create SPKACs using the B<spkac> utility.
369
370 The file should contain the variable SPKAC set to the value of
371 the SPKAC and also the required DN components as name value pairs.
372 If you need to include the same component twice then it can be
373 preceded by a number and a '.'.
374
375 =head1 EXAMPLES
376
377 Note: these examples assume that the B<ca> directory structure is
378 already set up and the relevant files already exist. This usually
379 involves creating a CA certificate and private key with B<req>, a
380 serial number file and an empty index file and placing them in
381 the relevant directories.
382
383 To use the sample configuration file below the directories demoCA,
384 demoCA/private and demoCA/newcerts would be created. The CA
385 certificate would be copied to demoCA/cacert.pem and its private
386 key to demoCA/private/cakey.pem. A file demoCA/serial would be
387 created containing for example "01" and the empty index file
388 demoCA/index.txt.
389
390
391 Sign a certificate request:
392
393  openssl ca -in req.pem -out newcert.pem
394
395 Sign a certificate request, using CA extensions:
396
397  openssl ca -in req.pem -extensions v3_ca -out newcert.pem
398
399 Generate a CRL
400
401  openssl ca -gencrl -out crl.pem
402
403 Sign several requests:
404
405  openssl ca -infiles req1.pem req2.pem req3.pem
406
407 Certify a Netscape SPKAC:
408
409  openssl ca -spkac spkac.txt
410
411 A sample SPKAC file (the SPKAC line has been truncated for clarity):
412
413  SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
414  CN=Steve Test
415  emailAddress=steve@openssl.org
416  0.OU=OpenSSL Group
417  1.OU=Another Group
418
419 A sample configuration file with the relevant sections for B<ca>:
420
421  [ ca ]
422  default_ca      = CA_default            # The default ca section
423  
424  [ CA_default ]
425
426  dir            = ./demoCA              # top dir
427  database       = $dir/index.txt        # index file.
428  new_certs_dir  = $dir/newcerts         # new certs dir
429  
430  certificate    = $dir/cacert.pem       # The CA cert
431  serial         = $dir/serial           # serial no file
432  private_key    = $dir/private/cakey.pem# CA private key
433  RANDFILE       = $dir/private/.rand    # random number file
434  
435  default_days   = 365                   # how long to certify for
436  default_crl_days= 30                   # how long before next CRL
437  default_md     = md5                   # md to use
438
439  policy         = policy_any            # default policy
440
441  nameopt        = default_ca            # Subject name display option
442  certopt        = default_ca            # Certificate display option
443  copy_extensions = none                 # Don't copy extensions from request
444
445  [ policy_any ]
446  countryName            = supplied
447  stateOrProvinceName    = optional
448  organizationName       = optional
449  organizationalUnitName = optional
450  commonName             = supplied
451  emailAddress           = optional
452
453 =head1 WARNINGS
454
455 The B<ca> command is quirky and at times downright unfriendly.
456
457 The B<ca> utility was originally meant as an example of how to do things
458 in a CA. It was not supposed to be used as a full blown CA itself:
459 nevertheless some people are using it for this purpose.
460
461 The B<ca> command is effectively a single user command: no locking is
462 done on the various files and attempts to run more than one B<ca> command
463 on the same database can have unpredictable results.
464
465 =head1 FILES
466
467 Note: the location of all files can change either by compile time options,
468 configuration file entries, environment variables or command line options.
469 The values below reflect the default values.
470
471  /usr/local/ssl/lib/openssl.cnf - master configuration file
472  ./demoCA                       - main CA directory
473  ./demoCA/cacert.pem            - CA certificate
474  ./demoCA/private/cakey.pem     - CA private key
475  ./demoCA/serial                - CA serial number file
476  ./demoCA/serial.old            - CA serial number backup file
477  ./demoCA/index.txt             - CA text database file
478  ./demoCA/index.txt.old         - CA text database backup file
479  ./demoCA/certs                 - certificate output file
480  ./demoCA/.rnd                  - CA random seed information
481
482 =head1 ENVIRONMENT VARIABLES
483
484 B<OPENSSL_CONF> reflects the location of master configuration file it can
485 be overridden by the B<-config> command line option.
486
487 =head1 RESTRICTIONS
488
489 The text database index file is a critical part of the process and 
490 if corrupted it can be difficult to fix. It is theoretically possible
491 to rebuild the index file from all the issued certificates and a current
492 CRL: however there is no option to do this.
493
494 CRL entry extensions cannot currently be created: only CRL extensions
495 can be added.
496
497 V2 CRL features like delta CRL support and CRL numbers are not currently
498 supported.
499
500 Although several requests can be input and handled at once it is only
501 possible to include one SPKAC or self signed certificate.
502
503 =head1 BUGS
504
505 The use of an in memory text database can cause problems when large
506 numbers of certificates are present because, as the name implies
507 the database has to be kept in memory.
508
509 It is not possible to certify two certificates with the same DN: this
510 is a side effect of how the text database is indexed and it cannot easily
511 be fixed without introducing other problems. Some S/MIME clients can use
512 two certificates with the same DN for separate signing and encryption
513 keys.
514
515 The B<ca> command really needs rewriting or the required functionality
516 exposed at either a command or interface level so a more friendly utility
517 (perl script or GUI) can handle things properly. The scripts B<CA.sh> and
518 B<CA.pl> help a little but not very much.
519
520 Any fields in a request that are not present in a policy are silently
521 deleted. This does not happen if the B<-preserveDN> option is used.
522 The behaviour should be more friendly and configurable.
523
524 Cancelling some commands by refusing to certify a certificate can
525 create an empty file.
526
527 =head1 WARNINGS
528
529 The B<copy_extensions> option should be used with caution. If care is
530 not taken then it can be a security risk. For example if a certificate
531 request contains a basicConstraints extension with CA:TRUE and the
532 B<copy_extensions> value is set to B<copyall> and the user does not spot
533 this when the certificate is displayed then this will hand the requestor
534 a valid CA certificate.
535
536 This situation can be avoided by setting B<copy_extensions> to B<copy>
537 and including basicConstraints with CA:FALSE in the configuration file.
538 Then if the request contains a basicConstraints extension it will be
539 ignored.
540
541 It is advisable to also include values for other extensions such
542 as B<keyUsage> to prevent a request supplying its own values.
543
544 Additional restrictions can be placed on the CA certificate itself.
545 For example if the CA certificate has:
546
547  basicConstraints = CA:TRUE, pathlen:0
548
549 then even if a certificate is issued with CA:TRUE it will not be valid.
550
551 =head1 SEE ALSO
552
553 L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>,
554 L<config(5)|config(5)>
555
556 =cut