506 lines
15 KiB
Plaintext
506 lines
15 KiB
Plaintext
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
ca - sample minimal CA application
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<openssl> B<ca>
|
|
[B<-verbose>]
|
|
[B<-config filename>]
|
|
[B<-name section>]
|
|
[B<-gencrl>]
|
|
[B<-revoke file>]
|
|
[B<-crldays days>]
|
|
[B<-crlhours hours>]
|
|
[B<-crlexts section>]
|
|
[B<-startdate date>]
|
|
[B<-enddate date>]
|
|
[B<-days arg>]
|
|
[B<-md arg>]
|
|
[B<-policy arg>]
|
|
[B<-keyfile arg>]
|
|
[B<-key arg>]
|
|
[B<-passin arg>]
|
|
[B<-cert file>]
|
|
[B<-in file>]
|
|
[B<-out file>]
|
|
[B<-notext>]
|
|
[B<-outdir dir>]
|
|
[B<-infiles>]
|
|
[B<-spkac file>]
|
|
[B<-ss_cert file>]
|
|
[B<-preserveDN>]
|
|
[B<-batch>]
|
|
[B<-msie_hack>]
|
|
[B<-extensions section>]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<ca> command is a minimal CA application. It can be used
|
|
to sign certificate requests in a variety of forms and generate
|
|
CRLs it also maintains a text database of issued certificates
|
|
and their status.
|
|
|
|
The options descriptions will be divided into each purpose.
|
|
|
|
=head1 CA OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<-config filename>
|
|
|
|
specifies the configuration file to use.
|
|
|
|
=item B<-name section>
|
|
|
|
specifies the configuration file section to use (overrides
|
|
B<default_ca> in the B<ca> section).
|
|
|
|
=item B<-in filename>
|
|
|
|
an input filename containing a single certificate request to be
|
|
signed by the CA.
|
|
|
|
=item B<-ss_cert filename>
|
|
|
|
a single self signed certificate to be signed by the CA.
|
|
|
|
=item B<-spkac filename>
|
|
|
|
a file containing a single Netscape signed public key and challenge
|
|
and additional field values to be signed by the CA. See the B<NOTES>
|
|
section for information on the required format.
|
|
|
|
=item B<-infiles>
|
|
|
|
if present this should be the last option, all subsequent arguments
|
|
are assumed to the the names of files containing certificate requests.
|
|
|
|
=item B<-out filename>
|
|
|
|
the output file to output certificates to. The default is standard
|
|
output. The certificate details will also be printed out to this
|
|
file.
|
|
|
|
=item B<-outdir directory>
|
|
|
|
the directory to output certificates to. The certificate will be
|
|
written to a filename consisting of the serial number in hex with
|
|
".pem" appended.
|
|
|
|
=item B<-cert>
|
|
|
|
the CA certificate file.
|
|
|
|
=item B<-keyfile filename>
|
|
|
|
the private key to sign requests with.
|
|
|
|
=item B<-key password>
|
|
|
|
the password used to encrypt the private key. Since on some
|
|
systems the command line arguments are visible (e.g. Unix with
|
|
the 'ps' utility) this option should be used with caution.
|
|
|
|
=item B<-passin arg>
|
|
|
|
the key password source. For more information about the format of B<arg>
|
|
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
|
|
=item B<-verbose>
|
|
|
|
this prints extra details about the operations being performed.
|
|
|
|
=item B<-notext>
|
|
|
|
don't output the text form of a certificate to the output file.
|
|
|
|
=item B<-startdate date>
|
|
|
|
this allows the start date to be explicitly set. The format of the
|
|
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
|
|
|
|
=item B<-enddate date>
|
|
|
|
this allows the expiry date to be explicitly set. The format of the
|
|
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
|
|
|
|
=item B<-days arg>
|
|
|
|
the number of days to certify the certificate for.
|
|
|
|
=item B<-md alg>
|
|
|
|
the message digest to use. Possible values include md5, sha1 and mdc2.
|
|
This option also applies to CRLs.
|
|
|
|
=item B<-policy arg>
|
|
|
|
this option defines the CA "policy" to use. This is a section in
|
|
the configuration file which decides which fields should be mandatory
|
|
or match the CA certificate. Check out the B<POLICY FORMAT> section
|
|
for more information.
|
|
|
|
=item B<-msie_hack>
|
|
|
|
this is a legacy option to make B<ca> work with very old versions of
|
|
the IE certificate 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.
|
|
|
|
=item B<-preserveDN>
|
|
|
|
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 compatibility 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.
|
|
|
|
=item B<-batch>
|
|
|
|
this sets the batch mode. In this mode no questions will be asked
|
|
and all certificates will be certified automatically.
|
|
|
|
=item B<-extensions section>
|
|
|
|
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.
|
|
|
|
=back
|
|
|
|
=head1 CRL OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<-gencrl>
|
|
|
|
this option generates a CRL based on information in the index file.
|
|
|
|
=item B<-crldays num>
|
|
|
|
the number of days before the next CRL is due. That is the days from
|
|
now to place in the CRL nextUpdate field.
|
|
|
|
=item B<-crlhours num>
|
|
|
|
the number of hours before the next CRL is due.
|
|
|
|
=item B<-revoke filename>
|
|
|
|
a filename containing a certificate to revoke.
|
|
|
|
=item B<-crlexts section>
|
|
|
|
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 B<not> CRL entry extensions. It should be noted
|
|
that some software (for example Netscape) can't handle V2 CRLs.
|
|
|
|
=back
|
|
|
|
=head1 CONFIGURATION FILE OPTIONS
|
|
|
|
The section of the configuration file containing options for B<ca>
|
|
is found as follows: If the B<-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 B<default_ca> option of the B<ca> section
|
|
of the configuration file (or in the default section of the
|
|
configuration file). Besides B<default_ca>, the following options are
|
|
read directly from the B<ca> section:
|
|
RANDFILE
|
|
preserve
|
|
msie_hack
|
|
With the exception of B<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) used.
|
|
|
|
=over 4
|
|
|
|
=item B<oid_file>
|
|
|
|
This specifies a file containing additional B<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.
|
|
|
|
=item B<oid_section>
|
|
|
|
This 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 B<=> and the numerical form. The short
|
|
and long names are the same when this option is used.
|
|
|
|
=item B<new_certs_dir>
|
|
|
|
the same as the B<-outdir> command line option. It specifies
|
|
the directory where new certificates will be placed. Mandatory.
|
|
|
|
=item B<certificate>
|
|
|
|
the same as B<-cert>. It gives the file containing the CA
|
|
certificate. Mandatory.
|
|
|
|
=item B<private_key>
|
|
|
|
same as the B<-keyfile> option. The file containing the
|
|
CA private key. Mandatory.
|
|
|
|
=item B<RANDFILE>
|
|
|
|
a file used to read and write random number seed information, or
|
|
an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
|
|
|
|
=item B<default_days>
|
|
|
|
the same as the B<-days> option. The number of days to certify
|
|
a certificate for.
|
|
|
|
=item B<default_startdate>
|
|
|
|
the same as the B<-startdate> option. The start date to certify
|
|
a certificate for. If not set the current time is used.
|
|
|
|
=item B<default_enddate>
|
|
|
|
the same as the B<-enddate> option. Either this option or
|
|
B<default_days> (or the command line equivalents) must be
|
|
present.
|
|
|
|
=item B<default_crl_hours default_crl_days>
|
|
|
|
the same as the B<-crlhours> and the B<-crldays> options. These
|
|
will only be used if neither command line option is present. At
|
|
least one of these must be present to generate a CRL.
|
|
|
|
=item B<default_md>
|
|
|
|
the same as the B<-md> option. The message digest to use. Mandatory.
|
|
|
|
=item B<database>
|
|
|
|
the text database file to use. Mandatory. This file must be present
|
|
though initially it will be empty.
|
|
|
|
=item B<serialfile>
|
|
|
|
a text file containing the next serial number to use in hex. Mandatory.
|
|
This file must be present and contain a valid serial number.
|
|
|
|
=item B<x509_extensions>
|
|
|
|
the same as B<-extensions>.
|
|
|
|
=item B<crl_extensions>
|
|
|
|
the same as B<-crlexts>.
|
|
|
|
=item B<preserve>
|
|
|
|
the same as B<-preserveDN>
|
|
|
|
=item B<msie_hack>
|
|
|
|
the same as B<-msie_hack>
|
|
|
|
=item B<policy>
|
|
|
|
the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
|
|
for more information.
|
|
|
|
=back
|
|
|
|
=head1 POLICY FORMAT
|
|
|
|
The policy section consists of a set of variables corresponding to
|
|
certificate 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 B<-preserveDN> option is set but
|
|
this can be regarded more of a quirk than intended behaviour.
|
|
|
|
=head1 SPKAC FORMAT
|
|
|
|
The input to the B<-spkac> command line option is a Netscape
|
|
signed public key and challenge. This will usually come from
|
|
the B<KEYGEN> tag in an HTML form to create a new private key.
|
|
It is however possible to create SPKACs using the B<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 '.'.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Note: these examples assume that the B<ca> directory structure is
|
|
already set up and the relevant files already exist. This usually
|
|
involves creating a CA certificate and private key with B<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/private/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=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/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 B<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
|
|
|
|
=head1 WARNINGS
|
|
|
|
The B<ca> command is quirky and at times downright unfriendly.
|
|
|
|
The B<ca> utility was originally meant as an example of how to do things
|
|
in a CA. It was not supposed be be used as a full blown CA itself:
|
|
nevertheless some people are using it for this purpose.
|
|
|
|
The B<ca> command is effectively a single user command: no locking is
|
|
done on the various files and attempts to run more than one B<ca> command
|
|
on the same database can have unpredictable results.
|
|
|
|
=head1 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
|
|
|
|
=head1 ENVIRONMENT VARIABLES
|
|
|
|
B<OPENSSL_CONF> reflects the location of master configuration file it can
|
|
be overridden by the B<-config> command line option.
|
|
|
|
=head1 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 currently
|
|
supported.
|
|
|
|
Although several requests can be input and handled at once it is only
|
|
possible to include one SPKAC or self signed certificate.
|
|
|
|
=head1 BUGS
|
|
|
|
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 easily
|
|
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 B<ca> command really needs rewriting or the required functionality
|
|
exposed at either a command or interface level so a more friendly utility
|
|
(perl script or GUI) can handle things properly. The scripts B<CA.sh> and
|
|
B<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 B<-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
|
|
create an empty file.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>,
|
|
L<config(5)|config(5)>
|
|
|
|
=cut
|