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