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