Apache HTTP Server Version 2.5
|Description:||Implementation of Certificate Transparency (RFC 6962)|
This module provides an implementation of Certificate Transparency, in
mod_ssl and command-line tools from the
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
http://www.certificate-transparency.org/. Key terminology used in
login 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.
This implementation for Apache httpd provides these features for TLS servers and proxies:
Configuration information about logs can be defined statically in the web
server configuration or maintained in a SQLite3 database. In the latter case,
mod_ssl_ct 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.
Configuration mechanisms, format of data saved for off-line audit, and other characteristics are subject to change based on further feedback and testing.
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.
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
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.
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.
The proxy indicates Certificate Transparency awareness in the ClientHello by including the signed_certificate_timestamp 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.
On-line verification is attempted for each received SCT:
If verification fails for at least one SCT and verification was not
successful for at least one SCT, the connection is aborted if
CTProxyAwareness is set to
Additionally, the server certificate chain and SCTs are stored for off-line
verification if the
directive is configured.
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.
Servers and proxies use different information about logs for their processing. This log configuration can be set in two ways:
ctlogconfig, and configure the path to that database using the
CTLogConfigdirective. This method of configuration supports dynamic updates;
mod_ssl_ctwill re-read the database at intervals. Additionally, the off-line audit program
ctauditsctscan use this configuration to find the URL of logs.
CTStaticLogConfigdirective. As with all other directives, the server must be restarted in order to pick up changes to the directives.
The information that can be configured about a log using either mechanism is described below:
Generally, only a small subset of this information is configured for a
particular log. Refer to the documentation for the
CTStaticLogConfig directive and the
ctlogconfig command for more specific information.
mod_ssl_ct allows you to configure SCTs statically
CTStaticSCTs directive. These must be
in binary form, ready to send to a client.
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
Tom Ritter's ct-tools
repository. Refer to
Proxy and server modes set the
SSL_CT_CLIENT_STATUS variables, respectively, to indicate
if the corresponding peer is CT-aware.
Proxy mode sets the
SSL_CT_PROXY_SCT_SOURCES variable to
indicate whether and where SCTs were obtained (ServerHello, certificate
These variables can be logged with the
Experimental support for this is implemented in the
command, which itself relies on the
verify_single_proof.py tool in the
certificate-transparency open source project.
can parse data for off-line audit (enabled with the
CTAuditStorage directive) and invoke
Here are rough notes for using
requirements.txtfile from the certificate-transparency project and run the following steps with that virtualenv activated.
PYTHONPATHto include the
pythondirectory within the certificate-transparency tools.
PATHto include the
ctauditscts, passing the value of the
CTAuditStoragedirective and, optionally, the path to the log configuration database. The latter will be used to look up log URLs by log id.
The data saved for audit can also be used by other programs; refer to the
ctauditscts source code for details on processing the data.
|Description:||Existing directory where data for off-line audit will be stored|
CTAuditStorage directive sets the name of a
directory where data will be stored for off-line audit. If directory
is not absolute then it is assumed to be relative to
If this directive is not specified, data will not be stored for off-line audit.
The directory will contain files named
active child processes and files named
PID.out for exited
child processes. These
.out files are ready for off-line audit.
The experimental command
ctauditscts (in the httpd source tree, not
currently installed) interfaces with certificate-transparency tools to
perform the audit.
|Description:||Location of certificate-transparency log client tool|
executable is the full path to the log client tool, which is
ct.exe) within the
source tree of the
certificate-transparency open source project.
An alternative implementation could be used to retrieve SCTs for a server certificate as long as the command-line interface is equivalent.
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.
|Description:||Log configuration database supporting dynamic updates|
CTLogConfigDB directive sets the name of a database
containing configuration about known logs. If filename is not absolute
then it is assumed to be relative to
Refer to the documentation for the
which manages the database.
|Description:||Maximum age of SCT obtained from a log, before it will be refreshed|
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.
|Description:||Level of CT awareness and enforcement for a proxy|
|Context:||server config, virtual host|
This directive controls awareness and checks for valid SCTs for a proxy. Several options are available:
|Description:||Existing directory where SCTs are managed|
CTSCTStorage directive sets the name of a
directory where SCTs and SCT lists will be stored. If directory
is not absolute then it is assumed to be relative to
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.
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.
|Description:||Limit on number of SCTs that can be returned in ServerHello|
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.
Typically only a few SCTs would be available, so this directive is only needed in special circumstances.
The directive does not take into account SCTs which may be provided in certificate extensions or in stapled OCSP responses.
|Description:||Static configuration of information about a log|
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
Each of the six fields must be specified, but usually only a small amount of information must be configured for each log; use - 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.
The fields are defined as follows:
-for one of the timestamps if it is unknown. For example, when configuring the minimum valid timestamp for a log which remains valid, specify
|Description:||Static configuration of one or more SCTs for a server certificate|
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.
certificate-pem-file refers to the server certificate in PEM
format. If the name is not absolute, then it is assumed to be relative to
sct-directory should contain one or more files with extension
.sct, representing one or more SCTs corresponding to the
server certificate. If sct-directory is not absolute, then it is
assumed to be relative to
If sct-directory is empty, no error will be raised.
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 .sct