6 ca - sample minimal CA application
40 [B<-extensions section>]
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
50 The options descriptions will be divided into each purpose.
56 =item B<-config filename>
58 specifies the configuration file to use.
60 =item B<-name section>
62 specifies the configuration file section to use (overrides
63 B<default_ca> in the B<ca> section).
67 an input filename containing a single certificate request to be
70 =item B<-ss_cert filename>
72 a single self signed certificate to be signed by the CA.
74 =item B<-spkac filename>
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.
82 if present this should be the last option, all subsequent arguments
83 are assumed to the the names of files containing certificate requests.
85 =item B<-out filename>
87 the output file to output certificates to. The default is standard
88 output. The certificate details will also be printed out to this
91 =item B<-outdir directory>
93 the directory to output certificates to. The certificate will be
94 written to a filename consisting of the serial number in hex with
99 the CA certificate file.
101 =item B<-keyfile filename>
103 the private key to sign requests with.
105 =item B<-key password>
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.
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)>.
118 this prints extra details about the operations being performed.
122 don't output the text form of a certificate to the output file.
124 =item B<-startdate date>
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).
129 =item B<-enddate date>
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).
136 the number of days to certify the certificate for.
140 the message digest to use. Possible values include md5, sha1 and mdc2.
141 This option also applies to CRLs.
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.
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
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.
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.
177 this sets the batch mode. In this mode no questions will be asked
178 and all certificates will be certified automatically.
180 =item B<-extensions section>
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.
188 =item B<-extfile file>
190 an additional configuration file to read certificate extensions from
191 (using the default section unless the B<-extensions> option is also
202 this option generates a CRL based on information in the index file.
204 =item B<-crldays num>
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.
209 =item B<-crlhours num>
211 the number of hours before the next CRL is due.
213 =item B<-revoke filename>
215 a filename containing a certificate to revoke.
219 supersedes subject name given in the request
221 =item B<-crlexts section>
223 the section of the configuration file containing CRL extensions to
224 include. If no CRL extension section is present then a V1 CRL is
225 created, if the CRL extension section is present (even if it is
226 empty) then a V2 CRL is created. The CRL extensions specified are
227 CRL extensions and B<not> CRL entry extensions. It should be noted
228 that some software (for example Netscape) can't handle V2 CRLs.
232 =head1 CONFIGURATION FILE OPTIONS
234 The section of the configuration file containing options for B<ca>
235 is found as follows: If the B<-name> command line option is used,
236 then it names the section to be used. Otherwise the section to
237 be used must be named in the B<default_ca> option of the B<ca> section
238 of the configuration file (or in the default section of the
239 configuration file). Besides B<default_ca>, the following options are
240 read directly from the B<ca> section:
244 With the exception of B<RANDFILE>, this is probably a bug and may
245 change in future releases.
247 Many of the configuration file options are identical to command line
248 options. Where the option is present in the configuration file
249 and the command line the command line value is used. Where an
250 option is described as mandatory then it must be present in
251 the configuration file or the command line equivalent (if
258 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
259 Each line of the file should consist of the numerical form of the
260 object identifier followed by white space then the short name followed
261 by white space and finally the long name.
265 This specifies a section in the configuration file containing extra
266 object identifiers. Each line should consist of the short name of the
267 object identifier followed by B<=> and the numerical form. The short
268 and long names are the same when this option is used.
270 =item B<new_certs_dir>
272 the same as the B<-outdir> command line option. It specifies
273 the directory where new certificates will be placed. Mandatory.
277 the same as B<-cert>. It gives the file containing the CA
278 certificate. Mandatory.
282 same as the B<-keyfile> option. The file containing the
283 CA private key. Mandatory.
287 a file used to read and write random number seed information, or
288 an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
290 =item B<default_days>
292 the same as the B<-days> option. The number of days to certify
295 =item B<default_startdate>
297 the same as the B<-startdate> option. The start date to certify
298 a certificate for. If not set the current time is used.
300 =item B<default_enddate>
302 the same as the B<-enddate> option. Either this option or
303 B<default_days> (or the command line equivalents) must be
306 =item B<default_crl_hours default_crl_days>
308 the same as the B<-crlhours> and the B<-crldays> options. These
309 will only be used if neither command line option is present. At
310 least one of these must be present to generate a CRL.
314 the same as the B<-md> option. The message digest to use. Mandatory.
318 the text database file to use. Mandatory. This file must be present
319 though initially it will be empty.
323 a text file containing the next serial number to use in hex. Mandatory.
324 This file must be present and contain a valid serial number.
326 =item B<x509_extensions>
328 the same as B<-extensions>.
330 =item B<crl_extensions>
332 the same as B<-crlexts>.
336 the same as B<-preserveDN>
340 the same as B<-noemailDN>. If you want the EMAIL field to be removed
341 from the DN of the certificate simply set this to 'no'. If not present
342 the default is to allow for the EMAIL filed in the certificate's DN.
346 the same as B<-msie_hack>
350 the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
351 for more information.
353 =item B<nameopt>, B<certopt>
355 these options allow the format used to display the certificate details
356 when asking the user to confirm signing. All the options supported by
357 the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
358 here, except the B<no_signame> and B<no_sigdump> are permanently set
359 and cannot be disabled (this is because the certificate signature cannot
360 be displayed because the certificate has not been signed at this point).
362 For convenience the values B<default_ca> are accepted by both to produce
365 If neither option is present the format used in earlier versions of
366 OpenSSL is used. Use of the old format is B<strongly> discouraged because
367 it only displays fields mentioned in the B<policy> section, mishandles
368 multicharacter string types and does not display extensions.
370 =item B<copy_extensions>
372 determines how extensions in certificate requests should be handled.
373 If set to B<none> or this option is not present then extensions are
374 ignored and not copied to the certificate. If set to B<copy> then any
375 extensions present in the request that are not already present are copied
376 to the certificate. If set to B<copyall> then all extensions in the
377 request are copied to the certificate: if the extension is already present
378 in the certificate it is deleted first. See the B<WARNINGS> section before
381 The main use of this option is to allow a certificate request to supply
382 values for certain extensions such as subjectAltName.
388 The policy section consists of a set of variables corresponding to
389 certificate DN fields. If the value is "match" then the field value
390 must match the same field in the CA certificate. If the value is
391 "supplied" then it must be present. If the value is "optional" then
392 it may be present. Any fields not mentioned in the policy section
393 are silently deleted, unless the B<-preserveDN> option is set but
394 this can be regarded more of a quirk than intended behaviour.
398 The input to the B<-spkac> command line option is a Netscape
399 signed public key and challenge. This will usually come from
400 the B<KEYGEN> tag in an HTML form to create a new private key.
401 It is however possible to create SPKACs using the B<spkac> utility.
403 The file should contain the variable SPKAC set to the value of
404 the SPKAC and also the required DN components as name value pairs.
405 If you need to include the same component twice then it can be
406 preceded by a number and a '.'.
410 Note: these examples assume that the B<ca> directory structure is
411 already set up and the relevant files already exist. This usually
412 involves creating a CA certificate and private key with B<req>, a
413 serial number file and an empty index file and placing them in
414 the relevant directories.
416 To use the sample configuration file below the directories demoCA,
417 demoCA/private and demoCA/newcerts would be created. The CA
418 certificate would be copied to demoCA/cacert.pem and its private
419 key to demoCA/private/cakey.pem. A file demoCA/serial would be
420 created containing for example "01" and the empty index file
424 Sign a certificate request:
426 openssl ca -in req.pem -out newcert.pem
428 Sign a certificate request, using CA extensions:
430 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
434 openssl ca -gencrl -out crl.pem
436 Sign several requests:
438 openssl ca -infiles req1.pem req2.pem req3.pem
440 Certify a Netscape SPKAC:
442 openssl ca -spkac spkac.txt
444 A sample SPKAC file (the SPKAC line has been truncated for clarity):
446 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
448 emailAddress=steve@openssl.org
452 A sample configuration file with the relevant sections for B<ca>:
455 default_ca = CA_default # The default ca section
459 dir = ./demoCA # top dir
460 database = $dir/index.txt # index file.
461 new_certs_dir = $dir/newcerts # new certs dir
463 certificate = $dir/cacert.pem # The CA cert
464 serial = $dir/serial # serial no file
465 private_key = $dir/private/cakey.pem# CA private key
466 RANDFILE = $dir/private/.rand # random number file
468 default_days = 365 # how long to certify for
469 default_crl_days= 30 # how long before next CRL
470 default_md = md5 # md to use
472 policy = policy_any # default policy
473 email_in_dn = no # Don't add the email into cert DN
475 nameopt = default_ca # Subject name display option
476 certopt = default_ca # Certificate display option
477 copy_extensions = none # Don't copy extensions from request
480 countryName = supplied
481 stateOrProvinceName = optional
482 organizationName = optional
483 organizationalUnitName = optional
484 commonName = supplied
485 emailAddress = optional
489 The B<ca> command is quirky and at times downright unfriendly.
491 The B<ca> utility was originally meant as an example of how to do things
492 in a CA. It was not supposed to be used as a full blown CA itself:
493 nevertheless some people are using it for this purpose.
495 The B<ca> command is effectively a single user command: no locking is
496 done on the various files and attempts to run more than one B<ca> command
497 on the same database can have unpredictable results.
501 Note: the location of all files can change either by compile time options,
502 configuration file entries, environment variables or command line options.
503 The values below reflect the default values.
505 /usr/local/ssl/lib/openssl.cnf - master configuration file
506 ./demoCA - main CA directory
507 ./demoCA/cacert.pem - CA certificate
508 ./demoCA/private/cakey.pem - CA private key
509 ./demoCA/serial - CA serial number file
510 ./demoCA/serial.old - CA serial number backup file
511 ./demoCA/index.txt - CA text database file
512 ./demoCA/index.txt.old - CA text database backup file
513 ./demoCA/certs - certificate output file
514 ./demoCA/.rnd - CA random seed information
516 =head1 ENVIRONMENT VARIABLES
518 B<OPENSSL_CONF> reflects the location of master configuration file it can
519 be overridden by the B<-config> command line option.
523 The text database index file is a critical part of the process and
524 if corrupted it can be difficult to fix. It is theoretically possible
525 to rebuild the index file from all the issued certificates and a current
526 CRL: however there is no option to do this.
528 CRL entry extensions cannot currently be created: only CRL extensions
531 V2 CRL features like delta CRL support and CRL numbers are not currently
534 Although several requests can be input and handled at once it is only
535 possible to include one SPKAC or self signed certificate.
539 The use of an in memory text database can cause problems when large
540 numbers of certificates are present because, as the name implies
541 the database has to be kept in memory.
543 It is not possible to certify two certificates with the same DN: this
544 is a side effect of how the text database is indexed and it cannot easily
545 be fixed without introducing other problems. Some S/MIME clients can use
546 two certificates with the same DN for separate signing and encryption
549 The B<ca> command really needs rewriting or the required functionality
550 exposed at either a command or interface level so a more friendly utility
551 (perl script or GUI) can handle things properly. The scripts B<CA.sh> and
552 B<CA.pl> help a little but not very much.
554 Any fields in a request that are not present in a policy are silently
555 deleted. This does not happen if the B<-preserveDN> option is used. To
556 enforce the absence of the EMAIL field within the DN, as suggested by
557 RFCs, regardless the contents of the request' subject the B<-noemailDN>
558 option can be used. The behaviour should be more friendly and
561 Cancelling some commands by refusing to certify a certificate can
562 create an empty file.
566 The B<copy_extensions> option should be used with caution. If care is
567 not taken then it can be a security risk. For example if a certificate
568 request contains a basicConstraints extension with CA:TRUE and the
569 B<copy_extensions> value is set to B<copyall> and the user does not spot
570 this when the certificate is displayed then this will hand the requestor
571 a valid CA certificate.
573 This situation can be avoided by setting B<copy_extensions> to B<copy>
574 and including basicConstraints with CA:FALSE in the configuration file.
575 Then if the request contains a basicConstraints extension it will be
578 It is advisable to also include values for other extensions such
579 as B<keyUsage> to prevent a request supplying its own values.
581 Additional restrictions can be placed on the CA certificate itself.
582 For example if the CA certificate has:
584 basicConstraints = CA:TRUE, pathlen:0
586 then even if a certificate is issued with CA:TRUE it will not be valid.
590 L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>,
591 L<config(5)|config(5)>