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