From 7ed8da474f697ddc0009a7f27a52be9a993753eb Mon Sep 17 00:00:00 2001 From: Jeff Trawick Date: Tue, 22 Apr 2014 15:02:54 +0000 Subject: [PATCH] more Certificate Transparency docs git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1589154 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_ssl_ct.xml | 217 +++++++++++++++++++++++++-- docs/manual/programs/ctlogconfig.xml | 17 ++- 2 files changed, 211 insertions(+), 23 deletions(-) diff --git a/docs/manual/mod/mod_ssl_ct.xml b/docs/manual/mod/mod_ssl_ct.xml index 2d1d42653f..825a38abe9 100644 --- a/docs/manual/mod/mod_ssl_ct.xml +++ b/docs/manual/mod/mod_ssl_ct.xml @@ -30,6 +30,7 @@ ssl_ct_module +

This module provides an implementation of Certificate Transparency, in conjunction with mod_ssl and command-line tools from the certificate-transparency @@ -46,21 +47,197 @@ servers and proxies:

  • 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).
    • -
  • SCTs can be received by the proxy from backend servers in the ServerHello, +
  • 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.
    • -
  • The proxy can be configured to disallow communication with a backend - which does not provide an SCT which passes on-line validation.
    • +
  • The proxy can be configured to disallow communication with an origin + server which does not provide an SCT which passes on-line validation.

    • Configuration information about logs can be defined statically in the web -server configuration or maintained in a Sqlite3 database. In the latter case, +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) 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.

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

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

    + +
    + +
    + 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.
    + +
    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 and the + ctlogconfig command for more specific information.

    + +
    + +
    + Logging CT status in the access log + +

    Both proxy and server modes set the SSL_CT_PEER_STATUS + variable to indicate if the peer is CT-aware.

    + +

    Proxy mode sets the SSL_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.

    +
    + +
    + Off-line audit for proxy + +

    Experimental support for this is implemented in the ctauditscts + command (in the httpd source tree, not currently installed), 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. + However, verify_single_proof.py is not complete currently and does + not provide a way to identify audit failures.

    + +

    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.

    +
    + CTAuditStorage Existing directory where data for off-line audit will be stored @@ -161,11 +338,11 @@ refreshed
    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 backend server does + proxy will not disallow communication if the origin server does not provide any valid SCTs.
    require
    -
    The proxy will abort communication with the backend server if it +
    The proxy will abort communication with the origin server if it does not provide at least one SCT which passes on-line validation.
    @@ -240,16 +417,13 @@ ServerHello
    log-id
    -
    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.
    +
    This is the id of the log, which is the SHA-256 hash of the log's + public key.
    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. The public key is - required in order to check the signature of SCTs received by the proxy.
    + to ServerRoot.
    trust
    This is a generic trust flag. Set this field to 0 to @@ -265,10 +439,13 @@ ServerHello
    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. Each server certificate - will be submitted to all logs for which log-URL is configured.
    + and in turn obtaining an SCT to be sent to clients.
    + +Log configuration contains more general information +about the fields which can be configured with this directive. +     @@ -283,16 +460,24 @@ ServerHello

    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.

    + 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 must contain one or more files with extension +

    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

         diff --git a/docs/manual/programs/ctlogconfig.xml b/docs/manual/programs/ctlogconfig.xml index c3ffa1886c..55fae21a4f 100644 --- a/docs/manual/programs/ctlogconfig.xml +++ b/docs/manual/programs/ctlogconfig.xml @@ -29,6 +29,9 @@

    ctlogconfig is a tool for maintaining a log configuration database, for use with mod_ssl_ct.

    +

    Refer first to Log + configuration in the mod_ssl_ct documentation.

    +

    Refer to the examples below for typical use.

    @@ -37,39 +40,39 @@
    Synopsis

    - ctlogconfig db-path dump + ctlogconfig /path/to/db dump

    - ctlogconfig db-path configure-public-key + ctlogconfig /path/to/db configure-public-key [ log-id|record-id ] /path/to/public-key.pem

    - ctlogconfig db-path configure-url + ctlogconfig /path/to/db configure-url [ log-id|record-id ] log-URL

    - ctlogconfig db-path valid-time-range + ctlogconfig /path/to/db valid-time-range log-id|record-id min-timestamp max-timestamp

    - ctlogconfig db-path trust + ctlogconfig /path/to/db trust log-id|record-id

    - ctlogconfig db-path distrust + ctlogconfig /path/to/db distrust log-id|record-id

    - ctlogconfig db-path forget + ctlogconfig /path/to/db forget log-id|record-id

    -- 2.50.1