Add drafty README

Serves as a mock-up of what to implement.

1 files 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:
+
+    <keyword>: <description>
+
+Only two keywords are expected by default: `alert` and `recovered`.
+
+## Contact
+
+  - Room `#certificate-transparency` at OFTC.net
+  - Room `#certificate-transparency` at matrix.org