From 895d5fea41177e444c18f4fdc820fffa5f67d5bf Mon Sep 17 00:00:00 2001 From: Rasmus Dahlberg Date: Sat, 9 Dec 2023 17:08:45 +0100 Subject: Add drafty skeleton --- README.md | 131 +++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 74 insertions(+), 57 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d510068..44b2da0 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ 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. @@ -12,101 +14,116 @@ An overview is shown in the figure below. XXX: ASCII figure. -To establish a secure connection to the monitor, a Tor onion service is assumed. -This means that all nodes and the monitor need to have Tor installed locally. - -The use of a Tor onion service also allows for NAT punching. In other words, it -is possible to run the monitor without a publicly reachable IP address. +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. -For the monitor to authenticate each 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. 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. - 2. An administrator notices alerts that `silent-ctmoon` outputs on stdout. - The integration with email, dashboards, or similar is out of scope. - 3. The platform running the monitor is not compromised by the attacker. - 4. The platforms hosting TLS sites start in good states but may be compromised - by the attacker sometime in the future. Detection of certificate - mis-issuance is then out of scope for the domains the compromised node - issued certificates for. It is in-scope to not let such a compromise - affect detection of mis-issued certificates with other nodes' domains. - 5. Mis-issued certificates will only be used for MitM attacks against users + 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 Tor on all platforms. On Debian: +Install the `silent-ct` software using Go's toolchain: - # apt install tor + $ go install rgdd.se/silent-ct@latest -Install the silent-ct software using Go's toolchain: +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. - $ go install rgdd.se/silent-ct/cmd/silent-ctnode@latest - $ go install rgdd.se/silent-ct/cmd/silent-ctmoon@latest +## Configure the monitor -`silent-ctnode` is only used on nodes that issue TLS certificates. +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. -`silent-ctmoon` is only used on the system that runs the monitor. + $ 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-ctmoon` _silent_ is that all nodes report legitimately issued +What makes `silent-ct` _silent_ is that all nodes report legitimately issued certificates over a secure channel. For each such legitimate certificate, run: - $ torify silent-ctnode -n NODE_NAME -s NODE_SECRET -o ONION_ADDR -c CHAIN_PATH + $ 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-ctmoon` listens for requests. +`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-ctmoon`. See example that works for `certbot` +issued certificates to `silent-ct`. See example that works for `certbot` issuing certificates with Let's Encrypt in the [contrib/](./contrib) directory. -## Configure the monitor - -Create a configuration file specifying which nodes can issue what certificates. - -Example: - - $ cat config - NODE_A aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa example.org www.example.org - NODE_B bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb git.example.org - -The first column specifies an arbitrary node name. - -The second column specifies a node secret used for mutual authentication. - -The following columns specify domain names the node issues certificates for. - -## Start the monitor - -[Configure an onion service][] that routes through the below UNIX socket. - -Start the monitor: - - $ silent-ctmoon -c config -s state.db -l silent-ctmoon.sock - -Stop gracefully by sending the SIGINT signal. - -[Configure an onion service]: xxx - ## Read monitoring alerts All output is formatted as follows: : -Only two keywords are expected by default: `alert` and `recovered`. +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 -- cgit v1.2.3