Add drafty skeleton

1 files changed, 74 insertions, 57 deletions

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:
 
     <keyword>: <description>
 
-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