2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_ssl_ct.xml.meta">
25 <name>mod_ssl_ct</name>
26 <description>Implementation of Certificate Transparency (RFC 6962)
28 <status>Extension</status>
29 <sourcefile>mod_ssl_ct.c</sourcefile>
30 <identifier>ssl_ct_module</identifier>
34 <p>This module provides an implementation of Certificate Transparency, in
35 conjunction with <module>mod_ssl</module> and command-line tools from the
36 <a href="https://code.google.com/p/certificate-transparency/">certificate-transparency</a>
37 open source project. The goal of Certificate Transparency is to expose the
38 use of server certificates which are trusted by browsers but were mistakenly
39 or maliciously issued. More information about Certificate Transparency is
40 available at <a href="http://www.certificate-transparency.org/">
41 http://www.certificate-transparency.org/</a>.</p>
43 <p>This implementation for Apache httpd provides these features for TLS
44 servers and proxies:</p>
47 <li>Signed Certificate Timestamps (SCTs) can be obtained from logs
48 automatically and, in conjunction with any statically configured SCTs, sent
49 to aware clients in the ServerHello (during the handshake).</li>
50 <li>SCTs can be received by the proxy from origin servers in the ServerHello,
51 in a certificate extension, and/or within stapled OCSP responses; any SCTs
52 received can be partially validated on-line and optionally queued for off-line
54 <li>The proxy can be configured to disallow communication with an origin
55 server which does not provide an SCT which passes on-line validation.</li>
58 <p>Configuration information about logs can be defined statically in the web
59 server configuration or maintained in a SQLite3 database. In the latter case,
60 <module>mod_ssl_ct</module> will reload the database periodically, so any
61 site-specific infrastructure for maintaining and propagating log configuration
62 information does not have to also restart httpd to make it take effect.</p>
64 <note>This module is experimental for the following reasons:
66 <li>Insufficient test and review</li>
67 <li>Reliance on an unreleased version of OpenSSL (1.0.2) for basic
69 <li>Incomplete <a href="#audit">off-line audit capability</a></li>
72 <p>Configuration mechanisms, format of data saved for off-line audit, and
73 other characteristics are subject to change based on further feedback and
79 <title>Server processing overview</title>
81 <p>Servers need to send SCTs to their clients. SCTs in a certificate
82 extension or stapled OCSP response will be sent without any special program
83 logic. This module handles sending SCTs configured by the administrator or
84 received from configured logs.</p>
86 <p>The number of SCTs sent in the ServerHello (i.e., not including those in a
87 certificate extension or stapled OCSP response) can be limited by the
88 <directive module="mod_ssl_ct">CTServerHelloSCTLimit</directive>
91 <p>For each server certificate, a daemon process maintains an SCT list to be
92 sent in the ServerHello, created from statically configured SCTs as well as
93 those received from logs. Logs marked as untrusted or with a maximum valid
94 timestamp before the present time will be ignored. Periodically the daemon
95 will submit certificates to a log as necessary (due to changed log
96 configuration or age) and rebuild the concatenation of SCTs.</p>
98 <p>The SCT list for a server certificate will be sent to any client that
99 indicates awareness in the ClientHello when that particular server certificate
105 <title>Proxy processing overview</title>
107 <p>The proxy indicates Certificate Transparency awareness in the ClientHello
108 by including the <em>signed_certificate_timestamp</em> extension. It can
109 recognize SCTs received in the ServerHello, in an extension in the certificate
110 for an origin server, or in a stapled OCSP response.</p>
112 <p>On-line verification is attempted for each received SCT:</p>
115 <li>For any SCT, the timestamp can be checked to see if it is not yet valid
116 based on the current time as well as any configured valid time interval for
118 <li>For an SCT from a log for which a public key is configured, the server
119 signature will be checked.</li>
122 <p>If verification fails for at least one SCT and verification was not
123 successful for at least one SCT, the connection is aborted if
124 <directive module="mod_ssl_ct">CTProxyAwareness</directive> is set to
125 <em>require</em>.</p>
127 <p>Additionally, the server certificate chain and SCTs are stored for off-line
128 verification if the <directive module="mod_ssl_ct">CTAuditStorage</directive>
129 directive is configured.</p>
131 <p>As an optimization, on-line verification and storing of data from the
132 server is only performed the first time a web server child process receives
133 the data. This saves some processing time as well as disk space. For typical
134 reverse proxy setups, very little processing overhead will be required.</p>
138 <section id="logconf">
139 <title>Log configuration</title>
141 <p>Servers and proxies use different information about logs for their processing.
142 This <em>log configuration</em> can be set in two ways:</p>
145 <li>Create a log configuration database using <program>ctlogconfig</program>,
146 and configure the path to that database using the <directive module="mod_ssl_ct">
147 CTLogConfig</directive> directive. This method of configuration supports
148 dynamic updates; <module>mod_ssl_ct</module> will re-read the database at
149 intervals. Additionally, the off-line audit program <code>ctauditscts</code>
150 can use this configuration to find the URL of logs.</li>
152 <li>Configure information about logs statically using the <directive
153 module="mod_ssl_ct">CTStaticLogConfig</directive> directive. As with all other
154 directives, the server must be restarted in order to pick up changes to the
158 <p>The information that can be configured about a log using either mechanism is
163 <dd>The log id is the SHA-256 hash of the log's public key, and is part of
164 every SCT. This is a convenient way to identify a particular log when
165 configuring valid timestamp ranges or certain other information.</dd>
167 <dt>public key of the log</dt>
168 <dd>A proxy must have the public key of the log in order to check the
169 signature in SCTs it receives which were obtained from the log.</dd>
171 <dt>general trust/distrust setting</dt>
172 <dd>This is a mechanism to distrust or restore trust in a particular log,
173 for whatever reason (including simply avoiding interaction with the
174 log in situations where it is off-line).</dd>
176 <dt>minimum and/or maximum valid timestamps</dt>
177 <dd>When configured, the proxy will check that timestamps from SCTs
178 are within the valid range.</dd>
181 <dd>The URL of the log (for its API) is required by a server in order to
182 submit server certificates to the log. The server will submit
183 each server certificate in order to obtain an SCT for each log with a
184 configured URL, except when the log is also marked as distrusted or the
185 current time is not within any configured valid timestamp range.
187 The log URL is also needed by off-line auditing of SCTs received by a
191 <p>Generally, only a small subset of this information is configured for a
192 particular log. Refer to the documentation for the <directive
193 module="mod_ssl_ct">CTStaticLogConfig</directive> and the
194 <program>ctlogconfig</program> command for more specific information.</p>
198 <section id="logging">
199 <title>Logging CT status in the access log</title>
201 <p>Both proxy and server modes set the <code>SSL_CT_PEER_STATUS</code>
202 variable to indicate if the peer is CT-aware.</p>
204 <p>Proxy mode sets the <code>SSL_PROXY_SCT_SOURCES</code> variable to
205 indicate whether and where SCTs were obtained (ServerHello, certificate
206 extension, etc.).</p>
208 <p>These variables can be logged with the <code>%{<em>varname</em>}e</code>
209 format of <module>mod_log_config</module>.</p>
213 <title>Off-line audit for proxy</title>
215 <p>Experimental support for this is implemented in the <code>ctauditscts</code>
216 command (in the httpd source tree, not currently installed), which itself
217 relies on the <code>verify_single_proof.py</code> tool in the
218 <em>certificate-transparency</em> open source project. <code>ctauditscts</code>
219 can parse data for off-line audit (enabled with the <directive module="mod_ssl_ct">
220 CTAuditStorage</directive> directive) and invoke <code>verify_single_proof.py</code>.
221 However, <code>verify_single_proof.py</code> is not complete currently and does
222 not provide a way to identify audit failures.</p>
224 <p>Here are rough notes for using <code>ctauditscts</code>:</p>
227 <li>Set <code>PYTHONPATH</code> to include the <code>src/python</code>
228 directory within the <em>certificate-transparency</em> tools.</li>
229 <li>Set <code>PATH</code> to include the <code>src/python/ct/client/tools</code>
231 <li>Run <code>ctauditscts</code>, passing the value of the
232 <directive>CTAuditStorage</directive> directive and, optionally, the path to
233 the log configuration database. The latter will be used to look up log URLs
237 <p>The data saved for audit can also be used by other programs; refer to the
238 <code>ctauditscts</code> source code for details.</p>
242 <name>CTAuditStorage</name>
243 <description>Existing directory where data for off-line audit will be stored</description>
244 <syntax>CTAuditStorage <em>directory</em></syntax>
245 <default>none</default>
246 <contextlist><context>server config</context></contextlist>
249 <p>The <directive>CTAuditStorage</directive> directive sets the name of a
250 directory where data will be stored for off-line audit. If <em>directory</em>
251 is not absolute then it is assumed to be relative to <directive module="core">
252 DefaultRuntimeDir</directive>.</p>
254 <p>If this directive is not specified, data will not be stored for off-line
257 <p>The directory will contain files named <code><em>PID</em>.tmp</code> for
258 active child processes and files named <code><em>PID</em>.out</code> for exited
259 child processes. These <code>.out</code> files are ready for off-line audit.
260 The experimental command <code>ctauditscts</code> (in the httpd source tree, not
261 currently installed) interfaces with <em>certificate-transparency</em> tools to
262 perform the audit.</p>
267 <name>CTLogClient</name>
268 <description>Location of certificate-transparency log client tool</description>
269 <syntax>CTLogClient <em>executable</em></syntax>
270 <default>none</default>
271 <contextlist><context>server config</context>
275 <p><em>executable</em> is the full path to the log client tool, which is
276 normally file <code>src/client/ct</code> within the source tree of the
277 <a href="https://code.google.com/p/certificate-transparency/">
278 certificate-transparency</a> open source project.</p>
280 <p>An alternative implementation could be used to retrieve SCTs for a
281 server certificate as long as the command-line interface is equivalent.</p>
283 <p>If this directive is not configured, server certificates cannot be
284 submitted to logs in order to obtain SCTs; thus, only admin-managed
285 SCTs will be provided to clients.</p>
290 <name>CTLogConfigDB</name>
291 <description>Log configuration database supporting dynamic updates</description>
292 <syntax>CTLogConfigDB <em>filename</em></syntax>
293 <default>none</default>
294 <contextlist><context>server config</context></contextlist>
297 <p>The <directive>CTLogConfigDB</directive> directive sets the name of a database
298 containing configuration about known logs. If <em>filename</em> is not absolute
299 then it is assumed to be relative to
300 <directive module="core">ServerRoot</directive>.</p>
302 <p>Refer to the documentation for the <program>ctlogconfig</program> program,
303 which manages the database.</p>
308 <name>CTMaxSCTAge</name>
309 <description>Maximum age of SCT obtained from a log, before it will be
310 refreshed</description>
311 <syntax>CTMaxSCTAge <em>num-seconds</em></syntax>
312 <default>1 day</default>
313 <contextlist><context>server config</context></contextlist>
316 <p>Server certificates with SCTs which are older than this maximum age will
317 be resubmitted to configured logs. Generally the log will return the same SCT
318 as before, but that is subject to log operation. SCTs will be refreshed as
319 necessary during normal server operation, with new SCTs returned to clients
320 as they become available.</p>
325 <name>CTProxyAwareness</name>
326 <description>Level of CT awareness and enforcement for a proxy
328 <syntax>CTProxyAwareness <em>oblivious|aware|require</em></syntax>
329 <default>aware</default>
330 <contextlist><context>server config</context>
331 <context>virtual host</context></contextlist>
334 <p>This directive controls awareness and checks for valid SCTs for a
335 proxy. Several options are available:</p>
339 <dd>The proxy will neither ask for nor examine SCTs. Certificate
340 Transparency processing for the proxy is completely disabled.</dd>
343 <dd>The proxy will perform all appropriate Certificate Transparency
344 processing, such as asking for and examining SCTs. However, the
345 proxy will not disallow communication if the origin server does
346 not provide any valid SCTs.</dd>
349 <dd>The proxy will abort communication with the origin server if it
350 does not provide at least one SCT which passes on-line validation.</dd>
357 <name>CTSCTStorage</name>
358 <description>Existing directory where SCTs are managed</description>
359 <syntax>CTSCTStorage <em>directory</em></syntax>
360 <default>none</default>
361 <contextlist><context>server config</context>
365 <p>The <directive>CTSCTStorage</directive> directive sets the name of a
366 directory where SCTs and SCT lists will will be stored. If <em>directory</em>
367 is not absolute then it is assumed to be relative to <directive module="core">
368 DefaultRuntimeDir</directive>.</p>
370 <p>A subdirectory for each server certificate contains information relative
371 to that certificate; the name of the subdirectory is the SHA-256 hash of the
374 <p>The certificate-specific directory contains SCTs retrieved from configured
375 logs, SCT lists prepared from statically configured SCTs and retrieved SCTs,
376 and other information used for managing SCTs.</p>
381 <name>CTServerHelloSCTLimit</name>
382 <description>Limit on number of SCTs that can be returned in
383 ServerHello</description>
384 <syntax>CTServerHelloSCTLimit <em>limit</em></syntax>
385 <default>100</default>
386 <contextlist><context>server config</context>
390 <p>This directive can be used to limit the number of SCTs which can be
391 returned by a TLS server in ServerHello, in case the number of configured
392 logs and statically-defined SCTs is relatively high.</p>
394 <p>Typically only a few SCTs would be available, so this directive is only
395 needed in special circumstances.</p>
397 <p>The directive does not take into account SCTs which may be provided in
398 certificate extensions or in stapled OCSP responses.</p>
403 <name>CTStaticLogConfig</name>
404 <description>Static configuration of information about a log</description>
405 <syntax>CTStaticLogConfig <em>log-id|-</em> <em>public-key-file|-</em>
406 <em>1|0|-</em> <em>min-timestamp|-</em> <em>max-timestamp|-</em>
407 <em>log-URL|-</em></syntax>
408 <default>none</default>
409 <contextlist><context>server config</context>
413 <p>This directive is used to configure information about a particular log.
414 This directive is appropriate when configuration information changes rarely.
415 If dynamic configuration updates must be supported, refer to the
416 <directive module="mod_ssl_ct">CTLogConfigDB</directive> directive.</p>
418 <p>Each of the six fields must be specified, but usually only a small
419 amount of information must be configured for each log; use <em>-</em> when no
420 information is available for the field. The fields are defined as follows:</p>
423 <dt><em>log-id</em></dt>
424 <dd>This is the id of the log, which is the SHA-256 hash of the log's
427 <dt><em>public-key-file</em></dt>
428 <dd>This is the name of a file containing the PEM encoding of the log's
429 public key. If the name is not absolute, then it is assumed to be relative
430 to <directive module="core">ServerRoot</directive>.</dd>
432 <dt><em>trust</em></dt>
433 <dd>This is a generic <q>trust</q> flag. Set this field to <em>0</em> to
434 distrust this log.</dd>
436 <dt><em>min-timestamp</em></dt>
437 <dd>SCTs received from this log by the proxy are invalid if the timestamp
438 is older than this value.</dd>
440 <dt><em>max-timestamp</em></dt>
441 <dd>SCTs received from this log by the proxy are invalid if the timestamp
442 is newer than this value.</dd>
444 <dt><em>log-URL</em></dt>
445 <dd>This is the URL of the log, for use in submitting server certificates
446 and in turn obtaining an SCT to be sent to clients.</dd>
450 <seealso><a href="#logconf">Log configuration</a> contains more general information
451 about the fields which can be configured with this directive.</seealso>
456 <name>CTStaticSCTs</name>
457 <description>Static configuration of one or more SCTs for a server certificate
459 <syntax>CTStaticSCTs <em>certificate-pem-file</em> <em>sct-directory</em></syntax>
460 <default>none</default>
461 <contextlist><context>server config</context>
465 <p>This directive is used to statically define one or more SCTs corresponding
466 to a server certificate. This mechanism can be used instead of or in
467 addition to dynamically obtaining SCTs from configured logs. Any changes to
468 the set of SCTs for a particular server certificate will be adopted dynamically
469 without the need to restart the server.</p>
471 <p><em>certificate-pem-file</em> refers to the server certificate in PEM
472 format. If the name is not absolute, then it is assumed to be relative to
473 <directive module="core">ServerRoot</directive>.</p>
475 <p><em>sct-directory</em> should contain one or more files with extension
476 <code>.sct</code>, representing one or more SCTs corresponding to the
477 server certificate. If <em>sct-directory</em> is not absolute, then it is
478 assumed to be relative to <directive module="core">ServerRoot</directive>.</p>
480 <p>If <em>sct-directory</em> is empty, no error will be raised.</p>
482 <p>This directive could be used to identify directories of SCTs maintained by
483 other infrastructure, provided that they are saved in binary format with
484 file extension <em>.sct</em></p>