861 lines
36 KiB
HTML
861 lines
36 KiB
HTML
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>ca</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#options">OPTIONS</a></li>
|
|
<li><a href="#crl_options">CRL OPTIONS</a></li>
|
|
<li><a href="#configuration_file_options">CONFIGURATION FILE OPTIONS</a></li>
|
|
<li><a href="#policy_format">POLICY FORMAT</a></li>
|
|
<li><a href="#spkac_format">SPKAC FORMAT</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#files">FILES</a></li>
|
|
<li><a href="#restrictions">RESTRICTIONS</a></li>
|
|
<li><a href="#bugs">BUGS</a></li>
|
|
<li><a href="#warnings">WARNINGS</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>openssl-ca,
|
|
ca - sample minimal CA application</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<p><strong>openssl</strong> <strong>ca</strong>
|
|
[<strong>-help</strong>]
|
|
[<strong>-verbose</strong>]
|
|
[<strong>-config filename</strong>]
|
|
[<strong>-name section</strong>]
|
|
[<strong>-gencrl</strong>]
|
|
[<strong>-revoke file</strong>]
|
|
[<strong>-valid file</strong>]
|
|
[<strong>-status serial</strong>]
|
|
[<strong>-updatedb</strong>]
|
|
[<strong>-crl_reason reason</strong>]
|
|
[<strong>-crl_hold instruction</strong>]
|
|
[<strong>-crl_compromise time</strong>]
|
|
[<strong>-crl_CA_compromise time</strong>]
|
|
[<strong>-crldays days</strong>]
|
|
[<strong>-crlhours hours</strong>]
|
|
[<strong>-crlexts section</strong>]
|
|
[<strong>-startdate date</strong>]
|
|
[<strong>-enddate date</strong>]
|
|
[<strong>-days arg</strong>]
|
|
[<strong>-md arg</strong>]
|
|
[<strong>-policy arg</strong>]
|
|
[<strong>-keyfile arg</strong>]
|
|
[<strong>-keyform PEM|DER</strong>]
|
|
[<strong>-key arg</strong>]
|
|
[<strong>-passin arg</strong>]
|
|
[<strong>-cert file</strong>]
|
|
[<strong>-selfsign</strong>]
|
|
[<strong>-in file</strong>]
|
|
[<strong>-out file</strong>]
|
|
[<strong>-notext</strong>]
|
|
[<strong>-outdir dir</strong>]
|
|
[<strong>-infiles</strong>]
|
|
[<strong>-spkac file</strong>]
|
|
[<strong>-ss_cert file</strong>]
|
|
[<strong>-preserveDN</strong>]
|
|
[<strong>-noemailDN</strong>]
|
|
[<strong>-batch</strong>]
|
|
[<strong>-msie_hack</strong>]
|
|
[<strong>-extensions section</strong>]
|
|
[<strong>-extfile section</strong>]
|
|
[<strong>-engine id</strong>]
|
|
[<strong>-subj arg</strong>]
|
|
[<strong>-utf8</strong>]
|
|
[<strong>-sigopt nm:v</strong>]
|
|
[<strong>-create_serial</strong>]
|
|
[<strong>-rand_serial</strong>]
|
|
[<strong>-multivalue-rdn</strong>]
|
|
[<strong>-rand file...</strong>]
|
|
[<strong>-writerand file</strong>]</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>The <strong>ca</strong> 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.</p>
|
|
<p>The options descriptions will be divided into each purpose.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="options">OPTIONS</a></h1>
|
|
<dl>
|
|
<dt><strong><a name="help" class="item"><strong>-help</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Print out a usage message.</p>
|
|
</dd>
|
|
<dt><strong><a name="verbose" class="item"><strong>-verbose</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This prints extra details about the operations being performed.</p>
|
|
</dd>
|
|
<dt><strong><a name="config_filename" class="item"><strong>-config filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Specifies the configuration file to use.
|
|
Optional; for a description of the default value,
|
|
see <em>openssl(1)/COMMAND SUMMARY</em>.</p>
|
|
</dd>
|
|
<dt><strong><a name="name_section" class="item"><strong>-name section</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Specifies the configuration file section to use (overrides
|
|
<strong>default_ca</strong> in the <strong>ca</strong> section).</p>
|
|
</dd>
|
|
<dt><strong><a name="in_filename" class="item"><strong>-in filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>An input filename containing a single certificate request to be
|
|
signed by the CA.</p>
|
|
</dd>
|
|
<dt><strong><a name="ss_cert_filename" class="item"><strong>-ss_cert filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>A single self-signed certificate to be signed by the CA.</p>
|
|
</dd>
|
|
<dt><strong><a name="spkac_filename" class="item"><strong>-spkac filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>A file containing a single Netscape signed public key and challenge
|
|
and additional field values to be signed by the CA. See the <strong>SPKAC FORMAT</strong>
|
|
section for information on the required input and output format.</p>
|
|
</dd>
|
|
<dt><strong><a name="infiles" class="item"><strong>-infiles</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>If present this should be the last option, all subsequent arguments
|
|
are taken as the names of files containing certificate requests.</p>
|
|
</dd>
|
|
<dt><strong><a name="out_filename" class="item"><strong>-out filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The output file to output certificates to. The default is standard
|
|
output. The certificate details will also be printed out to this
|
|
file in PEM format (except that <strong>-spkac</strong> outputs DER format).</p>
|
|
</dd>
|
|
<dt><strong><a name="outdir_directory" class="item"><strong>-outdir directory</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The directory to output certificates to. The certificate will be
|
|
written to a filename consisting of the serial number in hex with
|
|
".pem" appended.</p>
|
|
</dd>
|
|
<dt><strong><a name="cert" class="item"><strong>-cert</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The CA certificate file.</p>
|
|
</dd>
|
|
<dt><strong><a name="keyfile_filename" class="item"><strong>-keyfile filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The private key to sign requests with.</p>
|
|
</dd>
|
|
<dt><strong><a name="keyform_pem_der" class="item"><strong>-keyform PEM|DER</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The format of the data in the private key file.
|
|
The default is PEM.</p>
|
|
</dd>
|
|
<dt><strong><a name="sigopt_nm_v" class="item"><strong>-sigopt nm:v</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Pass options to the signature algorithm during sign or verify operations.
|
|
Names and values of these options are algorithm-specific.</p>
|
|
</dd>
|
|
<dt><strong><a name="key_password" class="item"><strong>-key password</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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.</p>
|
|
</dd>
|
|
<dt><strong><a name="selfsign" class="item"><strong>-selfsign</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Indicates the issued certificates are to be signed with the key
|
|
the certificate requests were signed with (given with <strong>-keyfile</strong>).
|
|
Certificate requests signed with a different key are ignored. If
|
|
<strong>-spkac</strong>, <strong>-ss_cert</strong> or <strong>-gencrl</strong> are given, <strong>-selfsign</strong> is
|
|
ignored.</p>
|
|
<p>A consequence of using <strong>-selfsign</strong> is that the self-signed
|
|
certificate appears among the entries in the certificate database
|
|
(see the configuration option <strong>database</strong>), and uses the same
|
|
serial number counter as all other certificates sign with the
|
|
self-signed certificate.</p>
|
|
</dd>
|
|
<dt><strong><a name="passin_arg" class="item"><strong>-passin arg</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The key password source. For more information about the format of <strong>arg</strong>
|
|
see the <strong>PASS PHRASE ARGUMENTS</strong> section in <em>openssl(1)</em>.</p>
|
|
</dd>
|
|
<dt><strong><a name="notext" class="item"><strong>-notext</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Don't output the text form of a certificate to the output file.</p>
|
|
</dd>
|
|
<dt><strong><a name="startdate_date" class="item"><strong>-startdate date</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This allows the start date to be explicitly set. The format of the
|
|
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
|
|
YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
|
|
both formats, seconds SS and timezone Z must be present.</p>
|
|
</dd>
|
|
<dt><strong><a name="enddate_date" class="item"><strong>-enddate date</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This allows the expiry date to be explicitly set. The format of the
|
|
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
|
|
YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
|
|
both formats, seconds SS and timezone Z must be present.</p>
|
|
</dd>
|
|
<dt><strong><a name="days_arg" class="item"><strong>-days arg</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The number of days to certify the certificate for.</p>
|
|
</dd>
|
|
<dt><strong><a name="md_alg" class="item"><strong>-md alg</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The message digest to use.
|
|
Any digest supported by the OpenSSL <strong>dgst</strong> command can be used. For signing
|
|
algorithms that do not support a digest (i.e. Ed25519 and Ed448) any message
|
|
digest that is set is ignored. This option also applies to CRLs.</p>
|
|
</dd>
|
|
<dt><strong><a name="policy_arg" class="item"><strong>-policy arg</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <strong>POLICY FORMAT</strong> section
|
|
for more information.</p>
|
|
</dd>
|
|
<dt><strong><a name="msie_hack" class="item"><strong>-msie_hack</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This is a deprecated option to make <strong>ca</strong> 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.</p>
|
|
</dd>
|
|
<dt><strong><a name="preservedn" class="item"><strong>-preserveDN</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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.</p>
|
|
</dd>
|
|
<dt><strong><a name="noemaildn" class="item"><strong>-noemailDN</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The DN of a certificate can contain the EMAIL field if present in the
|
|
request DN, however it is good policy just having the e-mail set into
|
|
the altName extension of the certificate. When this option is set the
|
|
EMAIL field is removed from the certificate' subject and set only in
|
|
the, eventually present, extensions. The <strong>email_in_dn</strong> keyword can be
|
|
used in the configuration file to enable this behaviour.</p>
|
|
</dd>
|
|
<dt><strong><a name="batch" class="item"><strong>-batch</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the batch mode. In this mode no questions will be asked
|
|
and all certificates will be certified automatically.</p>
|
|
</dd>
|
|
<dt><strong><a name="extensions_section" class="item"><strong>-extensions section</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The section of the configuration file containing certificate extensions
|
|
to be added when a certificate is issued (defaults to <strong>x509_extensions</strong>
|
|
unless the <strong>-extfile</strong> option is used). 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. See the
|
|
<em>x509v3_config(5)</em> manual page for details of the
|
|
extension section format.</p>
|
|
</dd>
|
|
<dt><strong><a name="extfile_file" class="item"><strong>-extfile file</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>An additional configuration file to read certificate extensions from
|
|
(using the default section unless the <strong>-extensions</strong> option is also
|
|
used).</p>
|
|
</dd>
|
|
<dt><strong><a name="engine_id" class="item"><strong>-engine id</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Specifying an engine (by its unique <strong>id</strong> string) will cause <strong>ca</strong>
|
|
to attempt to obtain a functional reference to the specified engine,
|
|
thus initialising it if needed. The engine will then be set as the default
|
|
for all available algorithms.</p>
|
|
</dd>
|
|
<dt><strong><a name="subj_arg" class="item"><strong>-subj arg</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Supersedes subject name given in the request.
|
|
The arg must be formatted as <em>/type0=value0/type1=value1/type2=...</em>.
|
|
Keyword characters may be escaped by \ (backslash), and whitespace is retained.
|
|
Empty values are permitted, but the corresponding type will not be included
|
|
in the resulting certificate.</p>
|
|
</dd>
|
|
<dt><strong><a name="utf8" class="item"><strong>-utf8</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This option causes field values to be interpreted as UTF8 strings, by
|
|
default they are interpreted as ASCII. This means that the field
|
|
values, whether prompted from a terminal or obtained from a
|
|
configuration file, must be valid UTF8 strings.</p>
|
|
</dd>
|
|
<dt><strong><a name="create_serial" class="item"><strong>-create_serial</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>If reading serial from the text file as specified in the configuration
|
|
fails, specifying this option creates a new random serial to be used as next
|
|
serial number.
|
|
To get random serial numbers, use the <strong>-rand_serial</strong> flag instead; this
|
|
should only be used for simple error-recovery.</p>
|
|
</dd>
|
|
<dt><strong><a name="rand_serial" class="item"><strong>-rand_serial</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Generate a large random number to use as the serial number.
|
|
This overrides any option or configuration to use a serial number file.</p>
|
|
</dd>
|
|
<dt><strong><a name="multivalue_rdn" class="item"><strong>-multivalue-rdn</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This option causes the -subj argument to be interpreted with full
|
|
support for multivalued RDNs. Example:</p>
|
|
<p><em>/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe</em></p>
|
|
<p>If -multi-rdn is not used then the UID value is <em>123456+CN=John Doe</em>.</p>
|
|
</dd>
|
|
<dt><strong><a name="rand_file" class="item"><strong>-rand file...</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>A file or files containing random data used to seed the random number
|
|
generator.
|
|
Multiple files can be specified separated by an OS-dependent character.
|
|
The separator is <strong>;</strong> for MS-Windows, <strong>,</strong> for OpenVMS, and <strong>:</strong> for
|
|
all others.</p>
|
|
</dd>
|
|
<dt><strong><a name="writerand_file" class="item">[<strong>-writerand file</strong>]</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Writes random data to the specified <em>file</em> upon exit.
|
|
This can be used with a subsequent <strong>-rand</strong> flag.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="crl_options">CRL OPTIONS</a></h1>
|
|
<dl>
|
|
<dt><strong><a name="gencrl" class="item"><strong>-gencrl</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This option generates a CRL based on information in the index file.</p>
|
|
</dd>
|
|
<dt><strong><a name="crldays_num" class="item"><strong>-crldays num</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The number of days before the next CRL is due. That is the days from
|
|
now to place in the CRL nextUpdate field.</p>
|
|
</dd>
|
|
<dt><strong><a name="crlhours_num" class="item"><strong>-crlhours num</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The number of hours before the next CRL is due.</p>
|
|
</dd>
|
|
<dt><strong><a name="revoke_filename" class="item"><strong>-revoke filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>A filename containing a certificate to revoke.</p>
|
|
</dd>
|
|
<dt><strong><a name="valid_filename" class="item"><strong>-valid filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>A filename containing a certificate to add a Valid certificate entry.</p>
|
|
</dd>
|
|
<dt><strong><a name="status_serial" class="item"><strong>-status serial</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Displays the revocation status of the certificate with the specified
|
|
serial number and exits.</p>
|
|
</dd>
|
|
<dt><strong><a name="updatedb" class="item"><strong>-updatedb</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Updates the database index to purge expired certificates.</p>
|
|
</dd>
|
|
<dt><strong><a name="crl_reason_reason" class="item"><strong>-crl_reason reason</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Revocation reason, where <strong>reason</strong> is one of: <strong>unspecified</strong>, <strong>keyCompromise</strong>,
|
|
<strong>CACompromise</strong>, <strong>affiliationChanged</strong>, <strong>superseded</strong>, <strong>cessationOfOperation</strong>,
|
|
<strong>certificateHold</strong> or <strong>removeFromCRL</strong>. The matching of <strong>reason</strong> is case
|
|
insensitive. Setting any revocation reason will make the CRL v2.</p>
|
|
<p>In practice <strong>removeFromCRL</strong> is not particularly useful because it is only used
|
|
in delta CRLs which are not currently implemented.</p>
|
|
</dd>
|
|
<dt><strong><a name="crl_hold_instruction" class="item"><strong>-crl_hold instruction</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the CRL revocation reason code to <strong>certificateHold</strong> and the hold
|
|
instruction to <strong>instruction</strong> which must be an OID. Although any OID can be
|
|
used only <strong>holdInstructionNone</strong> (the use of which is discouraged by <a href="http://www.ietf.org/rfc/rfc2459.txt" class="rfc">RFC2459</a>)
|
|
<strong>holdInstructionCallIssuer</strong> or <strong>holdInstructionReject</strong> will normally be used.</p>
|
|
</dd>
|
|
<dt><strong><a name="crl_compromise_time" class="item"><strong>-crl_compromise time</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the revocation reason to <strong>keyCompromise</strong> and the compromise time to
|
|
<strong>time</strong>. <strong>time</strong> should be in GeneralizedTime format that is <strong>YYYYMMDDHHMMSSZ</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="crl_ca_compromise_time" class="item"><strong>-crl_CA_compromise time</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This is the same as <strong>crl_compromise</strong> except the revocation reason is set to
|
|
<strong>CACompromise</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="crlexts_section" class="item"><strong>-crlexts section</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <strong>not</strong> CRL entry extensions. It should be noted
|
|
that some software (for example Netscape) can't handle V2 CRLs. See
|
|
<em>x509v3_config(5)</em> manual page for details of the
|
|
extension section format.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="configuration_file_options">CONFIGURATION FILE OPTIONS</a></h1>
|
|
<p>The section of the configuration file containing options for <strong>ca</strong>
|
|
is found as follows: If the <strong>-name</strong> command line option is used,
|
|
then it names the section to be used. Otherwise the section to
|
|
be used must be named in the <strong>default_ca</strong> option of the <strong>ca</strong> section
|
|
of the configuration file (or in the default section of the
|
|
configuration file). Besides <strong>default_ca</strong>, the following options are
|
|
read directly from the <strong>ca</strong> section:
|
|
RANDFILE
|
|
preserve
|
|
msie_hack
|
|
With the exception of <strong>RANDFILE</strong>, this is probably a bug and may
|
|
change in future releases.</p>
|
|
<p>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.</p>
|
|
<dl>
|
|
<dt><strong><a name="oid_file" class="item"><strong>oid_file</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This specifies a file containing additional <strong>OBJECT IDENTIFIERS</strong>.
|
|
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.</p>
|
|
</dd>
|
|
<dt><strong><a name="oid_section" class="item"><strong>oid_section</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <strong>=</strong> and the numerical form. The short
|
|
and long names are the same when this option is used.</p>
|
|
</dd>
|
|
<dt><strong><a name="new_certs_dir" class="item"><strong>new_certs_dir</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as the <strong>-outdir</strong> command line option. It specifies
|
|
the directory where new certificates will be placed. Mandatory.</p>
|
|
</dd>
|
|
<dt><strong><a name="certificate" class="item"><strong>certificate</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as <strong>-cert</strong>. It gives the file containing the CA
|
|
certificate. Mandatory.</p>
|
|
</dd>
|
|
<dt><strong><a name="private_key" class="item"><strong>private_key</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Same as the <strong>-keyfile</strong> option. The file containing the
|
|
CA private key. Mandatory.</p>
|
|
</dd>
|
|
<dt><strong><a name="randfile" class="item"><strong>RANDFILE</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>At startup the specified file is loaded into the random number generator,
|
|
and at exit 256 bytes will be written to it.</p>
|
|
</dd>
|
|
<dt><strong><a name="default_days" class="item"><strong>default_days</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as the <strong>-days</strong> option. The number of days to certify
|
|
a certificate for.</p>
|
|
</dd>
|
|
<dt><strong><a name="default_startdate" class="item"><strong>default_startdate</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as the <strong>-startdate</strong> option. The start date to certify
|
|
a certificate for. If not set the current time is used.</p>
|
|
</dd>
|
|
<dt><strong><a name="default_enddate" class="item"><strong>default_enddate</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as the <strong>-enddate</strong> option. Either this option or
|
|
<strong>default_days</strong> (or the command line equivalents) must be
|
|
present.</p>
|
|
</dd>
|
|
<dt><strong><a name="default_crl_hours_default_crl_days" class="item"><strong>default_crl_hours default_crl_days</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as the <strong>-crlhours</strong> and the <strong>-crldays</strong> 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.</p>
|
|
</dd>
|
|
<dt><strong><a name="default_md" class="item"><strong>default_md</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as the <strong>-md</strong> option. Mandatory except where the signing algorithm does
|
|
not require a digest (i.e. Ed25519 and Ed448).</p>
|
|
</dd>
|
|
<dt><strong><a name="database" class="item"><strong>database</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The text database file to use. Mandatory. This file must be present
|
|
though initially it will be empty.</p>
|
|
</dd>
|
|
<dt><strong><a name="unique_subject" class="item"><strong>unique_subject</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>If the value <strong>yes</strong> is given, the valid certificate entries in the
|
|
database must have unique subjects. if the value <strong>no</strong> is given,
|
|
several valid certificate entries may have the exact same subject.
|
|
The default value is <strong>yes</strong>, to be compatible with older (pre 0.9.8)
|
|
versions of OpenSSL. However, to make CA certificate roll-over easier,
|
|
it's recommended to use the value <strong>no</strong>, especially if combined with
|
|
the <strong>-selfsign</strong> command line option.</p>
|
|
<p>Note that it is valid in some circumstances for certificates to be created
|
|
without any subject. In the case where there are multiple certificates without
|
|
subjects this does not count as a duplicate.</p>
|
|
</dd>
|
|
<dt><strong><a name="serial" class="item"><strong>serial</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>A text file containing the next serial number to use in hex. Mandatory.
|
|
This file must be present and contain a valid serial number.</p>
|
|
</dd>
|
|
<dt><strong><a name="crlnumber" class="item"><strong>crlnumber</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>A text file containing the next CRL number to use in hex. The crl number
|
|
will be inserted in the CRLs only if this file exists. If this file is
|
|
present, it must contain a valid CRL number.</p>
|
|
</dd>
|
|
<dt><strong><a name="x509_extensions" class="item"><strong>x509_extensions</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as <strong>-extensions</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="crl_extensions" class="item"><strong>crl_extensions</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as <strong>-crlexts</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="preserve" class="item"><strong>preserve</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as <strong>-preserveDN</strong></p>
|
|
</dd>
|
|
<dt><strong><a name="email_in_dn" class="item"><strong>email_in_dn</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as <strong>-noemailDN</strong>. If you want the EMAIL field to be removed
|
|
from the DN of the certificate simply set this to 'no'. If not present
|
|
the default is to allow for the EMAIL filed in the certificate's DN.</p>
|
|
</dd>
|
|
<dt><strong><strong>msie_hack</strong></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as <strong>-msie_hack</strong></p>
|
|
</dd>
|
|
<dt><strong><a name="policy" class="item"><strong>policy</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The same as <strong>-policy</strong>. Mandatory. See the <strong>POLICY FORMAT</strong> section
|
|
for more information.</p>
|
|
</dd>
|
|
<dt><strong><a name="name_opt_cert_opt" class="item"><strong>name_opt</strong>, <strong>cert_opt</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>These options allow the format used to display the certificate details
|
|
when asking the user to confirm signing. All the options supported by
|
|
the <strong>x509</strong> utilities <strong>-nameopt</strong> and <strong>-certopt</strong> switches can be used
|
|
here, except the <strong>no_signame</strong> and <strong>no_sigdump</strong> are permanently set
|
|
and cannot be disabled (this is because the certificate signature cannot
|
|
be displayed because the certificate has not been signed at this point).</p>
|
|
<p>For convenience the values <strong>ca_default</strong> are accepted by both to produce
|
|
a reasonable output.</p>
|
|
<p>If neither option is present the format used in earlier versions of
|
|
OpenSSL is used. Use of the old format is <strong>strongly</strong> discouraged because
|
|
it only displays fields mentioned in the <strong>policy</strong> section, mishandles
|
|
multicharacter string types and does not display extensions.</p>
|
|
</dd>
|
|
<dt><strong><a name="copy_extensions" class="item"><strong>copy_extensions</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Determines how extensions in certificate requests should be handled.
|
|
If set to <strong>none</strong> or this option is not present then extensions are
|
|
ignored and not copied to the certificate. If set to <strong>copy</strong> then any
|
|
extensions present in the request that are not already present are copied
|
|
to the certificate. If set to <strong>copyall</strong> then all extensions in the
|
|
request are copied to the certificate: if the extension is already present
|
|
in the certificate it is deleted first. See the <strong>WARNINGS</strong> section before
|
|
using this option.</p>
|
|
<p>The main use of this option is to allow a certificate request to supply
|
|
values for certain extensions such as subjectAltName.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="policy_format">POLICY FORMAT</a></h1>
|
|
<p>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 <strong>-preserveDN</strong> option is set but
|
|
this can be regarded more of a quirk than intended behaviour.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="spkac_format">SPKAC FORMAT</a></h1>
|
|
<p>The input to the <strong>-spkac</strong> command line option is a Netscape
|
|
signed public key and challenge. This will usually come from
|
|
the <strong>KEYGEN</strong> tag in an HTML form to create a new private key.
|
|
It is however possible to create SPKACs using the <strong>spkac</strong> utility.</p>
|
|
<p>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 '.'.</p>
|
|
<p>When processing SPKAC format, the output is DER if the <strong>-out</strong>
|
|
flag is used, but PEM format if sending to stdout or the <strong>-outdir</strong>
|
|
flag is used.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>Note: these examples assume that the <strong>ca</strong> directory structure is
|
|
already set up and the relevant files already exist. This usually
|
|
involves creating a CA certificate and private key with <strong>req</strong>, a
|
|
serial number file and an empty index file and placing them in
|
|
the relevant directories.</p>
|
|
<p>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.</p>
|
|
<p>Sign a certificate request:</p>
|
|
<pre>
|
|
openssl ca -in req.pem -out newcert.pem</pre>
|
|
<p>Sign a certificate request, using CA extensions:</p>
|
|
<pre>
|
|
openssl ca -in req.pem -extensions v3_ca -out newcert.pem</pre>
|
|
<p>Generate a CRL</p>
|
|
<pre>
|
|
openssl ca -gencrl -out crl.pem</pre>
|
|
<p>Sign several requests:</p>
|
|
<pre>
|
|
openssl ca -infiles req1.pem req2.pem req3.pem</pre>
|
|
<p>Certify a Netscape SPKAC:</p>
|
|
<pre>
|
|
openssl ca -spkac spkac.txt</pre>
|
|
<p>A sample SPKAC file (the SPKAC line has been truncated for clarity):</p>
|
|
<pre>
|
|
SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
|
|
CN=Steve Test
|
|
emailAddress=steve@openssl.org
|
|
0.OU=OpenSSL Group
|
|
1.OU=Another Group</pre>
|
|
<p>A sample configuration file with the relevant sections for <strong>ca</strong>:</p>
|
|
<pre>
|
|
[ ca ]
|
|
default_ca = CA_default # The default ca section</pre>
|
|
<pre>
|
|
[ CA_default ]</pre>
|
|
<pre>
|
|
dir = ./demoCA # top dir
|
|
database = $dir/index.txt # index file.
|
|
new_certs_dir = $dir/newcerts # new certs dir</pre>
|
|
<pre>
|
|
certificate = $dir/cacert.pem # The CA cert
|
|
serial = $dir/serial # serial no file
|
|
#rand_serial = yes # for random serial#'s
|
|
private_key = $dir/private/cakey.pem# CA private key
|
|
RANDFILE = $dir/private/.rand # random number file</pre>
|
|
<pre>
|
|
default_days = 365 # how long to certify for
|
|
default_crl_days= 30 # how long before next CRL
|
|
default_md = md5 # md to use</pre>
|
|
<pre>
|
|
policy = policy_any # default policy
|
|
email_in_dn = no # Don't add the email into cert DN</pre>
|
|
<pre>
|
|
name_opt = ca_default # Subject name display option
|
|
cert_opt = ca_default # Certificate display option
|
|
copy_extensions = none # Don't copy extensions from request</pre>
|
|
<pre>
|
|
[ policy_any ]
|
|
countryName = supplied
|
|
stateOrProvinceName = optional
|
|
organizationName = optional
|
|
organizationalUnitName = optional
|
|
commonName = supplied
|
|
emailAddress = optional</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="files">FILES</a></h1>
|
|
<p>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.</p>
|
|
<pre>
|
|
/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</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="restrictions">RESTRICTIONS</a></h1>
|
|
<p>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.</p>
|
|
<p>V2 CRL features like delta CRLs are not currently supported.</p>
|
|
<p>Although several requests can be input and handled at once it is only
|
|
possible to include one SPKAC or self-signed certificate.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="bugs">BUGS</a></h1>
|
|
<p>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.</p>
|
|
<p>The <strong>ca</strong> 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 script
|
|
<strong>CA.pl</strong> helps a little but not very much.</p>
|
|
<p>Any fields in a request that are not present in a policy are silently
|
|
deleted. This does not happen if the <strong>-preserveDN</strong> option is used. To
|
|
enforce the absence of the EMAIL field within the DN, as suggested by
|
|
RFCs, regardless the contents of the request' subject the <strong>-noemailDN</strong>
|
|
option can be used. The behaviour should be more friendly and
|
|
configurable.</p>
|
|
<p>Canceling some commands by refusing to certify a certificate can
|
|
create an empty file.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="warnings">WARNINGS</a></h1>
|
|
<p>The <strong>ca</strong> command is quirky and at times downright unfriendly.</p>
|
|
<p>The <strong>ca</strong> utility was originally meant as an example of how to do things
|
|
in a CA. It was not supposed to be used as a full blown CA itself:
|
|
nevertheless some people are using it for this purpose.</p>
|
|
<p>The <strong>ca</strong> command is effectively a single user command: no locking is
|
|
done on the various files and attempts to run more than one <strong>ca</strong> command
|
|
on the same database can have unpredictable results.</p>
|
|
<p>The <strong>copy_extensions</strong> option should be used with caution. If care is
|
|
not taken then it can be a security risk. For example if a certificate
|
|
request contains a basicConstraints extension with CA:TRUE and the
|
|
<strong>copy_extensions</strong> value is set to <strong>copyall</strong> and the user does not spot
|
|
this when the certificate is displayed then this will hand the requester
|
|
a valid CA certificate.</p>
|
|
<p>This situation can be avoided by setting <strong>copy_extensions</strong> to <strong>copy</strong>
|
|
and including basicConstraints with CA:FALSE in the configuration file.
|
|
Then if the request contains a basicConstraints extension it will be
|
|
ignored.</p>
|
|
<p>It is advisable to also include values for other extensions such
|
|
as <strong>keyUsage</strong> to prevent a request supplying its own values.</p>
|
|
<p>Additional restrictions can be placed on the CA certificate itself.
|
|
For example if the CA certificate has:</p>
|
|
<pre>
|
|
basicConstraints = CA:TRUE, pathlen:0</pre>
|
|
<p>then even if a certificate is issued with CA:TRUE it will not be valid.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>Since OpenSSL 1.1.1, the program follows <a href="http://www.ietf.org/rfc/rfc5280.txt" class="rfc">RFC5280</a>. Specifically,
|
|
certificate validity period (specified by any of <strong>-startdate</strong>,
|
|
<strong>-enddate</strong> and <strong>-days</strong>) will be encoded as UTCTime if the dates are
|
|
earlier than year 2049 (included), and as GeneralizedTime if the dates
|
|
are in year 2050 or later.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>req(1)</em>, <em>spkac(1)</em>, <em>x509(1)</em>, <em>CA.pl(1)</em>,
|
|
<em>config(5)</em>, <em>x509v3_config(5)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the OpenSSL license (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|