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