Update design and write a brief introduction

Credit: much good input from Filippo Valsorda in the cleaned up version
of this design draft, e.g., including use of HMAC and that there may be
dragons wrt. to any potential filtering on the NotBefore timestamp.

1 files changed, 119 insertions, 0 deletions

diff --git a/docs/introduction.md b/docs/introduction.md
new file mode 100644
index 0000000..f10c269
--- /dev/null
+++ b/docs/introduction.md
@@ -0,0 +1,119 @@
+# Silent Certificate Transparency
+
+This document introduces a silent Certificate Transparency monitor design.
+
+## Setting
+
+We consider a setting where one or more trusted _nodes_ request certificates for
+a specified list of domain names.  The domain names that a node requests
+certificates for may overlap with the domain names of other nodes.  For example,
+there may be two distinct nodes that request certificates for a given domain.
+
+    TODO: Add figure.
+    Figure 1: A few examples of how trusted nodes may be deployed.
+
+The threat we are worried about is certificate mis-issuance.  Due to considering
+a multi-node setting with overlapping domain names, no single node can be aware
+of all legitimately issued certificates for the domain names that it manages.
+
+A certificate is considered mis-issued if it contains:
+
+  1. at least one domain name that any of the trusted nodes manage _but without
+     any of the trusted nodes requesting that certificate to be issued_, or
+  2. at least one subdomain of the domain names that any of the trusted nodes
+     manage _unless that subdomain is explicitly specified as out of scope_.
+
+The cause of certificate mis-issuance can vary, ranging from BGP and DNS hijacks
+to certificate authorities that are coerced, compromised, or actively malicious.
+
+## Goals and non-scope
+
+The goal is to detect certificate mis-issuance, not to prevent it.  It is out of
+scope to detect certificate mis-issuance that happened in the past.  In other
+words, if the architecture described herein is put into operation at time `T`,
+then any certificate mis-issuance that happened before time `T` is out of scope.
+
+It is also out of scope to detect certificate mis-issuance that targets web
+browsers without Certificate Transparency enforcement.  This is because we
+cannot get a concise view of all certificates without Certificate Transparency.
+
+To achieve the goal of certificate mis-issuance, we want a _monitor_ that:
+
+  1. _is easy to self-host_, because you trust yourself or can then find someone
+     else that is appropriate and willing to host your infrastructure, and
+  2. _is silent_, so that there is little or no noise unless certificate
+     mis-issuance is suspected or other noteworthy log events are happening.
+
+## Assumptions
+
+  - The attacker is unable to control two independent logs that count towards
+    the SCT checks in web browsers.  So, we need not worry about split-views and
+    can just download the logs and verify that they are locally consistent.
+  - The nodes that request 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 nodes managed.
+  - A mis-issued certificate will only be used to target connections from a
+    fixed set of fixed IP addresses.  Any party that can distinguish between
+    certificates that are legitimate and mis-issued will never be targeted.
+  - A domain owner notices alerts about suspected certificate mis-issuance.  The
+    monitor that generates these alerts is trusted and never compromised.
+
+## Architecture
+
+A monitor downloads all certificates that are issued by certificate authorities
+from Certificate Transparency logs.  The exact logs to download is automatically
+updated using a list that Google publishes in signed form.  All historical
+updates to the list of logs is stored locally in case any issues are suspected.
+
+To filter out certificates that are not relevant, the monitor is configured with
+a list of domains to match on.  Only matching certificates will be stored, which
+means there are nearly no storage requirements to run this type of monitor.
+
+To achieve the property of _silence_, the trusted nodes push legitimately issued
+certificates to the monitor which listens for such requests using an HTTP API.
+The monitor will use the feedback from these nodes to further filter the
+downloaded certificates that matched based on which ones are legitimate.  If any
+certificates are found that no node pushed to the monitor, an alert is created.
+
+The communication channel between the trusted nodes and the monitor can be
+tampered with.  For example, it may be plain HTTP or an HTTPS connection that
+the attacker trivially hijacks by obtaining yet another mis-issued certificate.
+Owning that the communication channel is insecure helps avoid misconfiguration.
+
+A pre-shared secret is used for each node to authenticate with the monitor.
+That secret is never shown on the wire (an HMAC key is derived from it), which
+means that all a man-in-the-middle attacker can do is replay and block messages.
+Accounting for replayed messages is either way a good thing, because it makes it
+easy to overcome temporary issues like a spotty network, a monitor reboot, etc.
+In other words, nodes can periodically (re)submit their legitimate certificates.
+Blocked messages can not be solved by cryptography and will result in alerts.
+
+To keep the attack surface of the monitor down, one may optionally choose to
+operate it as a Tor onion service, restrict access using WireGuard, or similar.
+Or in the case of a single-node deployment, run everything on the same system.
+
+## Open questions
+
+  - What do we do about certificates that appear in the logs after time `T`, but
+    which were issued with a `NotBefore` timestamp that is before time `T`?  We
+    want to minimize noise, but also not open up for CA backdating threats.
+  - What options for generating alerts should be supported other than stdout, if
+    any?  Most deployments already have ways to integrate with dashboards/email.
+
+## Further documentation
+
+  - [HTTP API](./http-api.md): read more about how the trusted nodes
+    authenticate with the monitor to submit legitimately issued certificates.
+  - [State directory](./state.md): read more about how the trusted monitor keeps
+    track of its state as plaintext files in a given directory.  Staying away
+    from a database is meant to ease debugging, silencing of alerts, etc.
+
+## Future ideas
+
+  - Reduce the amount of bandwidth that the monitor spends downloading
+    certificates that are either way discarded (non-matches).  This can be
+    achieved by introducing a _verifiable proxy_ supporting wildcard
+    (non-)membership proofs, see [verifiable light-weight monitoring][].  Ignore
+    the parts about changing the logs; that is easily solved by the proxy alone.
+
+[verifiable light-weight monitoring]: https://arxiv.org/pdf/1711.03952.pdf