6 ca - sample minimal CA application
18 [B<-crl_reason reason>]
19 [B<-crl_hold instruction>]
20 [B<-crl_compromise time>]
21 [B<-crl_CA_compromise time>]
47 [B<-extensions section>]
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
61 The options descriptions will be divided into each purpose.
67 =item B<-config filename>
69 specifies the configuration file to use.
71 =item B<-name section>
73 specifies the configuration file section to use (overrides
74 B<default_ca> in the B<ca> section).
78 an input filename containing a single certificate request to be
81 =item B<-ss_cert filename>
83 a single self signed certificate to be signed by the CA.
85 =item B<-spkac filename>
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.
93 if present this should be the last option, all subsequent arguments
94 are assumed to be the names of files containing certificate requests.
96 =item B<-out filename>
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).
102 =item B<-outdir directory>
104 the directory to output certificates to. The certificate will be
105 written to a filename consisting of the serial number in hex with
110 the CA certificate file.
112 =item B<-keyfile filename>
114 the private key to sign requests with.
116 =item B<-keyform PEM|DER>
118 the format of the data in the private key file.
121 =item B<-key password>
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.
129 indicates the issued certificates are to be signed with the key
130 the certificate requests were signed with (given with B<-keyfile>).
131 Cerificate requests signed with a different key are ignored. If
132 B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
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.
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)|openssl(1)>.
148 this prints extra details about the operations being performed.
152 don't output the text form of a certificate to the output file.
154 =item B<-startdate date>
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).
159 =item B<-enddate date>
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).
166 the number of days to certify the certificate for.
170 the message digest to use. Possible values include md5, sha1 and mdc2.
171 This option also applies to CRLs.
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.
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
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.
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.
207 this sets the batch mode. In this mode no questions will be asked
208 and all certificates will be certified automatically.
210 =item B<-extensions section>
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.
218 =item B<-extfile file>
220 an additional configuration file to read certificate extensions from
221 (using the default section unless the B<-extensions> option is also
226 specifying an engine (by it's unique B<id> string) will cause B<req>
227 to attempt to obtain a functional reference to the specified engine,
228 thus initialising it if needed. The engine will then be set as the default
229 for all available algorithms.
233 supersedes subject name given in the request.
234 The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
235 characters may be escaped by \ (backslash), no spaces are skipped.
239 this option causes field values to be interpreted as UTF8 strings, by
240 default they are interpreted as ASCII. This means that the field
241 values, whether prompted from a terminal or obtained from a
242 configuration file, must be valid UTF8 strings.
244 =item B<-multivalue-rdn>
246 this option causes the -subj argument to be interpretedt with full
247 support for multivalued RDNs. Example:
249 I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
251 If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
261 this option generates a CRL based on information in the index file.
263 =item B<-crldays num>
265 the number of days before the next CRL is due. That is the days from
266 now to place in the CRL nextUpdate field.
268 =item B<-crlhours num>
270 the number of hours before the next CRL is due.
272 =item B<-revoke filename>
274 a filename containing a certificate to revoke.
276 =item B<-status serial>
278 displays the revocation status of the certificate with the specified
279 serial number and exits.
283 Updates the database index to purge expired certificates.
285 =item B<-crl_reason reason>
287 revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>,
288 B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>,
289 B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case
290 insensitive. Setting any revocation reason will make the CRL v2.
292 In practive B<removeFromCRL> is not particularly useful because it is only used
293 in delta CRLs which are not currently implemented.
295 =item B<-crl_hold instruction>
297 This sets the CRL revocation reason code to B<certificateHold> and the hold
298 instruction to B<instruction> which must be an OID. Although any OID can be
299 used only B<holdInstructionNone> (the use of which is discouraged by RFC2459)
300 B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used.
302 =item B<-crl_compromise time>
304 This sets the revocation reason to B<keyCompromise> and the compromise time to
305 B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>.
307 =item B<-crl_CA_compromise time>
309 This is the same as B<crl_compromise> except the revocation reason is set to
312 =item B<-crlexts section>
314 the section of the configuration file containing CRL extensions to
315 include. If no CRL extension section is present then a V1 CRL is
316 created, if the CRL extension section is present (even if it is
317 empty) then a V2 CRL is created. The CRL extensions specified are
318 CRL extensions and B<not> CRL entry extensions. It should be noted
319 that some software (for example Netscape) can't handle V2 CRLs.
323 =head1 CONFIGURATION FILE OPTIONS
325 The section of the configuration file containing options for B<ca>
326 is found as follows: If the B<-name> command line option is used,
327 then it names the section to be used. Otherwise the section to
328 be used must be named in the B<default_ca> option of the B<ca> section
329 of the configuration file (or in the default section of the
330 configuration file). Besides B<default_ca>, the following options are
331 read directly from the B<ca> section:
335 With the exception of B<RANDFILE>, this is probably a bug and may
336 change in future releases.
338 Many of the configuration file options are identical to command line
339 options. Where the option is present in the configuration file
340 and the command line the command line value is used. Where an
341 option is described as mandatory then it must be present in
342 the configuration file or the command line equivalent (if
349 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
350 Each line of the file should consist of the numerical form of the
351 object identifier followed by white space then the short name followed
352 by white space and finally the long name.
356 This specifies a section in the configuration file containing extra
357 object identifiers. Each line should consist of the short name of the
358 object identifier followed by B<=> and the numerical form. The short
359 and long names are the same when this option is used.
361 =item B<new_certs_dir>
363 the same as the B<-outdir> command line option. It specifies
364 the directory where new certificates will be placed. Mandatory.
368 the same as B<-cert>. It gives the file containing the CA
369 certificate. Mandatory.
373 same as the B<-keyfile> option. The file containing the
374 CA private key. Mandatory.
378 a file used to read and write random number seed information, or
379 an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
381 =item B<default_days>
383 the same as the B<-days> option. The number of days to certify
386 =item B<default_startdate>
388 the same as the B<-startdate> option. The start date to certify
389 a certificate for. If not set the current time is used.
391 =item B<default_enddate>
393 the same as the B<-enddate> option. Either this option or
394 B<default_days> (or the command line equivalents) must be
397 =item B<default_crl_hours default_crl_days>
399 the same as the B<-crlhours> and the B<-crldays> options. These
400 will only be used if neither command line option is present. At
401 least one of these must be present to generate a CRL.
405 the same as the B<-md> option. The message digest to use. Mandatory.
409 the text database file to use. Mandatory. This file must be present
410 though initially it will be empty.
412 =item B<unique_subject>
414 if the value B<yes> is given, the valid certificate entries in the
415 database must have unique subjects. if the value B<no> is given,
416 several valid certificate entries may have the exact same subject.
417 The default value is B<yes>, to be compatible with older (pre 0.9.8)
418 versions of OpenSSL. However, to make CA certificate roll-over easier,
419 it's recommended to use the value B<no>, especially if combined with
420 the B<-selfsign> command line option.
424 a text file containing the next serial number to use in hex. Mandatory.
425 This file must be present and contain a valid serial number.
429 a text file containing the next CRL number to use in hex. The crl number
430 will be inserted in the CRLs only if this file exists. If this file is
431 present, it must contain a valid CRL number.
433 =item B<x509_extensions>
435 the same as B<-extensions>.
437 =item B<crl_extensions>
439 the same as B<-crlexts>.
443 the same as B<-preserveDN>
447 the same as B<-noemailDN>. If you want the EMAIL field to be removed
448 from the DN of the certificate simply set this to 'no'. If not present
449 the default is to allow for the EMAIL filed in the certificate's DN.
453 the same as B<-msie_hack>
457 the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
458 for more information.
460 =item B<name_opt>, B<cert_opt>
462 these options allow the format used to display the certificate details
463 when asking the user to confirm signing. All the options supported by
464 the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
465 here, except the B<no_signame> and B<no_sigdump> are permanently set
466 and cannot be disabled (this is because the certificate signature cannot
467 be displayed because the certificate has not been signed at this point).
469 For convenience the values B<ca_default> are accepted by both to produce
472 If neither option is present the format used in earlier versions of
473 OpenSSL is used. Use of the old format is B<strongly> discouraged because
474 it only displays fields mentioned in the B<policy> section, mishandles
475 multicharacter string types and does not display extensions.
477 =item B<copy_extensions>
479 determines how extensions in certificate requests should be handled.
480 If set to B<none> or this option is not present then extensions are
481 ignored and not copied to the certificate. If set to B<copy> then any
482 extensions present in the request that are not already present are copied
483 to the certificate. If set to B<copyall> then all extensions in the
484 request are copied to the certificate: if the extension is already present
485 in the certificate it is deleted first. See the B<WARNINGS> section before
488 The main use of this option is to allow a certificate request to supply
489 values for certain extensions such as subjectAltName.
495 The policy section consists of a set of variables corresponding to
496 certificate DN fields. If the value is "match" then the field value
497 must match the same field in the CA certificate. If the value is
498 "supplied" then it must be present. If the value is "optional" then
499 it may be present. Any fields not mentioned in the policy section
500 are silently deleted, unless the B<-preserveDN> option is set but
501 this can be regarded more of a quirk than intended behaviour.
505 The input to the B<-spkac> command line option is a Netscape
506 signed public key and challenge. This will usually come from
507 the B<KEYGEN> tag in an HTML form to create a new private key.
508 It is however possible to create SPKACs using the B<spkac> utility.
510 The file should contain the variable SPKAC set to the value of
511 the SPKAC and also the required DN components as name value pairs.
512 If you need to include the same component twice then it can be
513 preceded by a number and a '.'.
515 When processing SPKAC format, the output is DER if the B<-out>
516 flag is used, but PEM format if sending to stdout or the B<-outdir>
521 Note: these examples assume that the B<ca> directory structure is
522 already set up and the relevant files already exist. This usually
523 involves creating a CA certificate and private key with B<req>, a
524 serial number file and an empty index file and placing them in
525 the relevant directories.
527 To use the sample configuration file below the directories demoCA,
528 demoCA/private and demoCA/newcerts would be created. The CA
529 certificate would be copied to demoCA/cacert.pem and its private
530 key to demoCA/private/cakey.pem. A file demoCA/serial would be
531 created containing for example "01" and the empty index file
535 Sign a certificate request:
537 openssl ca -in req.pem -out newcert.pem
539 Sign a certificate request, using CA extensions:
541 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
545 openssl ca -gencrl -out crl.pem
547 Sign several requests:
549 openssl ca -infiles req1.pem req2.pem req3.pem
551 Certify a Netscape SPKAC:
553 openssl ca -spkac spkac.txt
555 A sample SPKAC file (the SPKAC line has been truncated for clarity):
557 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
559 emailAddress=steve@openssl.org
563 A sample configuration file with the relevant sections for B<ca>:
566 default_ca = CA_default # The default ca section
570 dir = ./demoCA # top dir
571 database = $dir/index.txt # index file.
572 new_certs_dir = $dir/newcerts # new certs dir
574 certificate = $dir/cacert.pem # The CA cert
575 serial = $dir/serial # serial no file
576 private_key = $dir/private/cakey.pem# CA private key
577 RANDFILE = $dir/private/.rand # random number file
579 default_days = 365 # how long to certify for
580 default_crl_days= 30 # how long before next CRL
581 default_md = md5 # md to use
583 policy = policy_any # default policy
584 email_in_dn = no # Don't add the email into cert DN
586 name_opt = ca_default # Subject name display option
587 cert_opt = ca_default # Certificate display option
588 copy_extensions = none # Don't copy extensions from request
591 countryName = supplied
592 stateOrProvinceName = optional
593 organizationName = optional
594 organizationalUnitName = optional
595 commonName = supplied
596 emailAddress = optional
600 Note: the location of all files can change either by compile time options,
601 configuration file entries, environment variables or command line options.
602 The values below reflect the default values.
604 /usr/local/ssl/lib/openssl.cnf - master configuration file
605 ./demoCA - main CA directory
606 ./demoCA/cacert.pem - CA certificate
607 ./demoCA/private/cakey.pem - CA private key
608 ./demoCA/serial - CA serial number file
609 ./demoCA/serial.old - CA serial number backup file
610 ./demoCA/index.txt - CA text database file
611 ./demoCA/index.txt.old - CA text database backup file
612 ./demoCA/certs - certificate output file
613 ./demoCA/.rnd - CA random seed information
615 =head1 ENVIRONMENT VARIABLES
617 B<OPENSSL_CONF> reflects the location of master configuration file it can
618 be overridden by the B<-config> command line option.
622 The text database index file is a critical part of the process and
623 if corrupted it can be difficult to fix. It is theoretically possible
624 to rebuild the index file from all the issued certificates and a current
625 CRL: however there is no option to do this.
627 V2 CRL features like delta CRLs are not currently supported.
629 Although several requests can be input and handled at once it is only
630 possible to include one SPKAC or self signed certificate.
634 The use of an in memory text database can cause problems when large
635 numbers of certificates are present because, as the name implies
636 the database has to be kept in memory.
638 The B<ca> command really needs rewriting or the required functionality
639 exposed at either a command or interface level so a more friendly utility
640 (perl script or GUI) can handle things properly. The scripts B<CA.sh> and
641 B<CA.pl> help a little but not very much.
643 Any fields in a request that are not present in a policy are silently
644 deleted. This does not happen if the B<-preserveDN> option is used. To
645 enforce the absence of the EMAIL field within the DN, as suggested by
646 RFCs, regardless the contents of the request' subject the B<-noemailDN>
647 option can be used. The behaviour should be more friendly and
650 Cancelling some commands by refusing to certify a certificate can
651 create an empty file.
655 The B<ca> command is quirky and at times downright unfriendly.
657 The B<ca> utility was originally meant as an example of how to do things
658 in a CA. It was not supposed to be used as a full blown CA itself:
659 nevertheless some people are using it for this purpose.
661 The B<ca> command is effectively a single user command: no locking is
662 done on the various files and attempts to run more than one B<ca> command
663 on the same database can have unpredictable results.
665 The B<copy_extensions> option should be used with caution. If care is
666 not taken then it can be a security risk. For example if a certificate
667 request contains a basicConstraints extension with CA:TRUE and the
668 B<copy_extensions> value is set to B<copyall> and the user does not spot
669 this when the certificate is displayed then this will hand the requestor
670 a valid CA certificate.
672 This situation can be avoided by setting B<copy_extensions> to B<copy>
673 and including basicConstraints with CA:FALSE in the configuration file.
674 Then if the request contains a basicConstraints extension it will be
677 It is advisable to also include values for other extensions such
678 as B<keyUsage> to prevent a request supplying its own values.
680 Additional restrictions can be placed on the CA certificate itself.
681 For example if the CA certificate has:
683 basicConstraints = CA:TRUE, pathlen:0
685 then even if a certificate is issued with CA:TRUE it will not be valid.
689 L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>,
690 L<config(5)|config(5)>