| <?xml version="1.0" encoding="ISO-8859-1"?> |
| <!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" lang="en" xml:lang="en"><head> |
| <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" /> |
| <!-- |
| XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| This file is generated from xml source: DO NOT EDIT |
| XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| --> |
| <title>mod_ssl_ct - Apache HTTP Server Version 2.5</title> |
| <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> |
| <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> |
| <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" /> |
| <script src="../style/scripts/prettify.min.js" type="text/javascript"> |
| </script> |
| |
| <link href="../images/favicon.ico" rel="shortcut icon" /></head> |
| <body> |
| <div id="page-header"> |
| <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p> |
| <p class="apache">Apache HTTP Server Version 2.5</p> |
| <img alt="" src="../images/feather.png" /></div> |
| <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> |
| <div id="path"> |
| <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div> |
| <div id="page-content"> |
| <div id="preamble"><h1>Apache Module mod_ssl_ct</h1> |
| <div class="toplang"> |
| <p><span>Available Languages: </span><a href="../en/mod/mod_ssl_ct.html" title="English"> en </a></p> |
| </div> |
| <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Implementation of Certificate Transparency (RFC 6962) |
| </td></tr> |
| <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>ssl_ct_module</td></tr> |
| <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> |
| open source project. The goal of Certificate Transparency is to expose the |
| use of server certificates which are trusted by browsers but were mistakenly |
| or maliciously issued. More information about Certificate Transparency is |
| available at <a href="http://www.certificate-transparency.org/"> |
| http://www.certificate-transparency.org/</a>. Key terminology used in |
| this documentation:</p> |
| |
| <dl> |
| <dt>Certificate log</dt> |
| <dd>A certificate log, referred to simply as <q>log</q> in this documentation, |
| is a network service to which server certificates have been submitted. A |
| user agent can confirm that the certificate of a server which it accesses |
| has been submitted to a log which it trusts, and that the log itself has |
| not been tampered with.</dd> |
| |
| <dt>Signed Certificate Timestamp (SCT)</dt> |
| <dd>This is an acknowledgement from a log that it has accepted a valid |
| certificate. It is signed with the log's public key. One or more SCTs |
| is passed to clients during the handshake, either in the ServerHello |
| (TLS extension), certificate extension, or in a stapled OCSP response.</dd> |
| </dl> |
| |
| <p>This implementation for Apache httpd provides these features for TLS |
| servers and proxies:</p> |
| |
| <ul> |
| <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 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 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, |
| <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, Beta 3 or later) 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>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="#static">Storing SCTs in a form consumable by mod_ssl_ct</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><h3 class="directives">Directives</h3> |
| <ul id="toc"> |
| <li><img alt="" src="../images/down.gif" /> <a href="#ctauditstorage">CTAuditStorage</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#ctlogclient">CTLogClient</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#ctlogconfigdb">CTLogConfigDB</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#ctmaxsctage">CTMaxSCTAge</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#ctproxyawareness">CTProxyAwareness</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#ctsctstorage">CTSCTStorage</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#ctserverhellosctlimit">CTServerHelloSCTLimit</a></li> |
| <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> |
| <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_ssl_ct">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_ssl_ct">Report a bug</a></li></ul><h3>See also</h3> |
| <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. |
| <br /> |
| A server must have the public key of the log in order to submit certificates |
| to it.</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> directive 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="static" id="static">Storing SCTs in a form consumable by mod_ssl_ct</a></h2> |
| |
| |
| <p><code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> allows you to configure SCTs statically |
| using the <code class="directive">CTStaticSCTs</code> directive. These must be |
| in binary form, ready to send to a client.</p> |
| |
| <p>Sample code in the form of a Python script to build an SCT in the correct |
| format from data received from a log can be found in |
| <a href="https://github.com/tomrittervg/ct-tools">Tom Ritter's ct-tools |
| repository</a>. Refer to <code>write-sct.py</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="logging" id="logging">Logging CT status in the access log</a></h2> |
| |
| |
| <p>Proxy and server modes set the <code>SSL_CT_PROXY_STATUS</code> and |
| <code>SSL_CT_CLIENT_STATUS</code> variables, respectively, to indicate |
| if the corresponding peer is CT-aware.</p> |
| |
| <p>Proxy mode sets the <code>SSL_CT_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, 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>. |
| </p> |
| |
| <p>Here are rough notes for using <code>ctauditscts</code>:</p> |
| |
| <ul> |
| <li>Create a <em>virtualenv</em> using the <code>requirements.txt</code> file |
| from the <em>certificate-transparency</em> project and run the following steps |
| with that <em>virtualenv</em> activated.</li> |
| <li>Set <code>PYTHONPATH</code> to include the <code>python</code> |
| directory within the <em>certificate-transparency</em> tools.</li> |
| <li>Set <code>PATH</code> to include the <code>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 on processing the data.</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"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Existing directory where data for off-line audit will be stored</td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTAuditStorage <em>directory</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr> |
| </table> |
| <p>The <code class="directive">CTAuditStorage</code> directive sets the name of a |
| directory where data will be stored for off-line audit. If <em>directory</em> |
| is not absolute then it is assumed to be relative to <code class="directive"><a href="../mod/core.html#defaultruntimedir"> |
| DefaultRuntimeDir</a></code>.</p> |
| |
| <p>If this directive is not specified, data will not be stored for off-line |
| audit.</p> |
| |
| <p>The directory will contain files named <code><em>PID</em>.tmp</code> for |
| active child processes and files named <code><em>PID</em>.out</code> for exited |
| child processes. These <code>.out</code> files are ready for off-line audit. |
| The experimental command <code>ctauditscts</code> (in the httpd source tree, not |
| currently installed) interfaces with <em>certificate-transparency</em> tools to |
| perform the audit.</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="CTLogClient" id="CTLogClient">CTLogClient</a> <a name="ctlogclient" id="ctlogclient">Directive</a></h2> |
| <table class="directive"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Location of certificate-transparency log client tool</td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTLogClient <em>executable</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr> |
| </table> |
| <p><em>executable</em> is the full path to the log client tool, which is |
| normally file <code>cpp/client/ct</code> (or <code>ct.exe</code>) within the |
| source tree of the |
| <a href="https://code.google.com/p/certificate-transparency/"> |
| certificate-transparency</a> open source project.</p> |
| |
| <p>An alternative implementation could be used to retrieve SCTs for a |
| server certificate as long as the command-line interface is equivalent.</p> |
| |
| <p>If this directive is not configured, server certificates cannot be |
| submitted to logs in order to obtain SCTs; thus, only admin-managed |
| SCTs or SCTs in certificate extensions will be provided to clients.</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="CTLogConfigDB" id="CTLogConfigDB">CTLogConfigDB</a> <a name="ctlogconfigdb" id="ctlogconfigdb">Directive</a></h2> |
| <table class="directive"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Log configuration database supporting dynamic updates</td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTLogConfigDB <em>filename</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr> |
| </table> |
| <p>The <code class="directive">CTLogConfigDB</code> directive sets the name of a database |
| containing configuration about known logs. If <em>filename</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>Refer to the documentation for the <code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code> program, |
| which manages the database.</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="CTMaxSCTAge" id="CTMaxSCTAge">CTMaxSCTAge</a> <a name="ctmaxsctage" id="ctmaxsctage">Directive</a></h2> |
| <table class="directive"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum age of SCT obtained from a log, before it will be |
| refreshed</td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTMaxSCTAge <em>num-seconds</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>1 day</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr> |
| </table> |
| <p>Server certificates with SCTs which are older than this maximum age will |
| be resubmitted to configured logs. Generally the log will return the same SCT |
| as before, but that is subject to log operation. SCTs will be refreshed as |
| necessary during normal server operation, with new SCTs returned to clients |
| as they become available.</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="CTProxyAwareness" id="CTProxyAwareness">CTProxyAwareness</a> <a name="ctproxyawareness" id="ctproxyawareness">Directive</a></h2> |
| <table class="directive"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Level of CT awareness and enforcement for a proxy |
| </td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTProxyAwareness <em>oblivious|aware|require</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>aware</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr> |
| </table> |
| <p>This directive controls awareness and checks for valid SCTs for a |
| proxy. Several options are available:</p> |
| |
| <dl> |
| <dt>oblivious</dt> |
| <dd>The proxy will neither ask for nor examine SCTs. Certificate |
| Transparency processing for the proxy is completely disabled.</dd> |
| |
| <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 origin server does |
| not provide any valid SCTs.</dd> |
| |
| <dt>require</dt> |
| <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> |
| |
| |
| </div> |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> |
| <div class="directive-section"><h2><a name="CTSCTStorage" id="CTSCTStorage">CTSCTStorage</a> <a name="ctsctstorage" id="ctsctstorage">Directive</a></h2> |
| <table class="directive"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Existing directory where SCTs are managed</td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTSCTStorage <em>directory</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr> |
| </table> |
| <p>The <code class="directive">CTSCTStorage</code> directive sets the name of a |
| directory where SCTs and SCT lists will be stored. If <em>directory</em> |
| is not absolute then it is assumed to be relative to <code class="directive"><a href="../mod/core.html#defaultruntimedir"> |
| DefaultRuntimeDir</a></code>.</p> |
| |
| <p>A subdirectory for each server certificate contains information relative |
| to that certificate; the name of the subdirectory is the SHA-256 hash of the |
| certificate.</p> |
| |
| <p>The certificate-specific directory contains SCTs retrieved from configured |
| logs, SCT lists prepared from statically configured SCTs and retrieved SCTs, |
| and other information used for managing SCTs.</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="CTServerHelloSCTLimit" id="CTServerHelloSCTLimit">CTServerHelloSCTLimit</a> <a name="ctserverhellosctlimit" id="ctserverhellosctlimit">Directive</a></h2> |
| <table class="directive"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limit on number of SCTs that can be returned in |
| ServerHello</td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTServerHelloSCTLimit <em>limit</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>100</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr> |
| </table> |
| <p>This directive can be used to limit the number of SCTs which can be |
| returned by a TLS server in ServerHello, in case the number of configured |
| logs and statically-defined SCTs is relatively high.</p> |
| |
| <p>Typically only a few SCTs would be available, so this directive is only |
| needed in special circumstances.</p> |
| |
| <p>The directive does not take into account SCTs which may be provided in |
| certificate extensions or in stapled OCSP responses.</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="CTStaticLogConfig" id="CTStaticLogConfig">CTStaticLogConfig</a> <a name="ctstaticlogconfig" id="ctstaticlogconfig">Directive</a></h2> |
| <table class="directive"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Static configuration of information about a log</td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTStaticLogConfig <em>log-id|-</em> <em>public-key-file|-</em> |
| <em>1|0|-</em> <em>min-timestamp|-</em> <em>max-timestamp|-</em> |
| <em>log-URL|-</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr> |
| </table> |
| <p>This directive is used to configure information about a particular log. |
| This directive is appropriate when configuration information changes rarely. |
| If dynamic configuration updates must be supported, refer to the |
| <code class="directive"><a href="#ctlogconfigdb">CTLogConfigDB</a></code> directive.</p> |
| |
| <p>Each of the six fields must be specified, but usually only a small |
| amount of information must be configured for each log; use <em>-</em> when no |
| information is available for the field. For example, in support of a |
| server-only configuration (i.e., no proxy), the administrator might |
| configure only the log URL to be used when submitting server certificates |
| and obtaining a Signed Certificate Timestamp.</p> |
| |
| <p>The fields are defined as follows:</p> |
| |
| <dl> |
| <dt><em>log-id</em></dt> |
| <dd>This is the id of the log, which is the SHA-256 hash of the log's |
| public key, provided in hexadecimal format. This string is 64 characters |
| in length. |
| <br /> |
| This field should be omitted when <em>public-key-file</em> is provided.</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>.</dd> |
| |
| <dt><em>trust/distrust</em></dt> |
| <dd>Set this field to <em>1</em> to distrust this log, or to otherwise avoid |
| using it for server certificate submission. Set this to <em>-</em> or |
| <em>0</em> (the default) to treat the log normally.</dd> |
| |
| <dt><em>min-timestamp</em> and <em>max-timestamp</em></dt> |
| <dd>A timestamp is a time as expressed in the number of milliseconds since the |
| epoch, ignoring leap seconds. This is the form of time used in Signed Certificate |
| Timestamps. This must be provided as a decimal number. |
| <br /> |
| Specify <strong><code>-</code></strong> for one of the timestamps if it is unknown. |
| For example, when configuring the minimum valid timestamp for a log which remains |
| valid, specify <strong><code>-</code></strong> for <em>max-timestamp</em>. |
| <br /> |
| SCTs received from this log by the proxy are invalid if the timestamp |
| is older than <em>min-timestamp</em> or newer than <em>max-timestamp</em>.</dd> |
| |
| <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.</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> |
| <table class="directive"> |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Static configuration of one or more SCTs for a server certificate |
| </td></tr> |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTStaticSCTs <em>certificate-pem-file</em> <em>sct-directory</em></code></td></tr> |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</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. 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> 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"> |
| <p><span>Available Languages: </span><a href="../en/mod/mod_ssl_ct.html" title="English"> en </a></p> |
| </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> |
| <script type="text/javascript"><!--//--><![CDATA[//><!-- |
| var comments_shortname = 'httpd'; |
| var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html'; |
| (function(w, d) { |
| if (w.location.hostname.toLowerCase() == "httpd.apache.org") { |
| d.write('<div id="comments_thread"><\/div>'); |
| var s = d.createElement('script'); |
| s.type = 'text/javascript'; |
| s.async = true; |
| s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; |
| (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); |
| } |
| else { |
| d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); |
| } |
| })(window, document); |
| //--><!]]></script></div><div id="footer"> |
| <p class="apache">Copyright 2016 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> |
| <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- |
| if (typeof(prettyPrint) !== 'undefined') { |
| prettyPrint(); |
| } |
| //--><!]]></script> |
| </body></html> |
