httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From traw...@apache.org
Subject svn commit: r1589157 - in /httpd/httpd/trunk/docs/manual: mod/mod_ssl_ct.html.en programs/ctlogconfig.html.en
Date Tue, 22 Apr 2014 15:03:52 GMT
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>
 



Mime
View raw message