You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by tr...@apache.org on 2014/04/22 17:03:52 UTC
svn commit: r1589157 - in /httpd/httpd/trunk/docs/manual:
mod/mod_ssl_ct.html.en programs/ctlogconfig.html.en
Author: trawick
Date: Tue Apr 22 15:03:51 2014
New Revision: 1589157
URL: http://svn.apache.org/r1589157
Log:
rebuild CT docs
Modified:
httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.html.en
httpd/httpd/trunk/docs/manual/programs/ctlogconfig.html.en
Modified: httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.html.en?rev=1589157&r1=1589156&r2=1589157&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.html.en (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.html.en Tue Apr 22 15:03:51 2014
@@ -33,6 +33,7 @@
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_ssl_ct.c</td></tr></table>
<h3>Summary</h3>
+
<p>This module provides an implementation of Certificate Transparency, in
conjunction with <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> and command-line tools from the
<a href="https://code.google.com/p/certificate-transparency/">certificate-transparency</a>
@@ -49,19 +50,32 @@ servers and proxies:</p>
<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,
<code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> 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>
+
+<div class="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>
+</div>
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<ul id="toc">
@@ -75,8 +89,176 @@ information does not have to also restar
<li><img alt="" src="../images/down.gif" /> <a href="#ctstaticlogconfig">CTStaticLogConfig</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctstaticscts">CTStaticSCTs</a></li>
</ul>
-<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#server">Server processing overview</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxy">Proxy processing overview</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#logconf">Log configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging CT status in the access log</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#audit">Off-line audit for proxy</a></li>
+</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="server" id="server">Server processing overview</a></h2>
+
+
+ <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
+ <code class="directive"><a href="#ctserverhellosctlimit">CTServerHelloSCTLimit</a></code>
+ 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>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="proxy" id="proxy">Proxy processing overview</a></h2>
+
+
+ <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
+ <code class="directive"><a href="#ctproxyawareness">CTProxyAwareness</a></code> is set to
+ <em>require</em>.</p>
+
+ <p>Additionally, the server certificate chain and SCTs are stored for off-line
+ verification if the <code class="directive"><a href="#ctauditstorage">CTAuditStorage</a></code>
+ 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>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="logconf" id="logconf">Log configuration</a></h2>
+
+
+ <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 <code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code>,
+ and configure the path to that database using the <code class="directive"><a href="#ctlogconfig">
+ CTLogConfig</a></code> directive. This method of configuration supports
+ dynamic updates; <code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> 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 <code class="directive"><a href="#ctstaticlogconfig">CTStaticLogConfig</a></code> 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 <code class="directive"><a href="#ctstaticlogconfig">CTStaticLogConfig</a></code> and the
+ <code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code> command for more specific information.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="logging" id="logging">Logging CT status in the access log</a></h2>
+
+
+ <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 <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="audit" id="audit">Off-line audit for proxy</a></h2>
+
+
+ <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 <code class="directive"><a href="#ctauditstorage">
+ CTAuditStorage</a></code> 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
+ <code class="directive">CTAuditStorage</code> 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>
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTAuditStorage" id="CTAuditStorage">CTAuditStorage</a> <a name="ctauditstorage" id="ctauditstorage">Directive</a></h2>
<table class="directive">
@@ -181,11 +363,11 @@ refreshed</td></tr>
<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>
@@ -260,16 +442,13 @@ ServerHello</td></tr>
<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 <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>. The public key is
- required in order to check the signature of SCTs received by the proxy.</dd>
+ to <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</dd>
<dt><em>trust</em></dt>
<dd>This is a generic <q>trust</q> flag. Set this field to <em>0</em> to
@@ -285,10 +464,14 @@ ServerHello</td></tr>
<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>
+<h3>See also</h3>
+<ul>
+<li><a href="#logconf">Log configuration</a> contains more general information
+about the fields which can be configured with this directive.</li>
+</ul>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTStaticSCTs" id="CTStaticSCTs">CTStaticSCTs</a> <a name="ctstaticscts" id="ctstaticscts">Directive</a></h2>
@@ -303,17 +486,25 @@ ServerHello</td></tr>
</table>
<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
<code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</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 <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</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>
+
</div>
</div>
<div class="bottomlang">
Modified: httpd/httpd/trunk/docs/manual/programs/ctlogconfig.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/programs/ctlogconfig.html.en?rev=1589157&r1=1589156&r2=1589157&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/programs/ctlogconfig.html.en (original)
+++ httpd/httpd/trunk/docs/manual/programs/ctlogconfig.html.en Tue Apr 22 15:03:51 2014
@@ -27,6 +27,9 @@
<p><code>ctlogconfig</code> is a tool for maintaining a log configuration
database, for use with <code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code>.</p>
+ <p>Refer first to <a href="../mod/mod_ssl_ct.html#logconf">Log
+ configuration</a> in the <code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> documentation.</p>
+
<p>Refer to the <a href="#examples">examples below</a> for typical use.</p>
</div>
@@ -39,39 +42,39 @@
<h2><a name="synopsis" id="synopsis">Synopsis</a></h2>
<p><code>
- <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>dump</strong>
+ <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>dump</strong>
</code></p>
<p><code>
- <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>configure-public-key</strong>
+ <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>configure-public-key</strong>
[ <em>log-id</em>|<em>record-id</em> ]
<em>/path/to/public-key.pem</em>
</code></p>
<p><code>
- <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>configure-url</strong>
+ <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>configure-url</strong>
[ <em>log-id</em>|<em>record-id</em> ]
<em>log-URL</em>
</code></p>
<p><code>
- <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>valid-time-range</strong>
+ <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>valid-time-range</strong>
<em>log-id</em>|<em>record-id</em>
<em>min-timestamp</em> <em>max-timestamp</em>
</code></p>
<p><code>
- <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>trust</strong>
+ <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>trust</strong>
<em>log-id</em>|<em>record-id</em>
</code></p>
<p><code>
- <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>distrust</strong>
+ <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>distrust</strong>
<em>log-id</em>|<em>record-id</em>
</code></p>
<p><code>
- <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>forget</strong>
+ <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>forget</strong>
<em>log-id</em>|<em>record-id</em>
</code></p>