document CAs in use at tor, and particularly the auto-ca

This is in response to the Digicert emails we have received today, and
to make sure we have somewhere that tells us to talk to TBB people.

tsa/howto/tls.mdwn

@@ -123,6 +123,11 @@ Then run Puppet on all affected hosts, for example the static mirrors:
     cumin 'C:roles::static_mirror_web' 'puppet agent -t'
 
 ## Pager playbook
+
+ * if you get email from Digicert, ask the Tor Browser team, they use
+   it to sign code (see "Design" below for more information about
+   which CAs are in use
+
 ## Disaster recovery
 
 # Reference
@@ -135,6 +140,68 @@ Then run Puppet on all affected hosts, for example the static mirrors:
 
 ## Design
 
+### Certificate authorities in use at Tor
+
+This documents mostly covers the Let's Encrypt certificates used by
+websites and other services managed by TPA.
+
+But there are other certificate authorities in use inside TPA and,
+more broadly, at Tor. Here's the list of known CAs in operation at the
+time of writing (2020-04-15):
+
+ * [Let's Encrypt](https://letsencrypt.org): automatically issues certificates for most websites
+   and domains, managed by TPA
+ * [Globalsign](https://globalsign.com): used by the [Fastly](https://www.fastly.com/) CDN used to distributed
+   TBB updates
+ * [Digicert](https://www.digicert.com/): used by other teams to sign software releases for Mac and Windows
+ * [[Puppet]]: our configuration management infrastructure has its own
+   X.509 certificate authority which allows "Puppet agents" to
+   authenticate and verify the "Puppet Master", see [[our
+   documentation|puppet]] and [upstream documentation](https://puppet.com/docs/puppet/latest/ssl_certificates.html) for details
+ * internal "auto-ca": all nodes in Puppet get their own X.509
+   certificate signed by a standalone, self-signed X.509 certificate,
+   documented below
+
+### Internal auto-ca
+
+The internal "auto-ca" is a standalone certificate authority running
+on the Puppet master (currently `pauli`), in
+`/srv/puppet.torproject.org/auto-ca`. 
+
+The CA runs based on a `Makefile` which takes care of creating,
+revoking, and distributing certificates to all nodes. Certificates are
+valid for a year (365 days, actually). If a certificate is going to
+expire in less than 30 days, it gets revoked and removed.
+
+The makefile then iterates over the known hosts (as per
+`/var/lib/misc/thishost/ssh_known_hosts`, generated from [[ldap]]) to
+create (two) certificates for each host. This makes sure certs get
+renewed before their expiry. It will also remove certificates from
+machines that are *not* known, which is the source of the `revoked
+client` emails TPA gets when a machine gets [[retired|retire-a-host]].
+
+The Makefile then creates *two* certificates per host: a "clientcert"
+(in `clientcerts/`) and a "server" (?) cert (in `certs/`). The former
+is used by Bacula and Postfix clients to authenticate with the central
+servers for backups and mail delivery, respectively. The latter is
+used by those servers to authenticate to their clients but is also
+used as default HTTPS certificates on new apache hosts.
+
+Once all certs are created, revoked, and/or removed, they gets copied
+into Puppet's file hierarchy, in the following locations:
+
+ * `/etc/puppet/modules/ssl/files/certs/`: server certs
+ * `/etc/puppet/modules/ssl/files/clientcerts/`: client certs.
+ * `/etc/puppet/modules/ssl/files/clientcerts/fingerprints`:
+   colon-separated `SHA256` fingerprints of all "client certs", one per
+   line
+ * `/etc/puppet/modules/ssl/files/certs/ca.crt`: CA's certificate
+ * `/etc/puppet/modules/ssl/files/certs/ca.crl`: certificate
+   revocation list
+
+This work gets run from cron (in `/etc/cron.daily/local-auto-ca`)
+which calls `make -s install` every day.
+
 ### Let's encrypt workflow
 
 When you push to the git repository on the `git-rw.torproject.org`
@@ -217,4 +284,8 @@ server (currently `cupani`):
 
 ## Alternatives considered
 
-<!-- include benchmarks and procedure if relevant -->
+The `auto-ca` machinery could be replaced by Puppet code. We could
+also leverage the ACME protocol designed by letsencrypt to run our own
+CA instead of just OpenSSL, although that might be overkill. In
+general it might be preferable to reuse an existing solution than
+maintain our own software in Make.