From f124940f75e1f49100fe5381019d2f65d6915304 Mon Sep 17 00:00:00 2001 From: Rasmus Dahlberg Date: Sat, 2 Dec 2023 20:08:54 +0100 Subject: Add drafty README Serves as a mock-up of what to implement. --- README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 112 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5a27a78..d510068 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,114 @@ # silent-ct -`silent-ct` is an implementation of a silent Certificate Transparency (CT) -monitor. You will not be notified unless certificate mis-issuance is suspected. +An implementation of a silent Certificate Transparency (CT) monitor. + +## 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. + +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. + +For the monitor to authenticate each node, HTTP Basic Authentication is used. + +## 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 + 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. + +## Install + +Install Tor on all platforms. On Debian: + + # apt install tor + +Install the silent-ct software using Go's toolchain: + + $ go install rgdd.se/silent-ct/cmd/silent-ctnode@latest + $ go install rgdd.se/silent-ct/cmd/silent-ctmoon@latest + +`silent-ctnode` is only used on nodes that issue TLS certificates. + +`silent-ctmoon` is only used on the system that runs the monitor. + +## Node setup + +What makes `silent-ctmoon` _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 + +`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. + +`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` +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`. + +## Contact + + - Room `#certificate-transparency` at OFTC.net + - Room `#certificate-transparency` at matrix.org -- cgit v1.2.3