Skip to content

Commit

Permalink
rebuild CT docs
Browse files Browse the repository at this point in the history 
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1589157 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information
@trawick
trawick committed Apr 22, 2014
1 parent 7020129 commit e2a776c
Show file tree
Hide file tree
Showing 2 changed files with 218 additions and 24 deletions.
225 changes: 208 additions & 17 deletions docs/manual/mod/mod_ssl_ct.html.en
View file
Expand Up @@ -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>
Expand All @@ -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">
Expand All @@ -75,8 +89,176 @@ information does not have to also restart httpd to make it take effect.</p>
<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">
Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -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
Expand All @@ -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>
Expand All @@ -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">
Expand Down
17 changes: 10 additions & 7 deletions docs/manual/programs/ctlogconfig.html.en
View file
Expand Up @@ -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>
Expand All @@ -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>

Expand Down

0 comments on commit e2a776c

Please sign in to comment.