From 62f94ac6a1404834ac6f0723ef57e25fcd5e67f9 Mon Sep 17 00:00:00 2001
From: Rasmus Dahlberg <rasmus@rgdd.se>
Date: Sat, 1 Jun 2024 15:35:45 +0200
Subject: Improve terminology and documentation
---
docs/design.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++
docs/feedback.md | 23 ++++++++++++
docs/introduction.md | 103 ---------------------------------------------------
docs/storage.md | 3 --
docs/submission.md | 22 -----------
5 files changed, 123 insertions(+), 128 deletions(-)
create mode 100644 docs/design.md
create mode 100644 docs/feedback.md
delete mode 100644 docs/introduction.md
delete mode 100644 docs/storage.md
delete mode 100644 docs/submission.md
(limited to 'docs')
diff --git a/docs/design.md b/docs/design.md
new file mode 100644
index 0000000..83f2b59
--- /dev/null
+++ b/docs/design.md
@@ -0,0 +1,100 @@
+# silentct
+
+This document introduces a silent Certificate Transparency monitor design.
+
+## Setting
+
+We consider a setting where one or more trusted systems request certificates for
+a list of domains. The domains that a system request certificates for may
+overlap with the domains of other systems. For example, there may be two
+distinct systems that host and request certificates for `www.example.org`.
+Other examples of "systems" that request certificates could include
+`jitsi.example.org`, `etherpad.example.org` and `gitlab.example.org`.
+
+The threat we are worried about is certificate mis-issuance. Due to considering
+a multi-system setting with overlapping domains, no single system can be aware
+of all legitimately issued certificates for the domains that are being managed.
+
+A certificate is considered mis-issued if it contains:
+
+ 1. at least one domain that any of the trusted systems manage _but without any
+ of the trusted systems requesting that certificate to be issued_, or
+ 2. at least one subdomain of the domains that any of the trusted systems
+ 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. It is however out of scope to
+detect certificate mis-issuance that happened in the past. In other words, if
+the design described herein is put into operation at time `T`, then any
+certificate mis-issuance that happened before time `T` is out of scope. This is
+an important constraint that makes it _a lot less costly_ to bootstrap the
+monitor. For example, old certificate backlogs can simply be ignored.
+
+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 detect certificate mis-issuance, we want to construct a monitor that:
+
+ 1. _is easy to self-host_, because you trust yourself or can then (more
+ easily) find someone you trust to do the monitoring on your behalf, and
+ 2. _is silent_, so that there is little or no noise unless certificate
+ mis-issuance is actually suspected. In other words, there should not be a
+ notification every time a legitimate certificate is issued or renewed.
+
+The "silent" property helps a lot for system administrators that manage more
+than a few certificates. It also helps in the third-party monitoring setting,
+as it would not be more noisy to subscribe to notifications from >1 monitor.
+
+## 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 while verifying that they are locally consistent.
+ - The systems 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 systems managed.
+ - A mis-issued certificate will only be used to target connections from a
+ fixed set of IP addresses. A 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.
+
+(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 "silent" property, the monitor pulls the trusted systems for
+legitimately issued certificates via HTTP GET. Alternatively, the monitor can
+read a local file in case it is co-located with a single trusted system. The
+monitor uses this as [feedback](./feedback.md) to filter the downloaded
+certificates that matched. If a certificate is found that none of the trusted
+systems made available, only then is an alert emitted (NOTICE level output).
+
+The communication channel between the trusted systems 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 shared secret is used for each system 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 files that a system 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 file twice.
+Blocking can not be solved by cryptography and would simply result in alerts.
diff --git a/docs/feedback.md b/docs/feedback.md
new file mode 100644
index 0000000..d79d57f
--- /dev/null
+++ b/docs/feedback.md
@@ -0,0 +1,23 @@
+# Feedback
+
+This document describes the integrity-protected file format that a trusted
+system uses when making legitimately issued certificates available to a monitor.
+
+## Format
+
+ NAME MAC
+ <CERTIFICATE CHAIN>
+ ...
+ <CERTIFICATE CHAIN>
+
+`NAME`: identifier that the monitor uses to locate the shared secret.
+
+`MAC`: HMAC with SHA256 as the hash function, computed for line two and forward.
+The shared HMAC key is derived as follows by the trusted system and the monitor:
+
+ hkdf := hkdf.New(sha256.New, SECRET, []byte("silentct"), NAME)
+ key := make([]byte, 16)
+ io.ReadFull(hkdf, key)
+
+`<CERTIFICATE CHAIN>`: certificate chain in PEM format that the trusted system
+considers legitimate. Can be repeated, then delimited by "silentct:separator".
diff --git a/docs/introduction.md b/docs/introduction.md
deleted file mode 100644
index 0aab2cc..0000000
--- a/docs/introduction.md
+++ /dev/null
@@ -1,103 +0,0 @@
-# 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.
-
-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 while verifying 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 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.
-
-(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 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 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 reading
-
-docdoc
-
-## 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
diff --git a/docs/storage.md b/docs/storage.md
deleted file mode 100644
index a0616ed..0000000
--- a/docs/storage.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Storage
-
-docdoc
diff --git a/docs/submission.md b/docs/submission.md
deleted file mode 100644
index 1d9c189..0000000
--- a/docs/submission.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Submission
-
-docdoc
-
-## Format
-
- NAME MAC
- <PEM CHAIN>
- silentct:separator
- ...
- <PEM CHAIN>
-
-`NAME`: identifier that the monitor uses to locate the right secret.
-
-`MAC`: HMAC with SHA256 as the hash function, computed for line two and forward.
-The HMAC key is derived by the node and the monitor from their shared secret:
-
- hkdf := hkdf.New(sha256.New, SECRET, []byte("silentct"), NAME)
- key := make([]byte, 16)
- io.ReadFull(hkdf, key)
-
-`<PEM CHAIN>`: certificate chain in PEM format the node considers legitimate.
--
cgit v1.2.3