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