ca(1ssl)ca(1ssl)NAMEca - Sample minimal CA application
SYNOPSIS
openssl ca [-verbose] [-config filename] [-name section] [-gencrl]
[-revoke file] [-crldays days] [-crlhours hours] [-crlexts section]
[-startdate date] [-enddate date] [-days arg] [-md arg] [-policy arg]
[-keyfile arg] [-key arg] [-passin arg] [-cert file] [-in file] [-out
file] [-notext] [-outdir dir] [-infiles] [-spkac file] [-ss_cert file]
[-preserveDN] [-batch] [-msie_hack] [-extensions section]
CA OPTIONS
Specifies the configuration file to use. Specifies the configuration
file section to use. Overrides default_ca in the ca section. An input
filename containing a single certificate request to be signed by the
CA. A single self signed certificate to be signed by the CA. A file
containing a single Netscape signed public key and challenge and addi‐
tional field values to be signed by the CA. See the NOTES section for
information on the required format. If present this should be the last
option, all subsequent arguments are assumed to the the names of files
containing certificate requests. The output file to output certifi‐
cates to. The default is standard output. The certificate details will
also be printed out to this file. The directory to output certificates
to. The certificate will be written to a filename consisting of the
serial number in hex with appended. The CA certificate file. The pri‐
vate key to sign requests with. The password used to encrypt the pri‐
vate key. Since on some systems the command line arguments are visible
(e.g. UNIX with the ps utility) this option should be used with cau‐
tion. The key password source. For more information about the format
of arg see the Pass Prhase Arguments section in
openssl(1ssl). Prints extra details about the operations being per‐
formed. Does not output the text form of a certificate to the output
file. Allows the start date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). Allows
the expiration date to be explicitly set. The format of the date is
YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). The number of
days to certify the certificate for. The message digest to use. Possi‐
ble values include md5, sha1 and mdc2. This option also applies to
CRLs. Defines the CA policy to use. This is a section in the configu‐
ration file which decides which fields should be mandatory or match the
CA certificate. See the POLICY FORMAT section for more information. A
legacy option to make ca work with very old versions of the IE certifi‐
cate enrollment control certenr3. It used UniversalStrings for almost
everything. Since the old control has various security bugs its use is
strongly discouraged. The newer control Xenroll does not need this
option. Normally the DN order of a certificate is the same as the
order of the fields in the relevant policy section. When this option is
set the order is the same as the request. This is largely for compati‐
bility with the older IE enrollment control which would only accept
certificates if their DNs match the order of the request. This is not
needed for Xenroll. Sets the batch mode. In this mode no questions
will be asked and all certificates will be certified automatically.
The section of the configuration file containing certificate extensions
to be added when a certificate is issued. If no extension section is
present then a V1 certificate is created. If the extension section is
present (even if it is empty) then a V3 certificate is created.
CRL OPTIONS
Generates a CRL based on information in the index file. The number of
days before the next CRL is due. That is the days from now to place in
the CRL next Update field. The number of hours before the next CRL is
due. A filename containing a certificate to revoke. The section of
the configuration file containing CRL extensions to include. If no CRL
extension section is present then a V1 CRL is created, if the CRL
extension section is present (even if it is empty) then a V2 CRL is
created. The CRL extensions specified are CRL extensions and not CRL
entry extensions. It should be noted that some software (such as Net‐
scape) cannot handle V2 CRLs.
CONFIGURATION FILE OPTIONS
The section of the configuration file containing options for ca is
found as follows:
If the -name command line option is used, then it names the section to
be used. Otherwise, the section to be used must be named in the
default_ca option of the ca section of the configuration file (or in
the default section of the configuration file). Besides default_ca, the
following options are read directly from the ca section:
RANDFILE
preserve
msie_hack
With the exception of RANDFILE, this is probably a bug and may change
in future releases.
Many of the configuration file options are identical to command line
options. Where the option is present in the configuration file and the
command line, the command line value is used. Where an option is
described as mandatory, then it must be present in the configuration
file or the command line equivalent (if any) is used. Specifies a file
containing additional OBJECT IDENTIFIERS. Each line of the file should
consist of the numerical form of the object identifier followed by
white space then the short name followed by white space and finally the
long name. Specifies a section in the configuration file containing
extra object identifiers. Each line should consist of the short name of
the object identifier followed by = and the numerical form. The short
and long names are the same when this option is used. The same as the
-outdir command line option. It specifies the directory where new cer‐
tificates will be placed. Mandatory. The same as the -cert option. It
gives the file containing the CA certificate. Mandatory. The same as
the -keyfile option. The file containing the CA private key. Mandatory.
A file used to read and write random number seed information, or an EGD
socket (see
RAND_egd(3)). The same as the -days option. The number of days to cer‐
tify a certificate for. The same as the -startdate option. The start
date to certify a certificate for. If not set the current time is used.
The same as the -enddate option. Either this option or default_days (or
the command line equivalents) must be present. The same as the -crl‐
hours and the -crldays options. These will only be used if neither com‐
mand line option is present. At least one of these must be present to
generate a CRL. The same as the -md option. The message digest to use.
Mandatory. The text database file to use. Mandatory. This file must be
present though initially it will be empty. A text file containing the
next serial number to use in hex. Mandatory. This file must be present
and contain a valid serial number. The same as the -extensions option.
The same as the -crlexts option. The same as the -preserveDN option.
The same as the -msie_hack option. The same as the -policy option.
Mandatory.
POLICY FORMAT
The policy section consists of a set of variables corresponding to cer‐
tificate DN fields. If the value is match then the field value must
match the same field in the CA certificate. If the value is supplied
then it must be present. If the value is optional then it may be
present. Any fields not mentioned in the policy section are silently
deleted, unless the -preserveDN option is set but this can be regarded
more of a quirk than intended behavior.
SPKAC FORMAT
The input to the -spkac command line option is a Netscape signed public
key and challenge. This will usually come from the KEYGEN tag in an
HTML form to create a new private key. It is however possible to cre‐
ate SPKACs using the spkac utility.
The file should contain the variable SPKAC set to the value of the
SPKAC and also the required DN components as name value pairs. If you
need to include the same component twice then it can be preceded by a
number and a '.'.
DESCRIPTION
The ca command is a minimal CA application. It can be used to sign cer‐
tificate requests in a variety of forms and generate CRLs it also main‐
tains a text database of issued certificates and their status.
The options descriptions will be divided into each purpose.
NOTES
The ca utility originally was meant as an example of how to do things
in a CA. It was not supposed be be used as a full blown CA; neverthe‐
less, some people are using it for this purpose.
The ca command is effectively a single user command. No locking is
done on the various files and attempts to run more than one ca command
on the same database can have unpredictable results.
RESTRICTIONS
The text database index file is a critical part of the process and if
corrupted it can be difficult to fix. It is theoretically possible to
rebuild the index file from all the issued certificates and a current
CRL. However, there is no option to do this.
CRL entry extensions cannot currently be created. Only CRL extensions
can be added.
V2 CRL features like delta CRL support and CRL numbers are not cur‐
rently supported.
Although several requests can be input and handled at once it is only
possible to include one SPKAC or self signed certificate.
The use of an in memory text database can cause problems when large
numbers of certificates are present because, as the name implies the
database has to be kept in memory.
Certificate request extensions are ignored. Some kind of policy should
be included to use certain static extensions and certain extensions
from the request.
It is not possible to certify two certificates with the same DN. This
is a side effect of how the text database is indexed and it cannot eas‐
ily be fixed without introducing other problems. Some S/MIME clients
can use two certificates with the same DN for separate signing and
encryption keys.
The ca command really needs rewriting or the required functionality
exposed at either a command or interface level so a more friendly util‐
ity (perl script or GUI) can handle things properly. The scripts CA.sh
and CA.pl help a little but not very much.
Any fields in a request that are not present in a policy are silently
deleted. This does not happen if the -preserveDN option is used but the
extra fields are not displayed when the user is asked to certify a
request. The behaviour should be more friendly and configurable.
Cancelling some commands by refusing to certify a certificate can cre‐
ate an empty file.
EXAMPLES
These examples assume that the ca directory structure is already set up
and the relevant files already exist. This usually involves creating a
CA certificate and private key with req, a serial number file and an
empty index file and placing them in the relevant directories.
To use the sample configuration file below the directories demoCA,
demoCA/private and demoCA/newcerts would be created. The CA certificate
would be copied to demoCA/cacert.pem and its private key to demoCA/pri‐
vate/cakey.pem. A file demoCA/serial would be created containing for
example "01" and the empty index file demoCA/index.txt.
Sign a certificate request:
openssl ca-in req.pem -out newcert.pem
Sign a certificate request, using CA extensions:
openssl ca-in req.pem -extensions v3_ca -out newcert.pem
Generate a CRL
openssl ca-gencrl -out crl.pem
Sign several requests:
openssl ca-infiles req1.pem req2.pem req3.pem
Certify a Netscape SPKAC:
openssl ca-spkac spkac.txt
A sample SPKAC file (the SPKAC line has been truncated for clarity):
SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBI‐
AkEAn7PDhCeV/xIxUg8V70YRxK2A5
CN=Steve Test
emailAddress=steve@openssl.org
0.OU=OpenSSL Group
1.OU=Another Group
A sample configuration file with the relevant sections for ca:
[ ca ]
default_ca = CA_default # The default ca section
[ CA_default ]
dir = ./demoCA # top dir
database = $dir/index.txt # index file.
new_certs_dir = $dir/newcerts # new certs dir
certificate = $dir/cacert.pem # The CA cert
serial = $dir/serial # serial no file
private_key = $dir/private/cakey.pem# CA private key
RANDFILE = $dir/private/.rand # random number file
default_days = 365 # how long to certify for
default_crl_days= 30 # how long before next CRL
default_md = md5 # md to use
policy = policy_any # default policy
[ policy_any ]
countryName = supplied
stateOrProvinceName = optional
organizationName = optional
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
ENVIRONMENT VARIABLES
OPENSSL_CONF reflects the location of master configuration file it can
be overridden by the -config command line option.
FILES
Note: the location of all files can change either by compile time
options, configuration file entries, environment variables or command
line options. The values below reflect the default values.
/usr/local/ssl/lib/openssl.cnf - master configuration file
./demoCA - main CA directory
./demoCA/cacert.pem - CA certificate
./demoCA/private/cakey.pem - CA private key
./demoCA/serial - CA serial number file
./demoCA/serial.old - CA serial number backup file
./demoCA/index.txt - CA text database file
./demoCA/index.txt.old - CA text database backup file
./demoCA/certs - certificate output file
./demoCA/.rnd - CA random seed information
SEE ALSO
Commands: req(1ssl), spkac(1ssl), x509(1ssl), CA.pl(1ssl)
Others: config(5)ca(1ssl)