# silent-ct

An implementation of a silent Certificate Transparency (CT) monitor.

**Status:** work in progress, please do not use for anything serious.

## How it works

Each node that issues TLS certificates submit them to a self-hosted monitor.
This is what makes it possible for silent-ct to be _silent_: alerts are only
generated if a certificate found in the logs were not requested by the nodes.

An overview is shown in the figure below.

    XXX: ASCII figure.

Each node establishes a secure channel to the monitor.  Secure means end-to-end
encrypted communication where the node can authenticate the monitor.  For the
monitor to authenticate each connecting node, HTTP Basic Authentication is used.

On a single-node system, the secure channel can be replaced by a UNIX socket.

## Setting and threat model

  1. Mis-issued certificates will only be used for MitM attacks against users
     that connect from a set of fixed IP addresses.  It is assumed that the
     party who can detect certificate mis-issuance will never be targeted.  This
     is why each node needs to establish a secure channel with the monitor.
  2. The nodes issuing TLS certificates start in good states but may be
     compromised sometime in the future.  Detection of certificate mis-issuance
     is then out of scope for all domains that the compromised node issued
     certificates for.  It is in-scope to not let such a compromise affect
     detection of mis-issued certificates for other nodes' domains though.
  3. The platform running the monitor is not compromised by the attacker.
  4. An administrator notices alerts that the monitor outputs on stdout.  The
     integration with email, dashboards, or similar is out of scope.
  5. It is not always possible for nodes to reach the monitor.  For example, the
     monitor may be running on a workstation only powered on during work hours.

## Install

Install the `silent-ct` software using Go's toolchain:

    $ go install rgdd.se/silent-ct@latest

If the monitor is not running on the same system as a single node, it is up to
you to configure an end-to-end encrypted channel where the monitor is
authenticated.  The remainder of this README assumed use of a Tor onion service.
Note that the monitor will then punch any NAT and thus run without a public IP.

## Configure the monitor

Create a configuration file specifying which nodes can issue what certificates.
You will also need to specify which domains the monitor should be looking for.

    $ cat config
    {
      "monitor": [
        {
          "wildcard": "example.org",
          "excludes": [
            "test"
          ]
        }
      ],
      "nodes": [
        {
          "name": "NODE_NAME",
          "secret": "NODE_SECRET",
          "issues": [
            "example.org",
            "www.example.org"
          ]
        }
      ]
    }

Here, the monitor is looking for `example.com` and all its subdomains expect for
anything relating to `test.example.com`.  There is a single node that is allowed
to issue certificates with the domain names `example.org` and `www.example.org`.

## Start the monitor

[Setup an onion service][] that routes through the below UNIX socket.

Start the monitor:

    $ mkdir state
    $ silent-ctmoon -c config.json -s state -l silent-ctmoon.sock

The intended way to exit is by sending the SIGINT or SIGTERM signals.

[Setup an onion service]: xxx

## Node setup

What makes `silent-ct` _silent_ is that all nodes report legitimately issued
certificates over a secure channel.  For each such legitimate certificate, run:

    $ torify curl ...

`NODE_NAME` is an arbitrary node name used for authentication.

`NODE_SECRET` is an arbitrary node secret used for authentication.

`ONION_ADDR` is the onion address where `silent-ct` listens for requests.

`CHAIN_PATH` is the path to a certificate chain that was issued legitimately.
It is safe to repeatedly submit the same certificate chain to `silent-ctmoon`.

You will need to add a cron job (or similar) that periodically submits the
issued certificates to `silent-ct`.  See example that works for `certbot`
issuing certificates with Let's Encrypt in the [contrib/](./contrib) directory.

## Read monitoring alerts

All output is formatted as follows:

    <keyword>: <description>

Only two keywords are expected by default: `fatal` and `alert`.

`fatal`: fatal errors were encountered, `silent-ct` is no longer running.

`alert`: something that you want to know about has happened, such as a
certificate appearing in the logs that none of the trusted nodes submitted.

## Contact

  - Room `#certificate-transparency` at OFTC.net
  - Room `#certificate-transparency` at matrix.org