<identifier>ssl_ct_module</identifier>
<summary>
+
<p>This module provides an implementation of Certificate Transparency, in
conjunction with <module>mod_ssl</module> and command-line tools from the
<a href="https://code.google.com/p/certificate-transparency/">certificate-transparency</a>
<li>Signed Certificate Timestamps (SCTs) can be obtained from logs
automatically and, in conjunction with any statically configured SCTs, sent
to aware clients in the ServerHello (during the handshake).</li>
- <li>SCTs can be received by the proxy from backend servers in the ServerHello,
+ <li>SCTs can be received by the proxy from origin servers in the ServerHello,
in a certificate extension, and/or within stapled OCSP responses; any SCTs
received can be partially validated on-line and optionally queued for off-line
audit.</li>
- <li>The proxy can be configured to disallow communication with a backend
- which does not provide an SCT which passes on-line validation.</li>
+ <li>The proxy can be configured to disallow communication with an origin
+ server which does not provide an SCT which passes on-line validation.</li>
</ul>
<p>Configuration information about logs can be defined statically in the web
-server configuration or maintained in a Sqlite3 database. In the latter case,
+server configuration or maintained in a SQLite3 database. In the latter case,
<module>mod_ssl_ct</module> will reload the database periodically, so any
site-specific infrastructure for maintaining and propagating log configuration
information does not have to also restart httpd to make it take effect.</p>
+
+<note>This module is experimental for the following reasons:
+<ul>
+ <li>Insufficient test and review</li>
+ <li>Reliance on an unreleased version of OpenSSL (1.0.2) for basic
+ operation</li>
+ <li>Incomplete <a href="#audit">off-line audit capability</a></li>
+</ul>
+
+<p>Configuration mechanisms, format of data saved for off-line audit, and
+other characteristics are subject to change based on further feedback and
+testing.</p>
+</note>
</summary>
+<section id="server">
+ <title>Server processing overview</title>
+
+ <p>Servers need to send SCTs to their clients. SCTs in a certificate
+ extension or stapled OCSP response will be sent without any special program
+ logic. This module handles sending SCTs configured by the administrator or
+ received from configured logs.</p>
+
+ <p>The number of SCTs sent in the ServerHello (i.e., not including those in a
+ certificate extension or stapled OCSP response) can be limited by the
+ <directive module="mod_ssl_ct">CTServerHelloSCTLimit</directive>
+ directive.</p>
+
+ <p>For each server certificate, a daemon process maintains an SCT list to be
+ sent in the ServerHello, created from statically configured SCTs as well as
+ those received from logs. Logs marked as untrusted or with a maximum valid
+ timestamp before the present time will be ignored. Periodically the daemon
+ will submit certificates to a log as necessary (due to changed log
+ configuration or age) and rebuild the concatenation of SCTs.</p>
+
+ <p>The SCT list for a server certificate will be sent to any client that
+ indicates awareness in the ClientHello when that particular server certificate
+ is used.</p>
+
+</section>
+
+<section id="proxy">
+ <title>Proxy processing overview</title>
+
+ <p>The proxy indicates Certificate Transparency awareness in the ClientHello
+ by including the <em>signed_certificate_timestamp</em> extension. It can
+ recognize SCTs received in the ServerHello, in an extension in the certificate
+ for an origin server, or in a stapled OCSP response.</p>
+
+ <p>On-line verification is attempted for each received SCT:</p>
+
+ <ul>
+ <li>For any SCT, the timestamp can be checked to see if it is not yet valid
+ based on the current time as well as any configured valid time interval for
+ the log.</li>
+ <li>For an SCT from a log for which a public key is configured, the server
+ signature will be checked.</li>
+ </ul>
+
+ <p>If verification fails for at least one SCT and verification was not
+ successful for at least one SCT, the connection is aborted if
+ <directive module="mod_ssl_ct">CTProxyAwareness</directive> is set to
+ <em>require</em>.</p>
+
+ <p>Additionally, the server certificate chain and SCTs are stored for off-line
+ verification if the <directive module="mod_ssl_ct">CTAuditStorage</directive>
+ directive is configured.</p>
+
+ <p>As an optimization, on-line verification and storing of data from the
+ server is only performed the first time a web server child process receives
+ the data. This saves some processing time as well as disk space. For typical
+ reverse proxy setups, very little processing overhead will be required.</p>
+
+</section>
+
+<section id="logconf">
+ <title>Log configuration</title>
+
+ <p>Servers and proxies use different information about logs for their processing.
+ This <em>log configuration</em> can be set in two ways:</p>
+
+ <ul>
+ <li>Create a log configuration database using <program>ctlogconfig</program>,
+ and configure the path to that database using the <directive module="mod_ssl_ct">
+ CTLogConfig</directive> directive. This method of configuration supports
+ dynamic updates; <module>mod_ssl_ct</module> will re-read the database at
+ intervals. Additionally, the off-line audit program <code>ctauditscts</code>
+ can use this configuration to find the URL of logs.</li>
+
+ <li>Configure information about logs statically using the <directive
+ module="mod_ssl_ct">CTStaticLogConfig</directive> directive. As with all other
+ directives, the server must be restarted in order to pick up changes to the
+ directives.</li>
+ </ul>
+
+ <p>The information that can be configured about a log using either mechanism is
+ described below:</p>
+
+ <dl>
+ <dt>log id</dt>
+ <dd>The log id is the SHA-256 hash of the log's public key, and is part of
+ every SCT. This is a convenient way to identify a particular log when
+ configuring valid timestamp ranges or certain other information.</dd>
+
+ <dt>public key of the log</dt>
+ <dd>A proxy must have the public key of the log in order to check the
+ signature in SCTs it receives which were obtained from the log.</dd>
+
+ <dt>general trust/distrust setting</dt>
+ <dd>This is a mechanism to distrust or restore trust in a particular log,
+ for whatever reason (including simply avoiding interaction with the
+ log in situations where it is off-line).</dd>
+
+ <dt>minimum and/or maximum valid timestamps</dt>
+ <dd>When configured, the proxy will check that timestamps from SCTs
+ are within the valid range.</dd>
+
+ <dt>log URL</dt>
+ <dd>The URL of the log (for its API) is required by a server in order to
+ submit server certificates to the log. The server will submit
+ each server certificate in order to obtain an SCT for each log with a
+ configured URL, except when the log is also marked as distrusted or the
+ current time is not within any configured valid timestamp range.
+ <br />
+ The log URL is also needed by off-line auditing of SCTs received by a
+ proxy.</dd>
+ </dl>
+
+ <p>Generally, only a small subset of this information is configured for a
+ particular log. Refer to the documentation for the <directive
+ module="mod_ssl_ct">CTStaticLogConfig</directive> and the
+ <program>ctlogconfig</program> command for more specific information.</p>
+
+</section>
+
+<section id="logging">
+ <title>Logging CT status in the access log</title>
+
+ <p>Both proxy and server modes set the <code>SSL_CT_PEER_STATUS</code>
+ variable to indicate if the peer is CT-aware.</p>
+
+ <p>Proxy mode sets the <code>SSL_PROXY_SCT_SOURCES</code> variable to
+ indicate whether and where SCTs were obtained (ServerHello, certificate
+ extension, etc.).</p>
+
+ <p>These variables can be logged with the <code>%{<em>varname</em>}e</code>
+ format of <module>mod_log_config</module>.</p>
+</section>
+
+<section id="audit">
+ <title>Off-line audit for proxy</title>
+
+ <p>Experimental support for this is implemented in the <code>ctauditscts</code>
+ command (in the httpd source tree, not currently installed), which itself
+ relies on the <code>verify_single_proof.py</code> tool in the
+ <em>certificate-transparency</em> open source project. <code>ctauditscts</code>
+ can parse data for off-line audit (enabled with the <directive module="mod_ssl_ct">
+ CTAuditStorage</directive> directive) and invoke <code>verify_single_proof.py</code>.
+ However, <code>verify_single_proof.py</code> is not complete currently and does
+ not provide a way to identify audit failures.</p>
+
+ <p>Here are rough notes for using <code>ctauditscts</code>:</p>
+
+ <ul>
+ <li>Set <code>PYTHONPATH</code> to include the <code>src/python</code>
+ directory within the <em>certificate-transparency</em> tools.</li>
+ <li>Set <code>PATH</code> to include the <code>src/python/ct/client/tools</code>
+ directory.</li>
+ <li>Run <code>ctauditscts</code>, passing the value of the
+ <directive>CTAuditStorage</directive> directive and, optionally, the path to
+ the log configuration database. The latter will be used to look up log URLs
+ by log id.</li>
+ </ul>
+
+ <p>The data saved for audit can also be used by other programs; refer to the
+ <code>ctauditscts</code> source code for details.</p>
+</section>
+
<directivesynopsis>
<name>CTAuditStorage</name>
<description>Existing directory where data for off-line audit will be stored</description>
<dt>aware</dt>
<dd>The proxy will perform all appropriate Certificate Transparency
processing, such as asking for and examining SCTs. However, the
- proxy will not disallow communication if the backend server does
+ proxy will not disallow communication if the origin server does
not provide any valid SCTs.</dd>
<dt>require</dt>
- <dd>The proxy will abort communication with the backend server if it
+ <dd>The proxy will abort communication with the origin server if it
does not provide at least one SCT which passes on-line validation.</dd>
</dl>
<dl>
<dt><em>log-id</em></dt>
- <dd>This is the id of the log. The id is the SHA-256 hash of the log's
- public key. In some cases it is appropriate and convenient to identify
- the log by the id (hash), such as when configuring information regarding
- the log's validity.</dd>
+ <dd>This is the id of the log, which is the SHA-256 hash of the log's
+ public key.</dd>
<dt><em>public-key-file</em></dt>
<dd>This is the name of a file containing the PEM encoding of the log's
public key. If the name is not absolute, then it is assumed to be relative
- to <directive module="core">ServerRoot</directive>. The public key is
- required in order to check the signature of SCTs received by the proxy.</dd>
+ to <directive module="core">ServerRoot</directive>.</dd>
<dt><em>trust</em></dt>
<dd>This is a generic <q>trust</q> flag. Set this field to <em>0</em> to
<dt><em>log-URL</em></dt>
<dd>This is the URL of the log, for use in submitting server certificates
- and in turn obtaining an SCT to be sent to clients. Each server certificate
- will be submitted to all logs for which <em>log-URL</em> is configured.</dd>
+ and in turn obtaining an SCT to be sent to clients.</dd>
</dl>
</usage>
+
+<seealso><a href="#logconf">Log configuration</a> contains more general information
+about the fields which can be configured with this directive.</seealso>
+
</directivesynopsis>
<directivesynopsis>
<usage>
<p>This directive is used to statically define one or more SCTs corresponding
to a server certificate. This mechanism can be used instead of or in
- addition to dynamically obtaining SCTs from configured logs.</p>
+ addition to dynamically obtaining SCTs from configured logs. Any changes to
+ the set of SCTs for a particular server certificate will be adopted dynamically
+ without the need to restart the server.</p>
<p><em>certificate-pem-file</em> refers to the server certificate in PEM
format. If the name is not absolute, then it is assumed to be relative to
<directive module="core">ServerRoot</directive>.</p>
- <p><em>sct-directory</em> must contain one or more files with extension
+ <p><em>sct-directory</em> should contain one or more files with extension
<code>.sct</code>, representing one or more SCTs corresponding to the
server certificate. If <em>sct-directory</em> is not absolute, then it is
assumed to be relative to <directive module="core">ServerRoot</directive>.</p>
+
+ <p>If <em>sct-directory</em> is empty, no error will be raised.</p>
+
+ <p>This directive could be used to identify directories of SCTs maintained by
+ other infrastructure, provided that they are saved in binary format with
+ file extension <em>.sct</em></p>
</usage>
</directivesynopsis>
projects / apache / commitdiff