From e371f2005f91b3db1904b3038c498c764ae15279 Mon Sep 17 00:00:00 2001 From: Rasmus Dahlberg Date: Mon, 8 Jan 2024 08:32:04 +0100 Subject: Bring introductory documentation up to speed --- docs/introduction.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) (limited to 'docs/introduction.md') diff --git a/docs/introduction.md b/docs/introduction.md index b0d7e71..0aab2cc 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -9,9 +9,6 @@ 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. @@ -65,28 +62,33 @@ 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. +(It is possible to get INFO output whenever logs are added and removed. The +default verbosity is however NOTICE, which aims to be as silent as possible.) + 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 get the property of _silence_, the monitor pulls the trusted nodes -periodically (HTTP GET) for legitimately issued certificates. The monitor will -use this feedback to filter the downloaded certificates that matched. If any -certificates are found that no node pushed to the monitor, an alert is created. +To get the property of _silence_, the monitor pulls the trusted nodes via HTTP +GET for legitimately issued certificates (periodic job). The monitor will use +this feedback to filter the downloaded certificates that matched. If any +certificates are found that no node pushed to the monitor, an alert is printed. 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. +A shared secret is used for each node to authenticate with the monitor. This +secret is never shown on the wire: an HMAC key is derived from it, which is used +to produce message authentication codes. All a machine-in-the-middle attacker +can do is replay or block integrity-protected submissions that a node generated. + "Replays" can happen either way because the monitor polls periodically, i.e., the monitor needs to account for the fact that it may poll the same thing twice. Blocking can not be solved by cryptography and would simply result in alerts. -## Further documentation +## Further reading docdoc -- cgit v1.2.3