Bring introductory documentation up to speed

1 files changed, 67 insertions, 80 deletions

diff --git a/README.md b/README.md
index 957fb9e..c554374 100644
--- a/README.md
+++ b/README.md
@@ -1,64 +1,75 @@
 # silent-ct
 
-An implementation of a silent Certificate Transparency (CT) monitor.
+An implementation of a silent Certificate Transparency monitor.
 
-**Status:** work in progress, please do not use for anything serious.
-
-FIXME: update readme based on latest revision.
+**Status:** drafty prototype, 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.
+A monitor downloads all certificates from Certificate Transparency logs.  This
+gives a concise view of which certificates have been issued for what domains.
+
+The monitor is configured to pull legitimately issued certificates from trusted
+nodes.  Each node packages its legitimate certificates as a single submission.
+This submission is then made available for download on a URL via HTTP GET.
+
+To convince the monitor that a submission was generated by a trusted node, a
+shared secret is established between the node and the monitor.  The node creates
+a message authentication code using the shared secret.  The monitor verifies it.
+
+What makes this setup _silent_ is the fact that the monitor can compute the
+difference between any discovered and legitimately issued certificates.  If a
+certificate is found that no node submitted, only then is an alert printed.
+
+## Quick start
+
+FIXME: the go install commands will not work until `rgdd.se` is configured
+properly.  Checkout the repository and go install from within the clone.
 
-An overview is shown in the figure below.
+### Setup a node
 
-    XXX: ASCII figure.
+You will need the `silent-ctnode` tool to create submissions that the monitor
+can pull.  Install:
 
-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.
+    $ go install rgdd.se/silent-ct/cmd/silent-ctnode@latest
 
-On a single-node system, the secure channel can be replaced by a UNIX socket.
+Locate the node's certificates that are still valid (i.e., not expired) and
+prepare a submission for them:
 
-## Setting and threat model
+    $ silent-ctnode -n NAME -s SECRET /path/to/chain-1.pem /path/to/chain-2.pem ...
 
-  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.
+`NAME` is an arbitrary name of the node.
 
-## Install
+`SECRET` is a secret that will only be shared with the monitor.
 
-Install the `silent-ct` software using Go's toolchain:
+The output includes the node name, the computed message authentication code, and
+the list of certificate chains that was specified.  Use the `-o` option if you
+prefer to save the output directly to a file rather than getting it on stdout.
 
-    $ go install rgdd.se/silent-ct@latest
+Make the generated submission file available on a URL.  Typically each node
+already serves web content, in which case you can copy it into some directory.
 
-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.
+Finally, ensure that anytime the node requests a new certificate to be issued,
+then a new submission is generated that replaces or extends the previous one.
+For example, if `certbot` is run by `cron`, then that is a good place to hook.
 
-## Configure the monitor
+Repeat this setup if there are multiple nodes.
 
-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.
+### Setup the monitor
 
-    $ cat config
+Install on the system that will run the monitor:
+
+    $ go install rgdd.se/silent-ct/cmd/silent-ctmoon@latest
+
+Create a monitor policy file in JSON format.  Below is an example that looks for
+all certificates related to `example.org`, expect for certificates that are
+associated with `test.example.org`.  You need at least one wildcard to match on.
+
+    $ cat policy.json
     {
       "monitor": [
         {
+          "bootstrap_at": "2024-01-01T00:00:00Z",
           "wildcard": "example.org",
           "excludes": [
             "test"
@@ -69,6 +80,7 @@ You will also need to specify which domains the monitor should be looking for.
         {
           "name": "NODE_NAME",
           "secret": "NODE_SECRET",
+          "url": "SUBMISSION_URL",
           "issues": [
             "example.org",
             "www.example.org"
@@ -77,55 +89,30 @@ You will also need to specify which domains the monitor should be looking for.
       ]
     }
 
-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.
+The `excludes` keyword is optional.  The `bootstrap_at` keyword is required, and
+should be set to the current time of adding the wildcard for monitoring.  Any
+certificate that expired before the specified bootstrap time will be ignored.
 
-`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`.
+Populate the list of nodes based on the names, secrets, and URLs selected during
+your setup.  Also add the domains each node is allowed to put into certificates.
 
-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.
+Bootstrap the monitor in a non-existent directory:
 
-## Read monitoring alerts
+    $ silent-ctmoon --bootstrap -f policy.json -d /path/to/directory -v INFO
+    ...
 
-All output is formatted as follows:
+Leave the monitor running:
 
-    <keyword>: <description>
+    $ silent-ctmoon -f policy.json -d /path/to/directory
 
-Only two keywords are expected by default: `fatal` and `alert`.
+Any noteworthy events (like a potentially mis-issued certificate that no node
+submitted) will be printed on stdout.  If you prefer to get the monitor's output
+in a file, use the `-o` option.   Please note that it is your job to watch the
+output, and/or to hook it up to a notification system like email or similar.
 
-`fatal`: fatal errors were encountered, `silent-ct` is no longer running.
+### Further documentation
 
-`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.
+  - A lengthier [introduction](./docs/introduction.md) to the overall design
 
 ## Contact