granicus.if.org Git - apache/blob - docs/manual/mod/mod_ssl_ct.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_ssl_ct - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <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" />
  12 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body>
  17 <div id="page-header">
  18 <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>
  19 <p class="apache">Apache HTTP Server Version 2.5</p>
  20 <img alt="" src="../images/feather.gif" /></div>
  21 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  22 <div id="path">
  23 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  24 <div id="page-content">
  25 <div id="preamble"><h1>Apache Module mod_ssl_ct</h1>
  26 <div class="toplang">
  27 <p><span>Available Languages: </span><a href="../en/mod/mod_ssl_ct.html" title="English">&nbsp;en&nbsp;</a></p>
  28 </div>
  29 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Implementation of Certificate Transparency (RFC 6962)
  30 </td></tr>
  31 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  32 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>ssl_ct_module</td></tr>
  33 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_ssl_ct.c</td></tr></table>
  34 <h3>Summary</h3>
  35
  36
  37 <p>This module provides an implementation of Certificate Transparency, in
  38 conjunction with <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> and command-line tools from the
  39 <a href="https://code.google.com/p/certificate-transparency/">certificate-transparency</a>
  40 open source project.  The goal of Certificate Transparency is to expose the
  41 use of server certificates which are trusted by browsers but were mistakenly
  42 or maliciously issued.  More information about Certificate Transparency is
  43 available at <a href="http://www.certificate-transparency.org/">
  44 http://www.certificate-transparency.org/</a>.  Key terminology used in
  45 this documentation:</p>
  46
  47 <dl>
  48   <dt>Certificate log</dt>
  49   <dd>A certificate log, referred to simply as <q>log</q> in this documentation,
  50   is a network service to which server certificates have been submitted.  A
  51   user agent can confirm that the certificate of a server which it accesses
  52   has been submitted to a log which it trusts, and that the log itself has
  53   not been tampered with.</dd>
  54
  55   <dt>Signed Certificate Timestamp (SCT)</dt>
  56   <dd>This is an acknowledgement from a log that it has accepted a valid
  57   certificate.  It is signed with the log's public key.  One or more SCTs
  58   is passed to clients during the handshake, either in the ServerHello
  59   (TLS extension), certificate extension, or in a stapled OCSP response.</dd>
  60 </dl>
  61
  62 <p>This implementation for Apache httpd provides these features for TLS
  63 servers and proxies:</p>
  64
  65 <ul>
  66   <li>Signed Certificate Timestamps (SCTs) can be obtained from logs
  67   automatically and, in conjunction with any statically configured SCTs, sent
  68   to aware clients in the ServerHello (during the handshake).</li>
  69   <li>SCTs can be received by the proxy from origin servers in the ServerHello,
  70   in a certificate extension, and/or within stapled OCSP responses; any SCTs
  71   received can be partially validated on-line and optionally queued for off-line
  72   audit.</li>
  73   <li>The proxy can be configured to disallow communication with an origin
  74   server which does not provide an SCT which passes on-line validation.</li>
  75 </ul>
  76
  77 <p>Configuration information about logs can be defined statically in the web
  78 server configuration or maintained in a SQLite3 database.  In the latter case,
  79 <code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> will reload the database periodically, so any
  80 site-specific infrastructure for maintaining and propagating log configuration
  81 information does not have to also restart httpd to make it take effect.</p>
  82
  83 <div class="note">This module is experimental for the following reasons:
  84 <ul>
  85   <li>Insufficient test and review</li>
  86   <li>Reliance on an unreleased version of OpenSSL (1.0.2) for basic
  87   operation</li>
  88   <li>Incomplete <a href="#audit">off-line audit capability</a></li>
  89 </ul>
  90
  91 <p>Configuration mechanisms, format of data saved for off-line audit, and
  92 other characteristics are subject to change based on further feedback and
  93 testing.</p>
  94 </div>
  95 </div>
  96 <div id="quickview"><h3 class="directives">Directives</h3>
  97 <ul id="toc">
  98 <li><img alt="" src="../images/down.gif" /> <a href="#ctauditstorage">CTAuditStorage</a></li>
  99 <li><img alt="" src="../images/down.gif" /> <a href="#ctlogclient">CTLogClient</a></li>
 100 <li><img alt="" src="../images/down.gif" /> <a href="#ctlogconfigdb">CTLogConfigDB</a></li>
 101 <li><img alt="" src="../images/down.gif" /> <a href="#ctmaxsctage">CTMaxSCTAge</a></li>
 102 <li><img alt="" src="../images/down.gif" /> <a href="#ctproxyawareness">CTProxyAwareness</a></li>
 103 <li><img alt="" src="../images/down.gif" /> <a href="#ctsctstorage">CTSCTStorage</a></li>
 104 <li><img alt="" src="../images/down.gif" /> <a href="#ctserverhellosctlimit">CTServerHelloSCTLimit</a></li>
 105 <li><img alt="" src="../images/down.gif" /> <a href="#ctstaticlogconfig">CTStaticLogConfig</a></li>
 106 <li><img alt="" src="../images/down.gif" /> <a href="#ctstaticscts">CTStaticSCTs</a></li>
 107 </ul>
 108 <h3>Topics</h3>
 109 <ul id="topics">
 110 <li><img alt="" src="../images/down.gif" /> <a href="#server">Server processing overview</a></li>
 111 <li><img alt="" src="../images/down.gif" /> <a href="#proxy">Proxy processing overview</a></li>
 112 <li><img alt="" src="../images/down.gif" /> <a href="#logconf">Log configuration</a></li>
 113 <li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging CT status in the access log</a></li>
 114 <li><img alt="" src="../images/down.gif" /> <a href="#audit">Off-line audit for proxy</a></li>
 115 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
 116 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 117 <div class="section">
 118 <h2><a name="server" id="server">Server processing overview</a></h2>
 119
 120
 121   <p>Servers need to send SCTs to their clients.  SCTs in a certificate
 122   extension or stapled OCSP response will be sent without any special program
 123   logic.  This module handles sending SCTs configured by the administrator or
 124   received from configured logs.</p>
 125
 126   <p>The number of SCTs sent in the ServerHello (i.e., not including those in a
 127   certificate extension or stapled OCSP response) can be limited by the
 128   <code class="directive"><a href="#ctserverhellosctlimit">CTServerHelloSCTLimit</a></code>
 129   directive.</p>
 130
 131   <p>For each server certificate, a daemon process maintains an SCT list to be
 132   sent in the ServerHello, created from statically configured SCTs as well as
 133   those received from logs.  Logs marked as untrusted or with a maximum valid
 134   timestamp before the present time will be ignored.  Periodically the daemon
 135   will submit certificates to a log as necessary (due to changed log
 136   configuration or age) and rebuild the concatenation of SCTs.</p>
 137
 138   <p>The SCT list for a server certificate will be sent to any client that
 139   indicates awareness in the ClientHello when that particular server certificate
 140   is used.</p>
 141
 142 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 143 <div class="section">
 144 <h2><a name="proxy" id="proxy">Proxy processing overview</a></h2>
 145
 146
 147   <p>The proxy indicates Certificate Transparency awareness in the ClientHello
 148   by including the <em>signed_certificate_timestamp</em> extension.  It can
 149   recognize SCTs received in the ServerHello, in an extension in the certificate
 150   for an origin server, or in a stapled OCSP response.</p>
 151
 152   <p>On-line verification is attempted for each received SCT:</p>
 153
 154   <ul>
 155     <li>For any SCT, the timestamp can be checked to see if it is not yet valid
 156     based on the current time as well as any configured valid time interval for
 157     the log.</li>
 158     <li>For an SCT from a log for which a public key is configured, the server
 159     signature will be checked.</li>
 160   </ul>
 161
 162   <p>If verification fails for at least one SCT and verification was not
 163   successful for at least one SCT, the connection is aborted if
 164   <code class="directive"><a href="#ctproxyawareness">CTProxyAwareness</a></code> is set to
 165   <em>require</em>.</p>
 166
 167   <p>Additionally, the server certificate chain and SCTs are stored for off-line
 168   verification if the <code class="directive"><a href="#ctauditstorage">CTAuditStorage</a></code>
 169   directive is configured.</p>
 170
 171   <p>As an optimization, on-line verification and storing of data from the
 172   server is only performed the first time a web server child process receives
 173   the data.  This saves some processing time as well as disk space.  For typical
 174   reverse proxy setups, very little processing overhead will be required.</p>
 175
 176 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 177 <div class="section">
 178 <h2><a name="logconf" id="logconf">Log configuration</a></h2>
 179
 180
 181   <p>Servers and proxies use different information about logs for their processing.
 182   This <em>log configuration</em> can be set in two ways:</p>
 183
 184   <ul>
 185     <li>Create a log configuration database using <code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code>,
 186     and configure the path to that database using the <code class="directive"><a href="#ctlogconfig">
 187     CTLogConfig</a></code> directive.  This method of configuration supports
 188     dynamic updates; <code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> will re-read the database at
 189     intervals.  Additionally, the off-line audit program <code>ctauditscts</code>
 190     can use this configuration to find the URL of logs.</li>
 191
 192     <li>Configure information about logs statically using the <code class="directive"><a href="#ctstaticlogconfig">CTStaticLogConfig</a></code> directive.  As with all other
 193     directives, the server must be restarted in order to pick up changes to the
 194     directives.</li>
 195   </ul>
 196
 197   <p>The information that can be configured about a log using either mechanism is
 198   described below:</p>
 199
 200   <dl>
 201     <dt>log id</dt>
 202     <dd>The log id is the SHA-256 hash of the log's public key, and is part of
 203     every SCT.  This is a convenient way to identify a particular log when
 204     configuring valid timestamp ranges or certain other information.</dd>
 205
 206     <dt>public key of the log</dt>
 207     <dd>A proxy must have the public key of the log in order to check the
 208     signature in SCTs it receives which were obtained from the log.</dd>
 209
 210     <dt>general trust/distrust setting</dt>
 211     <dd>This is a mechanism to distrust or restore trust in a particular log,
 212     for whatever reason (including simply avoiding interaction with the
 213     log in situations where it is off-line).</dd>
 214
 215     <dt>minimum and/or maximum valid timestamps</dt>
 216     <dd>When configured, the proxy will check that timestamps from SCTs
 217     are within the valid range.</dd>
 218
 219     <dt>log URL</dt>
 220     <dd>The URL of the log (for its API) is required by a server in order to
 221     submit server certificates to the log.  The server will submit
 222     each server certificate in order to obtain an SCT for each log with a
 223     configured URL, except when the log is also marked as distrusted or the
 224     current time is not within any configured valid timestamp range.
 225     <br />
 226     The log URL is also needed by off-line auditing of SCTs received by a
 227     proxy.</dd>
 228   </dl>
 229
 230   <p>Generally, only a small subset of this information is configured for a
 231   particular log.  Refer to the documentation for the <code class="directive"><a href="#ctstaticlogconfig">CTStaticLogConfig</a></code> directive and the
 232   <code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code> command for more specific information.</p>
 233
 234 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 235 <div class="section">
 236 <h2><a name="logging" id="logging">Logging CT status in the access log</a></h2>
 237
 238
 239   <p>Both proxy and server modes set the <code>SSL_CT_PEER_STATUS</code>
 240   variable to indicate if the peer is CT-aware.</p>
 241
 242   <p>Proxy mode sets the <code>SSL_PROXY_SCT_SOURCES</code> variable to
 243   indicate whether and where SCTs were obtained (ServerHello, certificate
 244   extension, etc.).</p>
 245
 246   <p>These variables can be logged with the <code>%{<em>varname</em>}e</code>
 247   format of <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>.</p>
 248 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 249 <div class="section">
 250 <h2><a name="audit" id="audit">Off-line audit for proxy</a></h2>
 251
 252
 253   <p>Experimental support for this is implemented in the <code>ctauditscts</code>
 254   command (in the httpd source tree, not currently installed), which itself
 255   relies on the <code>verify_single_proof.py</code> tool in the
 256   <em>certificate-transparency</em> open source project.  <code>ctauditscts</code>
 257   can parse data for off-line audit (enabled with the <code class="directive"><a href="#ctauditstorage">
 258   CTAuditStorage</a></code> directive) and invoke <code>verify_single_proof.py</code>.
 259   However, <code>verify_single_proof.py</code> is not complete currently and does
 260   not provide a way to identify audit failures.</p>
 261
 262   <p>Here are rough notes for using <code>ctauditscts</code>:</p>
 263
 264   <ul>
 265     <li>Set <code>PYTHONPATH</code> to include the <code>src/python</code>
 266     directory within the <em>certificate-transparency</em> tools.</li>
 267     <li>Set <code>PATH</code> to include the <code>src/python/ct/client/tools</code>
 268     directory.</li>
 269     <li>Run <code>ctauditscts</code>, passing the value of the
 270     <code class="directive">CTAuditStorage</code> directive and, optionally, the path to
 271     the log configuration database.  The latter will be used to look up log URLs
 272     by log id.</li>
 273   </ul>
 274
 275   <p>The data saved for audit can also be used by other programs; refer to the
 276   <code>ctauditscts</code> source code for details.</p>
 277 </div>
 278 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 279 <div class="directive-section"><h2><a name="CTAuditStorage" id="CTAuditStorage">CTAuditStorage</a> <a name="ctauditstorage" id="ctauditstorage">Directive</a></h2>
 280 <table class="directive">
 281 <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>
 282 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTAuditStorage <em>directory</em></code></td></tr>
 283 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
 284 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 285 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 286 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 287 </table>
 288   <p>The <code class="directive">CTAuditStorage</code> directive sets the name of a
 289   directory where data will be stored for off-line audit.  If <em>directory</em>
 290   is not absolute then it is assumed to be relative to <code class="directive"><a href="../mod/core.html#defaultruntimedir">
 291   DefaultRuntimeDir</a></code>.</p>
 292
 293   <p>If this directive is not specified, data will not be stored for off-line
 294   audit.</p>
 295
 296   <p>The directory will contain files named <code><em>PID</em>.tmp</code> for
 297   active child processes and files named <code><em>PID</em>.out</code> for exited
 298   child processes.  These <code>.out</code> files are ready for off-line audit.
 299   The experimental command <code>ctauditscts</code> (in the httpd source tree, not
 300   currently installed) interfaces with <em>certificate-transparency</em> tools to
 301   perform the audit.</p>
 302
 303 </div>
 304 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 305 <div class="directive-section"><h2><a name="CTLogClient" id="CTLogClient">CTLogClient</a> <a name="ctlogclient" id="ctlogclient">Directive</a></h2>
 306 <table class="directive">
 307 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Location of certificate-transparency log client tool</td></tr>
 308 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTLogClient <em>executable</em></code></td></tr>
 309 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
 310 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 311 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 312 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 313 </table>
 314   <p><em>executable</em> is the full path to the log client tool, which is
 315   normally file <code>src/client/ct</code> within the source tree of the
 316   <a href="https://code.google.com/p/certificate-transparency/">
 317   certificate-transparency</a> open source project.</p>
 318
 319   <p>An alternative implementation could be used to retrieve SCTs for a
 320   server certificate as long as the command-line interface is equivalent.</p>
 321
 322   <p>If this directive is not configured, server certificates cannot be
 323   submitted to logs in order to obtain SCTs; thus, only admin-managed
 324   SCTs will be provided to clients.</p>
 325
 326 </div>
 327 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 328 <div class="directive-section"><h2><a name="CTLogConfigDB" id="CTLogConfigDB">CTLogConfigDB</a> <a name="ctlogconfigdb" id="ctlogconfigdb">Directive</a></h2>
 329 <table class="directive">
 330 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Log configuration database supporting dynamic updates</td></tr>
 331 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTLogConfigDB <em>filename</em></code></td></tr>
 332 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
 333 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 334 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 335 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 336 </table>
 337   <p>The <code class="directive">CTLogConfigDB</code> directive sets the name of a database
 338   containing configuration about known logs.  If <em>filename</em> is not absolute
 339   then it is assumed to be relative to
 340   <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
 341
 342   <p>Refer to the documentation for the <code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code> program,
 343   which manages the database.</p>
 344
 345 </div>
 346 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 347 <div class="directive-section"><h2><a name="CTMaxSCTAge" id="CTMaxSCTAge">CTMaxSCTAge</a> <a name="ctmaxsctage" id="ctmaxsctage">Directive</a></h2>
 348 <table class="directive">
 349 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum age of SCT obtained from a log, before it will be
 350 refreshed</td></tr>
 351 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTMaxSCTAge <em>num-seconds</em></code></td></tr>
 352 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>1 day</code></td></tr>
 353 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 354 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 355 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 356 </table>
 357   <p>Server certificates with SCTs which are older than this maximum age will
 358   be resubmitted to configured logs.  Generally the log will return the same SCT
 359   as before, but that is subject to log operation.  SCTs will be refreshed as
 360   necessary during normal server operation, with new SCTs returned to clients
 361   as they become available.</p>
 362
 363 </div>
 364 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 365 <div class="directive-section"><h2><a name="CTProxyAwareness" id="CTProxyAwareness">CTProxyAwareness</a> <a name="ctproxyawareness" id="ctproxyawareness">Directive</a></h2>
 366 <table class="directive">
 367 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Level of CT awareness and enforcement for a proxy
 368 </td></tr>
 369 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTProxyAwareness <em>oblivious|aware|require</em></code></td></tr>
 370 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>aware</code></td></tr>
 371 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 372 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 373 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 374 </table>
 375   <p>This directive controls awareness and checks for valid SCTs for a
 376   proxy.  Several options are available:</p>
 377
 378   <dl>
 379     <dt>oblivious</dt>
 380     <dd>The proxy will neither ask for nor examine SCTs.  Certificate
 381     Transparency processing for the proxy is completely disabled.</dd>
 382
 383     <dt>aware</dt>
 384     <dd>The proxy will perform all appropriate Certificate Transparency
 385     processing, such as asking for and examining SCTs.  However, the
 386     proxy will not disallow communication if the origin server does
 387     not provide any valid SCTs.</dd>
 388
 389     <dt>require</dt>
 390     <dd>The proxy will abort communication with the origin server if it
 391     does not provide at least one SCT which passes on-line validation.</dd>
 392   </dl>
 393
 394
 395 </div>
 396 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 397 <div class="directive-section"><h2><a name="CTSCTStorage" id="CTSCTStorage">CTSCTStorage</a> <a name="ctsctstorage" id="ctsctstorage">Directive</a></h2>
 398 <table class="directive">
 399 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Existing directory where SCTs are managed</td></tr>
 400 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTSCTStorage <em>directory</em></code></td></tr>
 401 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
 402 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 403 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 404 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 405 </table>
 406   <p>The <code class="directive">CTSCTStorage</code> directive sets the name of a
 407   directory where SCTs and SCT lists will will be stored.  If <em>directory</em>
 408   is not absolute then it is assumed to be relative to <code class="directive"><a href="../mod/core.html#defaultruntimedir">
 409   DefaultRuntimeDir</a></code>.</p>
 410
 411   <p>A subdirectory for each server certificate contains information relative
 412   to that certificate; the name of the subdirectory is the SHA-256 hash of the
 413   certificate.</p>
 414
 415   <p>The certificate-specific directory contains SCTs retrieved from configured
 416   logs, SCT lists prepared from statically configured SCTs and retrieved SCTs,
 417   and other information used for managing SCTs.</p>
 418
 419 </div>
 420 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 421 <div class="directive-section"><h2><a name="CTServerHelloSCTLimit" id="CTServerHelloSCTLimit">CTServerHelloSCTLimit</a> <a name="ctserverhellosctlimit" id="ctserverhellosctlimit">Directive</a></h2>
 422 <table class="directive">
 423 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limit on number of SCTs that can be returned in
 424 ServerHello</td></tr>
 425 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTServerHelloSCTLimit <em>limit</em></code></td></tr>
 426 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>100</code></td></tr>
 427 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 428 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 429 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 430 </table>
 431   <p>This directive can be used to limit the number of SCTs which can be
 432   returned by a TLS server in ServerHello, in case the number of configured
 433   logs and statically-defined SCTs is relatively high.</p>
 434
 435   <p>Typically only a few SCTs would be available, so this directive is only
 436   needed in special circumstances.</p>
 437
 438   <p>The directive does not take into account SCTs which may be provided in
 439   certificate extensions or in stapled OCSP responses.</p>
 440
 441 </div>
 442 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 443 <div class="directive-section"><h2><a name="CTStaticLogConfig" id="CTStaticLogConfig">CTStaticLogConfig</a> <a name="ctstaticlogconfig" id="ctstaticlogconfig">Directive</a></h2>
 444 <table class="directive">
 445 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Static configuration of information about a log</td></tr>
 446 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTStaticLogConfig <em>log-id|-</em> <em>public-key-file|-</em>
 447 <em>1|0|-</em> <em>min-timestamp|-</em> <em>max-timestamp|-</em>
 448 <em>log-URL|-</em></code></td></tr>
 449 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
 450 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 451 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 452 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 453 </table>
 454   <p>This directive is used to configure information about a particular log.
 455   This directive is appropriate when configuration information changes rarely.
 456   If dynamic configuration updates must be supported, refer to the
 457   <code class="directive"><a href="#ctlogconfigdb">CTLogConfigDB</a></code> directive.</p>
 458
 459   <p>Each of the six fields must be specified, but usually only a small
 460   amount of information must be configured for each log; use <em>-</em> when no
 461   information is available for the field.  The fields are defined as follows:</p>
 462
 463   <dl>
 464     <dt><em>log-id</em></dt>
 465     <dd>This is the id of the log, which is the SHA-256 hash of the log's
 466     public key.</dd>
 467
 468     <dt><em>public-key-file</em></dt>
 469     <dd>This is the name of a file containing the PEM encoding of the log's
 470     public key.  If the name is not absolute, then it is assumed to be relative
 471     to <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</dd>
 472
 473     <dt><em>trust</em></dt>
 474     <dd>This is a generic <q>trust</q> flag.  Set this field to <em>0</em> to
 475     distrust this log.</dd>
 476
 477     <dt><em>min-timestamp</em></dt>
 478     <dd>SCTs received from this log by the proxy are invalid if the timestamp
 479     is older than this value.</dd>
 480
 481     <dt><em>max-timestamp</em></dt>
 482     <dd>SCTs received from this log by the proxy are invalid if the timestamp
 483     is newer than this value.</dd>
 484
 485     <dt><em>log-URL</em></dt>
 486     <dd>This is the URL of the log, for use in submitting server certificates
 487     and in turn obtaining an SCT to be sent to clients.</dd>
 488   </dl>
 489
 490 <h3>See also</h3>
 491 <ul>
 492 <li><a href="#logconf">Log configuration</a> contains more general information
 493 about the fields which can be configured with this directive.</li>
 494 </ul>
 495 </div>
 496 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 497 <div class="directive-section"><h2><a name="CTStaticSCTs" id="CTStaticSCTs">CTStaticSCTs</a> <a name="ctstaticscts" id="ctstaticscts">Directive</a></h2>
 498 <table class="directive">
 499 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Static configuration of one or more SCTs for a server certificate
 500 </td></tr>
 501 <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>
 502 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
 503 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 504 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 505 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
 506 </table>
 507   <p>This directive is used to statically define one or more SCTs corresponding
 508   to a server certificate.  This mechanism can be used instead of or in
 509   addition to dynamically obtaining SCTs from configured logs.  Any changes to
 510   the set of SCTs for a particular server certificate will be adopted dynamically
 511   without the need to restart the server.</p>
 512
 513   <p><em>certificate-pem-file</em> refers to the server certificate in PEM
 514   format.  If the name is not absolute, then it is assumed to be relative to
 515   <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
 516
 517   <p><em>sct-directory</em> should contain one or more files with extension
 518   <code>.sct</code>, representing one or more SCTs corresponding to the
 519   server certificate.  If <em>sct-directory</em> is not absolute, then it is
 520   assumed to be relative to <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
 521
 522   <p>If <em>sct-directory</em> is empty, no error will be raised.</p>
 523
 524   <p>This directive could be used to identify directories of SCTs maintained by
 525   other infrastructure, provided that they are saved in binary format with
 526   file extension <em>.sct</em></p>
 527
 528 </div>
 529 </div>
 530 <div class="bottomlang">
 531 <p><span>Available Languages: </span><a href="../en/mod/mod_ssl_ct.html" title="English">&nbsp;en&nbsp;</a></p>
 532 </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&amp;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>
 533 <script type="text/javascript"><!--//--><![CDATA[//><!--
 534 var comments_shortname = 'httpd';
 535 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html';
 536 (function(w, d) {
 537     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 538         d.write('<div id="comments_thread"><\/div>');
 539         var s = d.createElement('script');
 540         s.type = 'text/javascript';
 541         s.async = true;
 542         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 543         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 544     }
 545     else {
 546         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 547     }
 548 })(window, document);
 549 //--><!]]></script></div><div id="footer">
 550 <p class="apache">Copyright 2014 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>
 551 <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[//><!--
 552 if (typeof(prettyPrint) !== 'undefined') {
 553     prettyPrint();
 554 }
 555 //--><!]]></script>
 556 </body></html>