1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
# silent-ct
An implementation of a silent Certificate Transparency (CT) monitor.
**Status:** work in progress, please do not use for anything serious.
FIXME: update readme based on latest revision.
## 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.
An overview is shown in the figure below.
XXX: ASCII figure.
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.
On a single-node system, the secure channel can be replaced by a UNIX socket.
## Setting and threat model
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 the `silent-ct` software using Go's toolchain:
$ go install rgdd.se/silent-ct@latest
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.
## Configure the monitor
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.
$ 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-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.
`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-ct`. See example that works for `certbot`
issuing certificates with Let's Encrypt in the [contrib/](./contrib) directory.
## Read monitoring alerts
All output is formatted as follows:
<keyword>: <description>
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
- Room `#certificate-transparency` at OFTC.net
- Room `#certificate-transparency` at matrix.org
|
