| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_ssl_ct.xml.meta"> |
| |
| <name>mod_ssl_ct</name> |
| <description>Implementation of Certificate Transparency (RFC 6962) |
| </description> |
| <status>Extension</status> |
| <sourcefile>mod_ssl_ct.c</sourcefile> |
| <identifier>ssl_ct_module</identifier> |
| |
| <summary> |
| |
| <p>This module provides an implementation of Certificate Transparency, in |
| conjunction with <module>mod_ssl</module> and command-line tools from the |
| <a href="https://code.google.com/p/certificate-transparency/">certificate-transparency</a> |
| open source project. The goal of Certificate Transparency is to expose the |
| use of server certificates which are trusted by browsers but were mistakenly |
| or maliciously issued. More information about Certificate Transparency is |
| available at <a href="http://www.certificate-transparency.org/"> |
| http://www.certificate-transparency.org/</a>. Key terminology used in |
| this documentation:</p> |
| |
| <dl> |
| <dt>Certificate log</dt> |
| <dd>A certificate log, referred to simply as <q>log</q> in this documentation, |
| is a network service to which server certificates have been submitted. A |
| user agent can confirm that the certificate of a server which it accesses |
| has been submitted to a log which it trusts, and that the log itself has |
| not been tampered with.</dd> |
| |
| <dt>Signed Certificate Timestamp (SCT)</dt> |
| <dd>This is an acknowledgement from a log that it has accepted a valid |
| certificate. It is signed with the log's public key. One or more SCTs |
| is passed to clients during the handshake, either in the ServerHello |
| (TLS extension), certificate extension, or in a stapled OCSP response.</dd> |
| </dl> |
| |
| <p>This implementation for Apache httpd provides these features for TLS |
| servers and proxies:</p> |
| |
| <ul> |
| <li>Signed Certificate Timestamps (SCTs) can be obtained from logs |
| automatically and, in conjunction with any statically configured SCTs, sent |
| to aware clients in the ServerHello (during the handshake).</li> |
| <li>SCTs can be received by the proxy from origin servers in the ServerHello, |
| in a certificate extension, and/or within stapled OCSP responses; any SCTs |
| received can be partially validated on-line and optionally queued for off-line |
| audit.</li> |
| <li>The proxy can be configured to disallow communication with an origin |
| server which does not provide an SCT which passes on-line validation.</li> |
| </ul> |
| |
| <p>Configuration information about logs can be defined statically in the web |
| server configuration or maintained in a SQLite3 database. In the latter case, |
| <module>mod_ssl_ct</module> will reload the database periodically, so any |
| site-specific infrastructure for maintaining and propagating log configuration |
| information does not have to also restart httpd to make it take effect.</p> |
| |
| <note>This module is experimental for the following reasons: |
| <ul> |
| <li>Insufficient test and review</li> |
| <li>Reliance on an unreleased version of OpenSSL (1.0.2, Beta 3 or later) for |
| basic operation</li> |
| <li>Incomplete <a href="#audit">off-line audit capability</a></li> |
| </ul> |
| |
| <p>Configuration mechanisms, format of data saved for off-line audit, and |
| other characteristics are subject to change based on further feedback and |
| testing.</p> |
| </note> |
| </summary> |
| |
| <section id="server"> |
| <title>Server processing overview</title> |
| |
| <p>Servers need to send SCTs to their clients. SCTs in a certificate |
| extension or stapled OCSP response will be sent without any special program |
| logic. This module handles sending SCTs configured by the administrator or |
| received from configured logs.</p> |
| |
| <p>The number of SCTs sent in the ServerHello (i.e., not including those in a |
| certificate extension or stapled OCSP response) can be limited by the |
| <directive module="mod_ssl_ct">CTServerHelloSCTLimit</directive> |
| directive.</p> |
| |
| <p>For each server certificate, a daemon process maintains an SCT list to be |
| sent in the ServerHello, created from statically configured SCTs as well as |
| those received from logs. Logs marked as untrusted or with a maximum valid |
| timestamp before the present time will be ignored. Periodically the daemon |
| will submit certificates to a log as necessary (due to changed log |
| configuration or age) and rebuild the concatenation of SCTs.</p> |
| |
| <p>The SCT list for a server certificate will be sent to any client that |
| indicates awareness in the ClientHello when that particular server certificate |
| is used.</p> |
| |
| </section> |
| |
| <section id="proxy"> |
| <title>Proxy processing overview</title> |
| |
| <p>The proxy indicates Certificate Transparency awareness in the ClientHello |
| by including the <em>signed_certificate_timestamp</em> extension. It can |
| recognize SCTs received in the ServerHello, in an extension in the certificate |
| for an origin server, or in a stapled OCSP response.</p> |
| |
| <p>On-line verification is attempted for each received SCT:</p> |
| |
| <ul> |
| <li>For any SCT, the timestamp can be checked to see if it is not yet valid |
| based on the current time as well as any configured valid time interval for |
| the log.</li> |
| <li>For an SCT from a log for which a public key is configured, the server |
| signature will be checked.</li> |
| </ul> |
| |
| <p>If verification fails for at least one SCT and verification was not |
| successful for at least one SCT, the connection is aborted if |
| <directive module="mod_ssl_ct">CTProxyAwareness</directive> is set to |
| <em>require</em>.</p> |
| |
| <p>Additionally, the server certificate chain and SCTs are stored for off-line |
| verification if the <directive module="mod_ssl_ct">CTAuditStorage</directive> |
| directive is configured.</p> |
| |
| <p>As an optimization, on-line verification and storing of data from the |
| server is only performed the first time a web server child process receives |
| the data. This saves some processing time as well as disk space. For typical |
| reverse proxy setups, very little processing overhead will be required.</p> |
| |
| </section> |
| |
| <section id="logconf"> |
| <title>Log configuration</title> |
| |
| <p>Servers and proxies use different information about logs for their processing. |
| This <em>log configuration</em> can be set in two ways:</p> |
| |
| <ul> |
| <li>Create a log configuration database using <program>ctlogconfig</program>, |
| and configure the path to that database using the <directive module="mod_ssl_ct"> |
| CTLogConfig</directive> directive. This method of configuration supports |
| dynamic updates; <module>mod_ssl_ct</module> will re-read the database at |
| intervals. Additionally, the off-line audit program <code>ctauditscts</code> |
| can use this configuration to find the URL of logs.</li> |
| |
| <li>Configure information about logs statically using the <directive |
| module="mod_ssl_ct">CTStaticLogConfig</directive> directive. As with all other |
| directives, the server must be restarted in order to pick up changes to the |
| directives.</li> |
| </ul> |
| |
| <p>The information that can be configured about a log using either mechanism is |
| described below:</p> |
| |
| <dl> |
| <dt>log id</dt> |
| <dd>The log id is the SHA-256 hash of the log's public key, and is part of |
| every SCT. This is a convenient way to identify a particular log when |
| configuring valid timestamp ranges or certain other information.</dd> |
| |
| <dt>public key of the log</dt> |
| <dd>A proxy must have the public key of the log in order to check the |
| signature in SCTs it receives which were obtained from the log. |
| <br /> |
| A server must have the public key of the log in order to submit certificates |
| to it.</dd> |
| |
| <dt>general trust/distrust setting</dt> |
| <dd>This is a mechanism to distrust or restore trust in a particular log, |
| for whatever reason (including simply avoiding interaction with the |
| log in situations where it is off-line).</dd> |
| |
| <dt>minimum and/or maximum valid timestamps</dt> |
| <dd>When configured, the proxy will check that timestamps from SCTs |
| are within the valid range.</dd> |
| |
| <dt>log URL</dt> |
| <dd>The URL of the log (for its API) is required by a server in order to |
| submit server certificates to the log. The server will submit |
| each server certificate in order to obtain an SCT for each log with a |
| configured URL, except when the log is also marked as distrusted or the |
| current time is not within any configured valid timestamp range. |
| <br /> |
| The log URL is also needed by off-line auditing of SCTs received by a |
| proxy.</dd> |
| </dl> |
| |
| <p>Generally, only a small subset of this information is configured for a |
| particular log. Refer to the documentation for the <directive |
| module="mod_ssl_ct">CTStaticLogConfig</directive> directive and the |
| <program>ctlogconfig</program> command for more specific information.</p> |
| |
| </section> |
| |
| <section id="static"> |
| <title>Storing SCTs in a form consumable by mod_ssl_ct</title> |
| |
| <p><module>mod_ssl_ct</module> allows you to configure SCTs statically |
| using the <directive>CTStaticSCTs</directive> directive. These must be |
| in binary form, ready to send to a client.</p> |
| |
| <p>Sample code in the form of a Python script to build an SCT in the correct |
| format from data received from a log can be found in |
| <a href="https://github.com/tomrittervg/ct-tools">Tom Ritter's ct-tools |
| repository</a>. Refer to <code>write-sct.py</code></p> |
| </section> |
| |
| <section id="logging"> |
| <title>Logging CT status in the access log</title> |
| |
| <p>Proxy and server modes set the <code>SSL_CT_PROXY_STATUS</code> and |
| <code>SSL_CT_CLIENT_STATUS</code> variables, respectively, to indicate |
| if the corresponding peer is CT-aware.</p> |
| |
| <p>Proxy mode sets the <code>SSL_CT_PROXY_SCT_SOURCES</code> variable to |
| indicate whether and where SCTs were obtained (ServerHello, certificate |
| extension, etc.).</p> |
| |
| <p>These variables can be logged with the <code>%{<em>varname</em>}e</code> |
| format of <module>mod_log_config</module>.</p> |
| </section> |
| |
| <section id="audit"> |
| <title>Off-line audit for proxy</title> |
| |
| <p>Experimental support for this is implemented in the <code>ctauditscts</code> |
| command, which itself relies on the <code>verify_single_proof.py</code> tool in the |
| <em>certificate-transparency</em> open source project. <code>ctauditscts</code> |
| can parse data for off-line audit (enabled with the <directive module="mod_ssl_ct"> |
| CTAuditStorage</directive> directive) and invoke <code>verify_single_proof.py</code>. |
| </p> |
| |
| <p>Here are rough notes for using <code>ctauditscts</code>:</p> |
| |
| <ul> |
| <li>Create a <em>virtualenv</em> using the <code>requirements.txt</code> file |
| from the <em>certificate-transparency</em> project and run the following steps |
| with that <em>virtualenv</em> activated.</li> |
| <li>Set <code>PYTHONPATH</code> to include the <code>python</code> |
| directory within the <em>certificate-transparency</em> tools.</li> |
| <li>Set <code>PATH</code> to include the <code>python/ct/client/tools</code> |
| directory.</li> |
| <li>Run <code>ctauditscts</code>, passing the value of the |
| <directive>CTAuditStorage</directive> directive and, optionally, the path to |
| the log configuration database. The latter will be used to look up log URLs |
| by log id.</li> |
| </ul> |
| |
| <p>The data saved for audit can also be used by other programs; refer to the |
| <code>ctauditscts</code> source code for details on processing the data.</p> |
| </section> |
| |
| <directivesynopsis> |
| <name>CTAuditStorage</name> |
| <description>Existing directory where data for off-line audit will be stored</description> |
| <syntax>CTAuditStorage <em>directory</em></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>The <directive>CTAuditStorage</directive> directive sets the name of a |
| directory where data will be stored for off-line audit. If <em>directory</em> |
| is not absolute then it is assumed to be relative to <directive module="core"> |
| DefaultRuntimeDir</directive>.</p> |
| |
| <p>If this directive is not specified, data will not be stored for off-line |
| audit.</p> |
| |
| <p>The directory will contain files named <code><em>PID</em>.tmp</code> for |
| active child processes and files named <code><em>PID</em>.out</code> for exited |
| child processes. These <code>.out</code> files are ready for off-line audit. |
| The experimental command <code>ctauditscts</code> (in the httpd source tree, not |
| currently installed) interfaces with <em>certificate-transparency</em> tools to |
| perform the audit.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CTLogClient</name> |
| <description>Location of certificate-transparency log client tool</description> |
| <syntax>CTLogClient <em>executable</em></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| </contextlist> |
| |
| <usage> |
| <p><em>executable</em> is the full path to the log client tool, which is |
| normally file <code>cpp/client/ct</code> (or <code>ct.exe</code>) within the |
| source tree of the |
| <a href="https://code.google.com/p/certificate-transparency/"> |
| certificate-transparency</a> open source project.</p> |
| |
| <p>An alternative implementation could be used to retrieve SCTs for a |
| server certificate as long as the command-line interface is equivalent.</p> |
| |
| <p>If this directive is not configured, server certificates cannot be |
| submitted to logs in order to obtain SCTs; thus, only admin-managed |
| SCTs or SCTs in certificate extensions will be provided to clients.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CTLogConfigDB</name> |
| <description>Log configuration database supporting dynamic updates</description> |
| <syntax>CTLogConfigDB <em>filename</em></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>The <directive>CTLogConfigDB</directive> directive sets the name of a database |
| containing configuration about known logs. If <em>filename</em> is not absolute |
| then it is assumed to be relative to |
| <directive module="core">ServerRoot</directive>.</p> |
| |
| <p>Refer to the documentation for the <program>ctlogconfig</program> program, |
| which manages the database.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CTMaxSCTAge</name> |
| <description>Maximum age of SCT obtained from a log, before it will be |
| refreshed</description> |
| <syntax>CTMaxSCTAge <em>num-seconds</em></syntax> |
| <default>1 day</default> |
| <contextlist><context>server config</context></contextlist> |
| |
| <usage> |
| <p>Server certificates with SCTs which are older than this maximum age will |
| be resubmitted to configured logs. Generally the log will return the same SCT |
| as before, but that is subject to log operation. SCTs will be refreshed as |
| necessary during normal server operation, with new SCTs returned to clients |
| as they become available.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CTProxyAwareness</name> |
| <description>Level of CT awareness and enforcement for a proxy |
| </description> |
| <syntax>CTProxyAwareness <em>oblivious|aware|require</em></syntax> |
| <default>aware</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context></contextlist> |
| |
| <usage> |
| <p>This directive controls awareness and checks for valid SCTs for a |
| proxy. Several options are available:</p> |
| |
| <dl> |
| <dt>oblivious</dt> |
| <dd>The proxy will neither ask for nor examine SCTs. Certificate |
| Transparency processing for the proxy is completely disabled.</dd> |
| |
| <dt>aware</dt> |
| <dd>The proxy will perform all appropriate Certificate Transparency |
| processing, such as asking for and examining SCTs. However, the |
| proxy will not disallow communication if the origin server does |
| not provide any valid SCTs.</dd> |
| |
| <dt>require</dt> |
| <dd>The proxy will abort communication with the origin server if it |
| does not provide at least one SCT which passes on-line validation.</dd> |
| </dl> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CTSCTStorage</name> |
| <description>Existing directory where SCTs are managed</description> |
| <syntax>CTSCTStorage <em>directory</em></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>CTSCTStorage</directive> directive sets the name of a |
| directory where SCTs and SCT lists will be stored. If <em>directory</em> |
| is not absolute then it is assumed to be relative to <directive module="core"> |
| DefaultRuntimeDir</directive>.</p> |
| |
| <p>A subdirectory for each server certificate contains information relative |
| to that certificate; the name of the subdirectory is the SHA-256 hash of the |
| certificate.</p> |
| |
| <p>The certificate-specific directory contains SCTs retrieved from configured |
| logs, SCT lists prepared from statically configured SCTs and retrieved SCTs, |
| and other information used for managing SCTs.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CTServerHelloSCTLimit</name> |
| <description>Limit on number of SCTs that can be returned in |
| ServerHello</description> |
| <syntax>CTServerHelloSCTLimit <em>limit</em></syntax> |
| <default>100</default> |
| <contextlist><context>server config</context> |
| </contextlist> |
| |
| <usage> |
| <p>This directive can be used to limit the number of SCTs which can be |
| returned by a TLS server in ServerHello, in case the number of configured |
| logs and statically-defined SCTs is relatively high.</p> |
| |
| <p>Typically only a few SCTs would be available, so this directive is only |
| needed in special circumstances.</p> |
| |
| <p>The directive does not take into account SCTs which may be provided in |
| certificate extensions or in stapled OCSP responses.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CTStaticLogConfig</name> |
| <description>Static configuration of information about a log</description> |
| <syntax>CTStaticLogConfig <em>log-id|-</em> <em>public-key-file|-</em> |
| <em>1|0|-</em> <em>min-timestamp|-</em> <em>max-timestamp|-</em> |
| <em>log-URL|-</em></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| </contextlist> |
| |
| <usage> |
| <p>This directive is used to configure information about a particular log. |
| This directive is appropriate when configuration information changes rarely. |
| If dynamic configuration updates must be supported, refer to the |
| <directive module="mod_ssl_ct">CTLogConfigDB</directive> directive.</p> |
| |
| <p>Each of the six fields must be specified, but usually only a small |
| amount of information must be configured for each log; use <em>-</em> when no |
| information is available for the field. For example, in support of a |
| server-only configuration (i.e., no proxy), the administrator might |
| configure only the log URL to be used when submitting server certificates |
| and obtaining a Signed Certificate Timestamp.</p> |
| |
| <p>The fields are defined as follows:</p> |
| |
| <dl> |
| <dt><em>log-id</em></dt> |
| <dd>This is the id of the log, which is the SHA-256 hash of the log's |
| public key, provided in hexadecimal format. This string is 64 characters |
| in length. |
| <br /> |
| This field should be omitted when <em>public-key-file</em> is provided.</dd> |
| |
| <dt><em>public-key-file</em></dt> |
| <dd>This is the name of a file containing the PEM encoding of the log's |
| public key. If the name is not absolute, then it is assumed to be relative |
| to <directive module="core">ServerRoot</directive>.</dd> |
| |
| <dt><em>trust/distrust</em></dt> |
| <dd>Set this field to <em>1</em> to distrust this log, or to otherwise avoid |
| using it for server certificate submission. Set this to <em>-</em> or |
| <em>0</em> (the default) to treat the log normally.</dd> |
| |
| <dt><em>min-timestamp</em> and <em>max-timestamp</em></dt> |
| <dd>A timestamp is a time as expressed in the number of milliseconds since the |
| epoch, ignoring leap seconds. This is the form of time used in Signed Certificate |
| Timestamps. This must be provided as a decimal number. |
| <br /> |
| Specify <strong><code>-</code></strong> for one of the timestamps if it is unknown. |
| For example, when configuring the minimum valid timestamp for a log which remains |
| valid, specify <strong><code>-</code></strong> for <em>max-timestamp</em>. |
| <br /> |
| SCTs received from this log by the proxy are invalid if the timestamp |
| is older than <em>min-timestamp</em> or newer than <em>max-timestamp</em>.</dd> |
| |
| <dt><em>log-URL</em></dt> |
| <dd>This is the URL of the log, for use in submitting server certificates |
| and in turn obtaining an SCT to be sent to clients.</dd> |
| </dl> |
| </usage> |
| |
| <seealso><a href="#logconf">Log configuration</a> contains more general information |
| about the fields which can be configured with this directive.</seealso> |
| |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CTStaticSCTs</name> |
| <description>Static configuration of one or more SCTs for a server certificate |
| </description> |
| <syntax>CTStaticSCTs <em>certificate-pem-file</em> <em>sct-directory</em></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| </contextlist> |
| |
| <usage> |
| <p>This directive is used to statically define one or more SCTs corresponding |
| to a server certificate. This mechanism can be used instead of or in |
| addition to dynamically obtaining SCTs from configured logs. Any changes to |
| the set of SCTs for a particular server certificate will be adopted dynamically |
| without the need to restart the server.</p> |
| |
| <p><em>certificate-pem-file</em> refers to the server certificate in PEM |
| format. If the name is not absolute, then it is assumed to be relative to |
| <directive module="core">ServerRoot</directive>.</p> |
| |
| <p><em>sct-directory</em> should contain one or more files with extension |
| <code>.sct</code>, representing one or more SCTs corresponding to the |
| server certificate. If <em>sct-directory</em> is not absolute, then it is |
| assumed to be relative to <directive module="core">ServerRoot</directive>.</p> |
| |
| <p>If <em>sct-directory</em> is empty, no error will be raised.</p> |
| |
| <p>This directive could be used to identify directories of SCTs maintained by |
| other infrastructure, provided that they are saved in binary format with |
| file extension <em>.sct</em></p> |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |