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
|
# silent-ct
An implementation of a silent Certificate Transparency monitor.
**Status:** drafty prototype, please do not use for anything serious.
## How it works
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
### Setup a node
You will need the `silent-ctnode` tool to create submissions that the monitor
can pull. Install:
$ go install rgdd.se/silent-ct/cmd/silent-ctnode@latest
Locate the node's certificates that are still valid (i.e., not expired) and
prepare a submission for them:
$ silent-ctnode -n NAME -s SECRET /path/to/chain-1.pem /path/to/chain-2.pem ...
`NAME` is an arbitrary name of the node.
`SECRET` is a secret that will only be shared with the monitor.
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.
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.
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.
Repeat this setup if there are multiple nodes.
### Setup the monitor
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"
]
}
],
"nodes": [
{
"name": "NODE_NAME",
"secret": "NODE_SECRET",
"url": "SUBMISSION_URL",
"issues": [
"example.org",
"www.example.org"
]
}
]
}
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.
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.
Bootstrap the monitor in a non-existent directory:
$ silent-ctmoon --bootstrap -f policy.json -d /path/to/directory -v INFO
...
Leave the monitor running:
$ silent-ctmoon -f policy.json -d /path/to/directory
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.
### Further documentation
- A lengthier [introduction](./docs/introduction.md) to the overall design
## Contact
- Room `#certificate-transparency` at OFTC.net
- Room `#certificate-transparency` at matrix.org
|
