You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by tr...@apache.org on 2014/04/21 23:14:22 UTC
svn commit: r1588987 [1/3] - in /httpd/httpd/trunk: ./ docs/manual/mod/
docs/manual/programs/ modules/ssl/ support/
Author: trawick
Date: Mon Apr 21 21:14:21 2014
New Revision: 1588987
URL: http://svn.apache.org/r1588987
Log:
Add module mod_ssl_ct, which provides an implementation of Certificate
Transparency (RFC 6962) for httpd.
mod_ssl_ct requires OpenSSL 1.0.2 (in beta) and must be explicitly
enabled via configure.
Note that support/ctauditscts is purposefully not installed; it
does not properly function due to a dependency on a
certificate-transparency open source project tool which itself is
not sufficiently complete at this time.
Added:
httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.xml (with props)
httpd/httpd/trunk/docs/manual/programs/ctlogconfig.xml (with props)
httpd/httpd/trunk/modules/ssl/mod_ssl_ct.c
httpd/httpd/trunk/modules/ssl/ssl_ct_log_config.c (with props)
httpd/httpd/trunk/modules/ssl/ssl_ct_log_config.h (with props)
httpd/httpd/trunk/modules/ssl/ssl_ct_sct.c (with props)
httpd/httpd/trunk/modules/ssl/ssl_ct_sct.h (with props)
httpd/httpd/trunk/modules/ssl/ssl_ct_util.c (with props)
httpd/httpd/trunk/modules/ssl/ssl_ct_util.h (with props)
httpd/httpd/trunk/support/ctauditscts (with props)
httpd/httpd/trunk/support/ctlogconfig (with props)
Modified:
httpd/httpd/trunk/CHANGES
httpd/httpd/trunk/modules/ssl/config.m4
httpd/httpd/trunk/support/Makefile.in
Modified: httpd/httpd/trunk/CHANGES
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/CHANGES?rev=1588987&r1=1588986&r2=1588987&view=diff
==============================================================================
--- httpd/httpd/trunk/CHANGES [utf-8] (original)
+++ httpd/httpd/trunk/CHANGES [utf-8] Mon Apr 21 21:14:21 2014
@@ -1,6 +1,9 @@
-*- coding: utf-8 -*-
Changes with Apache 2.5.0
+ *) Add module mod_ssl_ct, which provides an implementation of Certificate
+ Transparency (RFC 6962) for httpd. [Jeff Trawick]
+
*) mod_cache: Fix AH00784 errors on Windows when the the CacheLock directive
is enabled. [Eric Covener]
Added: httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.xml?rev=1588987&view=auto
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.xml (added)
+++ httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.xml Mon Apr 21 21:14:21 2014
@@ -0,0 +1,299 @@
+<?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>.</p>
+
+<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 backend 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 a backend
+ 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>
+</summary>
+
+<directivesynopsis>
+<name>CTAuditStorage</name>
+<description>Existing directory where data for off-line audit will be stored</description>
+<syntax>CTAuditStorage <em>directory</em></syntax>
+<default><em>none</em></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><em>none</em></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>src/client/ct</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>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>CTLogConfigDB</name>
+<description>Log configuration database supporting dynamic updates</description>
+<syntax>CTLogConfigDB <em>filename</em></syntax>
+<default><em>none</em></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><em>1 day</em></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><em>aware</em></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 backend server does
+ not provide any valid SCTs.</dd>
+
+ <dt>require</dt>
+ <dd>The proxy will abort communication with the backend 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><em>none</em></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 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><em>100</em></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><em>none</em></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. The fields are defined as follows:</p>
+
+ <dl>
+ <dt><em>log-id</em></dt>
+ <dd>This is the id of the log. The id is the SHA-256 hash of the log's
+ public key. In some cases it is appropriate and convenient to identify
+ the log by the id (hash), such as when configuring information regarding
+ the log's validity.</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>. The public key is
+ required in order to check the signature of SCTs received by the proxy.</dd>
+
+ <dt><em>trust</em></dt>
+ <dd>This is a generic <q>trust</q> flag. Set this field to <em>0</em> to
+ distrust this log.</dd>
+
+ <dt><em>min-timestamp</em></dt>
+ <dd>SCTs received from this log by the proxy are invalid if the timestamp
+ is older than this value.</dd>
+
+ <dt><em>max-timestamp</em></dt>
+ <dd>SCTs received from this log by the proxy are invalid if the timestamp
+ is newer than this value.</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. Each server certificate
+ will be submitted to all logs for which <em>log-URL</em> is configured.</dd>
+ </dl>
+</usage>
+</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><em>none</em></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.</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> must 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>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>
Propchange: httpd/httpd/trunk/docs/manual/mod/mod_ssl_ct.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: httpd/httpd/trunk/docs/manual/programs/ctlogconfig.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/programs/ctlogconfig.xml?rev=1588987&view=auto
==============================================================================
--- httpd/httpd/trunk/docs/manual/programs/ctlogconfig.xml (added)
+++ httpd/httpd/trunk/docs/manual/programs/ctlogconfig.xml Mon Apr 21 21:14:21 2014
@@ -0,0 +1,165 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.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.
+-->
+
+<manualpage metafile="ctlogconfig.xml.meta">
+<parentdocument href="./">Programs</parentdocument>
+
+<title>ctlogconfig - Certificate Transparency log configuration tool</title>
+
+<summary>
+ <p><code>ctlogconfig</code> is a tool for maintaining a log configuration
+ database, for use with <module>mod_ssl_ct</module>.</p>
+
+ <p>Refer to the <a href="#examples">examples below</a> for typical use.</p>
+
+</summary>
+<seealso><module>mod_ssl_ct</module></seealso>
+
+<section id="synopsis">
+ <title>Synopsis</title>
+ <p><code>
+ <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>dump</strong>
+ </code></p>
+
+ <p><code>
+ <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>configure-public-key</strong>
+ [ <em>log-id</em>|<em>record-id</em> ]
+ <em>/path/to/public-key.pem</em>
+ </code></p>
+
+ <p><code>
+ <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>configure-url</strong>
+ [ <em>log-id</em>|<em>record-id</em> ]
+ <em>log-URL</em>
+ </code></p>
+
+ <p><code>
+ <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>valid-time-range</strong>
+ <em>log-id</em>|<em>record-id</em>
+ <em>min-timestamp</em> <em>max-timestamp</em>
+ </code></p>
+
+ <p><code>
+ <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>trust</strong>
+ <em>log-id</em>|<em>record-id</em>
+ </code></p>
+
+ <p><code>
+ <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>distrust</strong>
+ <em>log-id</em>|<em>record-id</em>
+ </code></p>
+
+ <p><code>
+ <strong>ctlogconfig</strong> <strong>db-path</strong> <strong>forget</strong>
+ <em>log-id</em>|<em>record-id</em>
+ </code></p>
+
+</section>
+
+<section id="subcommands">
+ <title>Sub-commands</title>
+ <dl>
+ <dt>dump</dt>
+ <dd>Display configuration database contents. The record id shown in
+ the output of this sub-command can be used to identify the affected
+ record in other sub-commands.</dd>
+
+ <dt>configure-public-key</dt>
+ <dd>Add a log's public key to the database or set the public key for an
+ existing entry. The log's public key is needed to validate the signature
+ of SCTs received by a proxy from a backend server.</dd>
+
+ <dt>configure-url</dt>
+ <dd>Add a log's URL to the database or set the URL for an existing entry.
+ The log's URL is used when submitting server certificates to logs in
+ order to obtain SCTs to send to clients.</dd>
+
+ <dt>valid-time-range</dt>
+ <dd>Set the minimum valid time and/or the maximum valid time for a log.
+ SCTs from the log with timestamps outside of the valid range will not be
+ accepted. Use <code>-</code> for a time that is not being configured.</dd>
+
+ <dt>trust</dt>
+ <dd>Mark a log as trusted, which is the default setting. This sub-command
+ is used to reverse a <em>distrust</em> setting.</dd>
+
+ <dt>distrust</dt>
+ <dd>Mark a log as distrusted.</dd>
+
+ <dt>forget</dt>
+ <dd>Remove information about a log from the database.</dd>
+ </dl>
+</section>
+
+<section id="examples">
+ <title>Examples</title>
+
+ <p>Consider an Apache httpd instance which serves as a TLS server and a proxy.
+ The TLS server needs to obtain SCTs from a couple of known logs in order to
+ pass those to clients, and the proxy needs to be able to validate the signature
+ of SCTs received from backend servers.</p>
+
+ <p>First we'll configure the URLs for logs where server certificates are logged:</p>
+
+ <example>
+ $ ctlogconfig /path/to/conf/log-config configure-url http://log1.example.com/<br />
+ $ ctlogconfig /path/to/conf/log-config configure-url http://log2.example.com/<br />
+ $ ctlogconfig /path/to/conf/log-config dump<br />
+ Log entry:<br />
+ Record 1<br />
+ Log id : (not configured)<br />
+ Public key file: (not configured)<br />
+ URL : http://log1.example.com/<br />
+ Time range : -INF to +INF<br />
+<br />
+ Log entry:<br />
+ Record 2<br />
+ Log id : (not configured)<br />
+ Public key file: (not configured)<br />
+ URL : http://log2.example.com/<br />
+ Time range : -INF to +INF<br />
+ </example>
+
+ <p>Next we'll set the public key of a log where the certificate of our only
+ backend server is published. In this case it is the log with URL
+ http://log2.example.com/ which has already been configured.</p>
+
+ <example>
+ $ ctlogconfig /path/to/conf/log-config configure-public-key \\#2 /path/to/conf/log2-pub.pem<br />
+ $ ctlogconfig /path/to/conf/log-config dump<br />
+ Log entry:<br />
+ Record 1<br />
+ Log id : (not configured)<br />
+ Public key file: (not configured)<br />
+ URL : http://log1.example.com/<br />
+ Time range : -INF to +INF<br />
+<br />
+ Log entry:<br />
+ Record 2<br />
+ Log id : (not configured)<br />
+ Public key file: /path/to/conf/log2-pub.pem<br />
+ URL : http://log2.example.com/<br />
+ Time range : -INF to +INF<br />
+ </example>
+</section>
+
+</manualpage>
Propchange: httpd/httpd/trunk/docs/manual/programs/ctlogconfig.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: httpd/httpd/trunk/modules/ssl/config.m4
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/modules/ssl/config.m4?rev=1588987&r1=1588986&r2=1588987&view=diff
==============================================================================
--- httpd/httpd/trunk/modules/ssl/config.m4 (original)
+++ httpd/httpd/trunk/modules/ssl/config.m4 Mon Apr 21 21:14:21 2014
@@ -52,6 +52,14 @@ APACHE_MODULE(ssl, [SSL/TLS support (mod
# Ensure that other modules can pick up mod_ssl.h
APR_ADDTO(INCLUDES, [-I\$(top_srcdir)/$modpath_current])
+ssl_ct_objs="mod_ssl_ct.lo ssl_ct_log_config.lo ssl_ct_sct.lo ssl_ct_util.lo"
+APACHE_MODULE(ssl_ct, [Support for Certificate Transparency (RFC 6962)], $ssl_ct_objs, , no, [
+ dnl TODO: Check for OpenSSL >= 1.0.2
+ if test "$enable_ssl" = "no"; then
+ AC_MSG_ERROR([mod_ssl_ct is dependent on mod_ssl, which is not enabled.])
+ fi
+])
+
dnl # end of module specific part
APACHE_MODPATH_FINISH