5 ca - sample minimal CA application
19 [B<-crl_reason reason>]
20 [B<-crl_hold instruction>]
21 [B<-crl_compromise time>]
22 [B<-crl_CA_compromise time>]
48 [B<-extensions section>]
58 The B<ca> command is a minimal CA application. It can be used
59 to sign certificate requests in a variety of forms and generate
60 CRLs it also maintains a text database of issued certificates
63 The options descriptions will be divided into each purpose.
65 =head1 COMMAND OPTIONS
71 Print out a usage message.
75 this prints extra details about the operations being performed.
77 =item B<-config filename>
79 specifies the configuration file to use.
81 =item B<-name section>
83 specifies the configuration file section to use (overrides
84 B<default_ca> in the B<ca> section).
88 an input filename containing a single certificate request to be
91 =item B<-ss_cert filename>
93 a single self-signed certificate to be signed by the CA.
95 =item B<-spkac filename>
97 a file containing a single Netscape signed public key and challenge
98 and additional field values to be signed by the CA. See the B<SPKAC FORMAT>
99 section for information on the required input and output format.
103 if present this should be the last option, all subsequent arguments
104 are taken as the names of files containing certificate requests.
106 =item B<-out filename>
108 the output file to output certificates to. The default is standard
109 output. The certificate details will also be printed out to this
110 file in PEM format (except that B<-spkac> outputs DER format).
112 =item B<-outdir directory>
114 the directory to output certificates to. The certificate will be
115 written to a filename consisting of the serial number in hex with
120 the CA certificate file.
122 =item B<-keyfile filename>
124 the private key to sign requests with.
126 =item B<-keyform PEM|DER>
128 the format of the data in the private key file.
131 =item B<-key password>
133 the password used to encrypt the private key. Since on some
134 systems the command line arguments are visible (e.g. Unix with
135 the 'ps' utility) this option should be used with caution.
139 indicates the issued certificates are to be signed with the key
140 the certificate requests were signed with (given with B<-keyfile>).
141 Certificate requests signed with a different key are ignored. If
142 B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
145 A consequence of using B<-selfsign> is that the self-signed
146 certificate appears among the entries in the certificate database
147 (see the configuration option B<database>), and uses the same
148 serial number counter as all other certificates sign with the
149 self-signed certificate.
153 the key password source. For more information about the format of B<arg>
154 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
158 don't output the text form of a certificate to the output file.
160 =item B<-startdate date>
162 this allows the start date to be explicitly set. The format of the
163 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
165 =item B<-enddate date>
167 this allows the expiry date to be explicitly set. The format of the
168 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
172 the number of days to certify the certificate for.
176 the message digest to use.
177 Any digest supported by the OpenSSL B<dgst> command can be used.
178 This option also applies to CRLs.
182 this option defines the CA "policy" to use. This is a section in
183 the configuration file which decides which fields should be mandatory
184 or match the CA certificate. Check out the B<POLICY FORMAT> section
185 for more information.
189 this is a legacy option to make B<ca> work with very old versions of
190 the IE certificate enrollment control "certenr3". It used UniversalStrings
191 for almost everything. Since the old control has various security bugs
192 its use is strongly discouraged. The newer control "Xenroll" does not
197 Normally the DN order of a certificate is the same as the order of the
198 fields in the relevant policy section. When this option is set the order
199 is the same as the request. This is largely for compatibility with the
200 older IE enrollment control which would only accept certificates if their
201 DNs match the order of the request. This is not needed for Xenroll.
205 The DN of a certificate can contain the EMAIL field if present in the
206 request DN, however it is good policy just having the e-mail set into
207 the altName extension of the certificate. When this option is set the
208 EMAIL field is removed from the certificate' subject and set only in
209 the, eventually present, extensions. The B<email_in_dn> keyword can be
210 used in the configuration file to enable this behaviour.
214 this sets the batch mode. In this mode no questions will be asked
215 and all certificates will be certified automatically.
217 =item B<-extensions section>
219 the section of the configuration file containing certificate extensions
220 to be added when a certificate is issued (defaults to B<x509_extensions>
221 unless the B<-extfile> option is used). If no extension section is
222 present then, a V1 certificate is created. If the extension section
223 is present (even if it is empty), then a V3 certificate is created. See the:w
224 L<x509v3_config(5)> manual page for details of the
225 extension section format.
227 =item B<-extfile file>
229 an additional configuration file to read certificate extensions from
230 (using the default section unless the B<-extensions> option is also
235 specifying an engine (by its unique B<id> string) will cause B<ca>
236 to attempt to obtain a functional reference to the specified engine,
237 thus initialising it if needed. The engine will then be set as the default
238 for all available algorithms.
242 supersedes subject name given in the request.
243 The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
244 characters may be escaped by \ (backslash), no spaces are skipped.
248 this option causes field values to be interpreted as UTF8 strings, by
249 default they are interpreted as ASCII. This means that the field
250 values, whether prompted from a terminal or obtained from a
251 configuration file, must be valid UTF8 strings.
253 =item B<-create_serial>
255 if reading serial from the text file as specified in the configuration
256 fails, specifying this option creates a new random serial to be used as next
259 =item B<-multivalue-rdn>
261 This option causes the -subj argument to be interpreted with full
262 support for multivalued RDNs. Example:
264 I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
266 If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
276 this option generates a CRL based on information in the index file.
278 =item B<-crldays num>
280 the number of days before the next CRL is due. That is the days from
281 now to place in the CRL nextUpdate field.
283 =item B<-crlhours num>
285 the number of hours before the next CRL is due.
287 =item B<-revoke filename>
289 a filename containing a certificate to revoke.
291 =item B<-valid filename>
293 a filename containing a certificate to add a Valid certificate entry.
295 =item B<-status serial>
297 displays the revocation status of the certificate with the specified
298 serial number and exits.
302 Updates the database index to purge expired certificates.
304 =item B<-crl_reason reason>
306 revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>,
307 B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>,
308 B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case
309 insensitive. Setting any revocation reason will make the CRL v2.
311 In practice B<removeFromCRL> is not particularly useful because it is only used
312 in delta CRLs which are not currently implemented.
314 =item B<-crl_hold instruction>
316 This sets the CRL revocation reason code to B<certificateHold> and the hold
317 instruction to B<instruction> which must be an OID. Although any OID can be
318 used only B<holdInstructionNone> (the use of which is discouraged by RFC2459)
319 B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used.
321 =item B<-crl_compromise time>
323 This sets the revocation reason to B<keyCompromise> and the compromise time to
324 B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>.
326 =item B<-crl_CA_compromise time>
328 This is the same as B<crl_compromise> except the revocation reason is set to
331 =item B<-crlexts section>
333 the section of the configuration file containing CRL extensions to
334 include. If no CRL extension section is present then a V1 CRL is
335 created, if the CRL extension section is present (even if it is
336 empty) then a V2 CRL is created. The CRL extensions specified are
337 CRL extensions and B<not> CRL entry extensions. It should be noted
338 that some software (for example Netscape) can't handle V2 CRLs. See
339 L<x509v3_config(5)> manual page for details of the
340 extension section format.
344 =head1 CONFIGURATION FILE OPTIONS
346 The section of the configuration file containing options for B<ca>
347 is found as follows: If the B<-name> command line option is used,
348 then it names the section to be used. Otherwise the section to
349 be used must be named in the B<default_ca> option of the B<ca> section
350 of the configuration file (or in the default section of the
351 configuration file). Besides B<default_ca>, the following options are
352 read directly from the B<ca> section:
356 With the exception of B<RANDFILE>, this is probably a bug and may
357 change in future releases.
359 Many of the configuration file options are identical to command line
360 options. Where the option is present in the configuration file
361 and the command line the command line value is used. Where an
362 option is described as mandatory then it must be present in
363 the configuration file or the command line equivalent (if
370 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
371 Each line of the file should consist of the numerical form of the
372 object identifier followed by white space then the short name followed
373 by white space and finally the long name.
377 This specifies a section in the configuration file containing extra
378 object identifiers. Each line should consist of the short name of the
379 object identifier followed by B<=> and the numerical form. The short
380 and long names are the same when this option is used.
382 =item B<new_certs_dir>
384 the same as the B<-outdir> command line option. It specifies
385 the directory where new certificates will be placed. Mandatory.
389 the same as B<-cert>. It gives the file containing the CA
390 certificate. Mandatory.
394 same as the B<-keyfile> option. The file containing the
395 CA private key. Mandatory.
399 a file used to read and write random number seed information, or
400 an EGD socket (see L<RAND_egd(3)>).
402 =item B<default_days>
404 the same as the B<-days> option. The number of days to certify
407 =item B<default_startdate>
409 the same as the B<-startdate> option. The start date to certify
410 a certificate for. If not set the current time is used.
412 =item B<default_enddate>
414 the same as the B<-enddate> option. Either this option or
415 B<default_days> (or the command line equivalents) must be
418 =item B<default_crl_hours default_crl_days>
420 the same as the B<-crlhours> and the B<-crldays> options. These
421 will only be used if neither command line option is present. At
422 least one of these must be present to generate a CRL.
426 the same as the B<-md> option. Mandatory.
430 the text database file to use. Mandatory. This file must be present
431 though initially it will be empty.
433 =item B<unique_subject>
435 if the value B<yes> is given, the valid certificate entries in the
436 database must have unique subjects. if the value B<no> is given,
437 several valid certificate entries may have the exact same subject.
438 The default value is B<yes>, to be compatible with older (pre 0.9.8)
439 versions of OpenSSL. However, to make CA certificate roll-over easier,
440 it's recommended to use the value B<no>, especially if combined with
441 the B<-selfsign> command line option.
445 a text file containing the next serial number to use in hex. Mandatory.
446 This file must be present and contain a valid serial number.
450 a text file containing the next CRL number to use in hex. The crl number
451 will be inserted in the CRLs only if this file exists. If this file is
452 present, it must contain a valid CRL number.
454 =item B<x509_extensions>
456 the same as B<-extensions>.
458 =item B<crl_extensions>
460 the same as B<-crlexts>.
464 the same as B<-preserveDN>
468 the same as B<-noemailDN>. If you want the EMAIL field to be removed
469 from the DN of the certificate simply set this to 'no'. If not present
470 the default is to allow for the EMAIL filed in the certificate's DN.
474 the same as B<-msie_hack>
478 the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
479 for more information.
481 =item B<name_opt>, B<cert_opt>
483 these options allow the format used to display the certificate details
484 when asking the user to confirm signing. All the options supported by
485 the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
486 here, except the B<no_signame> and B<no_sigdump> are permanently set
487 and cannot be disabled (this is because the certificate signature cannot
488 be displayed because the certificate has not been signed at this point).
490 For convenience the values B<ca_default> are accepted by both to produce
493 If neither option is present the format used in earlier versions of
494 OpenSSL is used. Use of the old format is B<strongly> discouraged because
495 it only displays fields mentioned in the B<policy> section, mishandles
496 multicharacter string types and does not display extensions.
498 =item B<copy_extensions>
500 determines how extensions in certificate requests should be handled.
501 If set to B<none> or this option is not present then extensions are
502 ignored and not copied to the certificate. If set to B<copy> then any
503 extensions present in the request that are not already present are copied
504 to the certificate. If set to B<copyall> then all extensions in the
505 request are copied to the certificate: if the extension is already present
506 in the certificate it is deleted first. See the B<WARNINGS> section before
509 The main use of this option is to allow a certificate request to supply
510 values for certain extensions such as subjectAltName.
516 The policy section consists of a set of variables corresponding to
517 certificate DN fields. If the value is "match" then the field value
518 must match the same field in the CA certificate. If the value is
519 "supplied" then it must be present. If the value is "optional" then
520 it may be present. Any fields not mentioned in the policy section
521 are silently deleted, unless the B<-preserveDN> option is set but
522 this can be regarded more of a quirk than intended behaviour.
526 The input to the B<-spkac> command line option is a Netscape
527 signed public key and challenge. This will usually come from
528 the B<KEYGEN> tag in an HTML form to create a new private key.
529 It is however possible to create SPKACs using the B<spkac> utility.
531 The file should contain the variable SPKAC set to the value of
532 the SPKAC and also the required DN components as name value pairs.
533 If you need to include the same component twice then it can be
534 preceded by a number and a '.'.
536 When processing SPKAC format, the output is DER if the B<-out>
537 flag is used, but PEM format if sending to stdout or the B<-outdir>
542 Note: these examples assume that the B<ca> directory structure is
543 already set up and the relevant files already exist. This usually
544 involves creating a CA certificate and private key with B<req>, a
545 serial number file and an empty index file and placing them in
546 the relevant directories.
548 To use the sample configuration file below the directories demoCA,
549 demoCA/private and demoCA/newcerts would be created. The CA
550 certificate would be copied to demoCA/cacert.pem and its private
551 key to demoCA/private/cakey.pem. A file demoCA/serial would be
552 created containing for example "01" and the empty index file
556 Sign a certificate request:
558 openssl ca -in req.pem -out newcert.pem
560 Sign a certificate request, using CA extensions:
562 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
566 openssl ca -gencrl -out crl.pem
568 Sign several requests:
570 openssl ca -infiles req1.pem req2.pem req3.pem
572 Certify a Netscape SPKAC:
574 openssl ca -spkac spkac.txt
576 A sample SPKAC file (the SPKAC line has been truncated for clarity):
578 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
580 emailAddress=steve@openssl.org
584 A sample configuration file with the relevant sections for B<ca>:
587 default_ca = CA_default # The default ca section
591 dir = ./demoCA # top dir
592 database = $dir/index.txt # index file.
593 new_certs_dir = $dir/newcerts # new certs dir
595 certificate = $dir/cacert.pem # The CA cert
596 serial = $dir/serial # serial no file
597 private_key = $dir/private/cakey.pem# CA private key
598 RANDFILE = $dir/private/.rand # random number file
600 default_days = 365 # how long to certify for
601 default_crl_days= 30 # how long before next CRL
602 default_md = md5 # md to use
604 policy = policy_any # default policy
605 email_in_dn = no # Don't add the email into cert DN
607 name_opt = ca_default # Subject name display option
608 cert_opt = ca_default # Certificate display option
609 copy_extensions = none # Don't copy extensions from request
612 countryName = supplied
613 stateOrProvinceName = optional
614 organizationName = optional
615 organizationalUnitName = optional
616 commonName = supplied
617 emailAddress = optional
621 Note: the location of all files can change either by compile time options,
622 configuration file entries, environment variables or command line options.
623 The values below reflect the default values.
625 /usr/local/ssl/lib/openssl.cnf - master configuration file
626 ./demoCA - main CA directory
627 ./demoCA/cacert.pem - CA certificate
628 ./demoCA/private/cakey.pem - CA private key
629 ./demoCA/serial - CA serial number file
630 ./demoCA/serial.old - CA serial number backup file
631 ./demoCA/index.txt - CA text database file
632 ./demoCA/index.txt.old - CA text database backup file
633 ./demoCA/certs - certificate output file
634 ./demoCA/.rnd - CA random seed information
636 =head1 ENVIRONMENT VARIABLES
638 B<OPENSSL_CONF> reflects the location of master configuration file it can
639 be overridden by the B<-config> command line option.
643 The text database index file is a critical part of the process and
644 if corrupted it can be difficult to fix. It is theoretically possible
645 to rebuild the index file from all the issued certificates and a current
646 CRL: however there is no option to do this.
648 V2 CRL features like delta CRLs are not currently supported.
650 Although several requests can be input and handled at once it is only
651 possible to include one SPKAC or self-signed certificate.
655 The use of an in-memory text database can cause problems when large
656 numbers of certificates are present because, as the name implies
657 the database has to be kept in memory.
659 The B<ca> command really needs rewriting or the required functionality
660 exposed at either a command or interface level so a more friendly utility
661 (perl script or GUI) can handle things properly. The script
662 B<CA.pl> helps a little but not very much.
664 Any fields in a request that are not present in a policy are silently
665 deleted. This does not happen if the B<-preserveDN> option is used. To
666 enforce the absence of the EMAIL field within the DN, as suggested by
667 RFCs, regardless the contents of the request' subject the B<-noemailDN>
668 option can be used. The behaviour should be more friendly and
671 Canceling some commands by refusing to certify a certificate can
672 create an empty file.
676 The B<ca> command is quirky and at times downright unfriendly.
678 The B<ca> utility was originally meant as an example of how to do things
679 in a CA. It was not supposed to be used as a full blown CA itself:
680 nevertheless some people are using it for this purpose.
682 The B<ca> command is effectively a single user command: no locking is
683 done on the various files and attempts to run more than one B<ca> command
684 on the same database can have unpredictable results.
686 The B<copy_extensions> option should be used with caution. If care is
687 not taken then it can be a security risk. For example if a certificate
688 request contains a basicConstraints extension with CA:TRUE and the
689 B<copy_extensions> value is set to B<copyall> and the user does not spot
690 this when the certificate is displayed then this will hand the requester
691 a valid CA certificate.
693 This situation can be avoided by setting B<copy_extensions> to B<copy>
694 and including basicConstraints with CA:FALSE in the configuration file.
695 Then if the request contains a basicConstraints extension it will be
698 It is advisable to also include values for other extensions such
699 as B<keyUsage> to prevent a request supplying its own values.
701 Additional restrictions can be placed on the CA certificate itself.
702 For example if the CA certificate has:
704 basicConstraints = CA:TRUE, pathlen:0
706 then even if a certificate is issued with CA:TRUE it will not be valid.
710 L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>,
711 L<config(5)>, L<x509v3_config(5)>
715 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
717 Licensed under the OpenSSL license (the "License"). You may not use
718 this file except in compliance with the License. You can obtain a copy
719 in the file LICENSE in the source distribution or at
720 L<https://www.openssl.org/source/license.html>.