<-
Apache > HTTP Server > Documentation > Version 2.5 > Modules

Apache Module mod_ssl_ct

Description: Implementation of Certificate Transparency (RFC 6962)
Status: Extension
Module Identifier: ssl_ct_module
Source File: mod_ssl_ct.c

Summary

This module provides an implementation of Certificate Transparency, in conjunction with mod_ssl and command-line tools from the certificate-transparency 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 http://www.certificate-transparency.org/. Key terminology used in this documentation:

Certificate log
A certificate log, referred to simply as log 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.
Signed Certificate Timestamp (SCT)
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.

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.

This module is experimental for the following reasons:
  • Insufficient test and review
  • Reliance on an unreleased version of OpenSSL (1.0.2, Beta 3 or later) for basic operation
  • Incomplete off-line audit capability

Configuration mechanisms, format of data saved for off-line audit, and other characteristics are subject to change based on further feedback and testing.

Topics

Directives

Bugfix checklist

See also

top

Server processing overview

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 CTServerHelloSCTLimit directive.

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.

top

Proxy processing overview

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 require.

Additionally, the server certificate chain and SCTs are stored for off-line verification if the CTAuditStorage 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.

top

Log configuration

Servers and proxies use different information about logs for their processing. This log configuration can be set in two ways:

The information that can be configured about a log using either mechanism is described below:

log id
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.
public key of the log
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.
A server must have the public key of the log in order to submit certificates to it.
general trust/distrust setting
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).
minimum and/or maximum valid timestamps
When configured, the proxy will check that timestamps from SCTs are within the valid range.
log URL
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.
The log URL is also needed by off-line auditing of SCTs received by a proxy.

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.

top

Storing SCTs in a form consumable by mod_ssl_ct

mod_ssl_ct allows you to configure SCTs statically using the 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 write-sct.py

top

Logging CT status in the access log

Proxy and server modes set the SSL_CT_PROXY_STATUS and 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 extension, etc.).

These variables can be logged with the %{varname}e format of mod_log_config.

top

Off-line audit for proxy

Experimental support for this is implemented in the ctauditscts command, which itself relies on the verify_single_proof.py tool in the certificate-transparency open source project. ctauditscts can parse data for off-line audit (enabled with the CTAuditStorage directive) and invoke verify_single_proof.py.

Here are rough notes for using ctauditscts:

The data saved for audit can also be used by other programs; refer to the ctauditscts source code for details on processing the data.

top

CTAuditStorage Directive

Description: Existing directory where data for off-line audit will be stored
Syntax: CTAuditStorage directory
Default: none
Context: server config
Status: Extension
Module: mod_ssl_ct

The 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 DefaultRuntimeDir.

If this directive is not specified, data will not be stored for off-line audit.

The directory will contain files named PID.tmp for 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.

top

CTLogClient Directive

Description: Location of certificate-transparency log client tool
Syntax: CTLogClient executable
Default: none
Context: server config
Status: Extension
Module: mod_ssl_ct

executable is the full path to the log client tool, which is normally file cpp/client/ct (or 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.

top

CTLogConfigDB Directive

Description: Log configuration database supporting dynamic updates
Syntax: CTLogConfigDB filename
Default: none
Context: server config
Status: Extension
Module: mod_ssl_ct

The 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 ServerRoot.

Refer to the documentation for the ctlogconfig program, which manages the database.

top

CTMaxSCTAge Directive

Description: Maximum age of SCT obtained from a log, before it will be refreshed
Syntax: CTMaxSCTAge num-seconds
Default: 1 day
Context: server config
Status: Extension
Module: mod_ssl_ct

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.

top

CTProxyAwareness Directive

Description: Level of CT awareness and enforcement for a proxy
Syntax: CTProxyAwareness oblivious|aware|require
Default: aware
Context: server config, virtual host
Status: Extension
Module: mod_ssl_ct

This directive controls awareness and checks for valid SCTs for a proxy. Several options are available:

oblivious
The proxy will neither ask for nor examine SCTs. Certificate Transparency processing for the proxy is completely disabled.
aware
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.
require
The proxy will abort communication with the origin server if it does not provide at least one SCT which passes on-line validation.
top

CTSCTStorage Directive

Description: Existing directory where SCTs are managed
Syntax: CTSCTStorage directory
Default: none
Context: server config
Status: Extension
Module: mod_ssl_ct

The 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 DefaultRuntimeDir.

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.

top

CTServerHelloSCTLimit Directive

Description: Limit on number of SCTs that can be returned in ServerHello
Syntax: CTServerHelloSCTLimit limit
Default: 100
Context: server config
Status: Extension
Module: mod_ssl_ct

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.

top

CTStaticLogConfig Directive

Description: Static configuration of information about a log
Syntax: CTStaticLogConfig log-id|- public-key-file|- 1|0|- min-timestamp|- max-timestamp|- log-URL|-
Default: none
Context: server config
Status: Extension
Module: mod_ssl_ct

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 CTLogConfigDB directive.

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:

log-id
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.
This field should be omitted when public-key-file is provided.
public-key-file
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 ServerRoot.
trust/distrust
Set this field to 1 to distrust this log, or to otherwise avoid using it for server certificate submission. Set this to - or 0 (the default) to treat the log normally.
min-timestamp and max-timestamp
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.
Specify - for one of the timestamps if it is unknown. For example, when configuring the minimum valid timestamp for a log which remains valid, specify - for max-timestamp.
SCTs received from this log by the proxy are invalid if the timestamp is older than min-timestamp or newer than max-timestamp.
log-URL
This is the URL of the log, for use in submitting server certificates and in turn obtaining an SCT to be sent to clients.

See also

top

CTStaticSCTs Directive

Description: Static configuration of one or more SCTs for a server certificate
Syntax: CTStaticSCTs certificate-pem-file sct-directory
Default: none
Context: server config
Status: Extension
Module: mod_ssl_ct

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 ServerRoot.

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 ServerRoot.

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

top