personal/_posts/2017-12-26-lets-encrypt.md

   1 ---
   2 title: Let's Encrypt Tiny
   3 categories: Sysadmin
   4 ---
   5
   6 I think all HTTP communication on the internet should be encrypted -- and thanks
   7 to [Let's Encrypt](https://letsencrypt.org/), we are now much closer to this
   8 goal than we were two years ago.  However, when I set up Let's Encrypt on my
   9 server (which is more than a year ago by now), I was not very happy with the
  10 official client: The client manages multiple certificates with different sets of
  11 domains per certificate, but I found it entirely unclear which commands would
  12 replace existing certificates or create a new one.  Moreover, I have some
  13 special needs: I've set up DNSSEC with TLSA records containing hashes of my
  14 certificates, so replacing a certificate has to also update DNS and deal with
  15 the fact that DNS entries get cached.  Lucky enough, Let's Encrypt is based on
  16 open standards, so I was not forced to use their client!
  17
  18 To make a long story short, I decided to write my own Let's Encrypt client,
  19 which I describe in this post.
  20
  21 <!-- MORE -->
  22
  23 ## Let's Encrypt Tiny
  24
  25 The client is based on [acme-tiny](https://github.com/diafygi/acme-tiny), a
  26 beautifully small Python library (<200 lines) speaking the ACME protocol.
  27 That's the protocol developed by Let's Encrypt to communicate with an automated
  28 CA.  I duly called my client "Let's Encrypt Tiny", and with less than 250 lines
  29 I think that name is still fair.  For now,
  30 [Let's Encrypt Tiny](https://github.com/RalfJung/server-scripts/blob/master/letsencrypt-tiny)
  31 resides in my [server-scripts](https://github.com/RalfJung/server-scripts)
  32 repository, and it will stay there until anyone else has an interesting in using
  33 it. ;)
  34
  35 The central concept of Let's Encrypt Tiny is a "certificate line" -- a sequence
  36 of certificates, possibly for different private keys, that "belong together" in
  37 the sense that each is considered (by their owner) the successor of the
  38 previous.  Services like apache are configured to use a particular certificate
  39 line for a particular domain (well, in my case, it's the same line for all
  40 domains, but one could imagine different setups).  Each certificate line has a
  41 separate config file, whose most important job is to configure the set of
  42 domains in the latest certificate of the line.  The key operations on a
  43 certificate line are to create a *fresh* key and obtain a certificate for it,
  44 and to obtain a new certificate for the *existing* key.  Let's Encrypt
  45 certificates expire after 90 days, so we have to perform renewal at least that
  46 often, but there is no reason to always generate a fresh private key.  One
  47 reason to keep the previous key is that the TLSA record in DNS can be configured
  48 to be a hash of just the key, so a renewal for an existing key can be done
  49 without changing DNS.
  50
  51 The other important concept in Let's Encrypt Tiny is the idea of a "staging
  52 key", as opposed to the "live key".  This is needed to properly support
  53 DNSSEC+TLSA.  Just briefly, the idea of TLSA is to not use certificate
  54 authorities to determine the correct certificate for a domain (CAs have proven
  55 untrustworthy again and again, and a single failing CA undermines the security
  56 of the entire system), but instead use DNS.  If DNS is secured with DNSSEC --
  57 which is much more resilient against a single entity failing than the CA system
  58 -- then we can just put a hash of the certificate, or a hash of the public key,
  59 into the DNS, side-stepping the entire CA system.  Unfortunately, TLSA has not
  60 seen widespread adoption, though a
  61 [Firefox extension](https://addons.mozilla.org/en-US/firefox/addon/dnssec-validator/)
  62 is available (and extensions for some other browsers as well).  Still, I like
  63 this technology, so I have deployed it on my server.
  64
  65 However, one consequence of TLSA records is that a freshly generated key cannot
  66 immediately be used (i.e., by the web server): The DNS still contains the old
  67 key's data, and that data gets cached!  In Let's Encrypt Tiny, this key first
  68 gets "staged".  Next, we have to update the DNS zone to contain TLSA records for
  69 *both* the old and the new key.  Then we have to wait until the TTL
  70 (time-to-live) of that record passes, to make sure that no caches still contain
  71 *only* the old key.  Finally, we "unstage" the key so all the servers (web
  72 server, jabber server, and so on) to use the new certificate and key, which are
  73 now "live".
  74
  75 ## Configuration
  76
  77 Let's look at an example: Here is the configuration file for this server,
  78 ralfj.de, with comments explaining the purpose of the various options:
  79
  80 ```
  81 # The domains currently making up this certificate line:
  82 domains =
  83   ralfj.de
  84   www.ralfj.de
  85   lists.ralfj.de
  86   git.ralfj.de
  87   ns.ralfj.de
  88   ipv4.ns.ralfj.de
  89   ipv6.ns.ralfj.de
  90   jabber.ralfj.de
  91   conference.jabber.ralfj.de
  92 # ... this list goes on.
  93
  94 # The size of the RSA secret key (in bits).
  95 key-length = 4096
  96
  97 [timing]
  98 # Max. age of the private key before we generate a new one.
  99 max-key-age-days = 256
 100 # How long a new private key is "staged" before it is used as the live key.
 101 # 0 disables staging.
 102 staging-hours = 0
 103 # How many days before the certificate expires should be request a new one?
 104 renew-cert-before-expiry-days = 15
 105
 106 [hooks]
 107 # Script to execute after the certificate changed.
 108 post-certchange = /root/letsencrypt/cert-hook
 109 # Script to execute after the key changed.  Only needed when using DNSSEC+TLSA.
 110 #post-keychange = /root/letsencrypt/key-hook
 111
 112 [acme]
 113 # File storing the ACME account private key (created if missing).
 114 account-key = /etc/ssl/private/letsencrypt/account.key
 115 # Directory to put the ACME challenges into.  Must be mapped to
 116 # /.well-known/acme-challenge on all domains listed above.  For example, in
 117 # apache, put the following directive somewhere global:
 118 #   Alias /.well-known/acme-challenge/ /srv/acme-challenge/
 119 challenge-dir = /srv/acme-challenge/
 120
 121 [dirs]
 122 # Directory for certificates.
 123 certs = /etc/ssl/mycerts/letsencrypt
 124 # Directory for private keys.
 125 keys = /etc/ssl/private/letsencrypt
 126 # A place to put old certificates and keys.
 127 backups = /etc/ssl/old/letsencrypt
 128
 129 [files]
 130 # Filename prefix (without extension) for the live key and certificate.
 131 live = live
 132 # Filename prefix (without extension) for the staging key and certificate.
 133 staging = staging
 134 ```
 135
 136 With this configuration, Let's Encrypt Tiny creates files
 137 `/etc/ssl/mycerts/letsencrypt/live.crt` and
 138 `/etc/ssl/private/letsencrypt/live.key`.  These files are always the "tip" of
 139 the certificate line and should be configured in the various servers -- however,
 140 most servers will need these files to be massaged a bit.  First of all, we also
 141 need a key chain, and the intermediate CA used by Let's Encrypt actually changes
 142 over time.  Moreover, some servers want certificate and key in one file, while
 143 others want the certificates to be bundled with the keychain and expect the
 144 private key in a separate file.  Sometimes, the Diffie-Hellman parameters are
 145 also expected in the same file as the certificate -- every SSL-supporting server
 146 seems to handle this slightly differently.
 147
 148 This is all handled by the certificate hook, which creates the various derived files:
 149 ```
 150 #!/bin/sh
 151 cd /etc/ssl/mycerts/letsencrypt
 152 export PATH="/usr/sbin/:/sbin/:$PATH"
 153
 154 # Determine the intermediate CA used by this certificate.  We expect the
 155 # intermediate certificates to be stored in files in /etc/ssl/chains/,
 156 # e.g. /etc/ssl/chains/letsencrypt-X3.crt.
 157 ISSUER=$(openssl x509 -issuer -in live.crt -noout | sed 's/.*Authority \(X[0-9]\+\).*/\1/')
 158 ISSUER_FILE=/etc/ssl/chains/letsencrypt-"$ISSUER".crt
 159 if ! [ -f "$ISSUER_FILE" ]; then
 160     echo "Cannot find certificate for issuer $(openssl x509 -issuer -in live.crt -noout)"
 161     exit 1
 162 fi
 163
 164 # Create derived files.  We expect /etc/ssl/dh2048.pem to contain the DH
 165 # parameters, generated with
 166 #   openssl dhparam -out /etc/ssl/dh2048.pem 2048
 167 cat "$ISSUER_FILE" > live.chain # just the chain
 168 cat live.crt /etc/ssl/dh2048.pem > live.crt+dh # Certificate plus DH parameters
 169 cat live.crt live.chain > live.crt+chain # Certificate plus chain
 170
 171 # Fill in here:  the code to restart/reload all relevant services.
 172 ```
 173
 174 With this, the apache SSL configuration looks as follows:
 175
 176 ```
 177 # Certificate, Key, and DH parameters
 178 SSLCertificateFile      /etc/ssl/mycerts/live.crt+dh
 179 SSLCertificateKeyFile   /etc/ssl/private/live.key
 180 SSLCertificateChainFile /etc/ssl/mycerts/live.chain
 181
 182 # configure SSL ciphers and protocols
 183 SSLProtocol All -SSLv2 -SSLv3
 184 # TODO: Once OpenSSL supports GMC with more than just AES, revisit this
 185 # NOTE: The reason we support non-FS ciphers is stupid middleboxes that don't support FS
 186 SSLCipherSuite 'kEECDH+AESGCM:kEDH+AESGCM:kEECDH:kEDH:AESGCM:ALL:!3DES:!EXPORT:!LOW:!MEDIUM:!aNULL:!eNULL'
 187 SSLHonorCipherOrder     on
 188 ```
 189
 190 (My cipher suite is deliberately not the one from
 191 [bettercrypto.org](https://bettercrypto.org) because I prefer to not update it
 192 with every change in OpenSSL's supported ciphers.)
 193
 194 ## Obtaining the first certificate
 195
 196 You can now run `letsencrypt-tiny -c letsencrypt.conf init` to perform the
 197 initial setup.
 198
 199 In the future, to change the set of domains, first edit the config file and then
 200 run `letsencrypt-tiny -c letsencrypt.conf -k renew`.  The `-k` tells Let's
 201 Encrypt Tiny to also run the certificate hook.
 202
 203 ## Automation via cron
 204
 205 Let's Encrypt certificates expire after 90 days, so we want renewal to be
 206 automated.  To this end, just make sure that `letsencrypt-tiny -c
 207 letsencrypt.conf -k cron` gets run regularly, like once a day.  I have the
 208 following in root's crontab (`sudo crontab -e`):
 209
 210 ```
 211 32  6  *   *   *     /root/server-scripts/letsencrypt-tiny -c /root/letsencrypt/conf -k cron
 212 ```
 213
 214 This will check the time intervals you configured above, and act accordingly.
 215 If any action is taken, the script will print that information on standard
 216 output; if you have email set up on your server, this means you will get an
 217 email notification.
 218
 219 ## DNSSEC and TLSA
 220
 221 Everything described so far should give you a working SSL setup if you do not
 222 use DNSSEC+TLSA.  If you *do* use DNSSEC+TLSA, like I do on this server, you
 223 need to enable the `post-keychange` hook and have it regenerate your DNS zone,
 224 and you need to increase `staging-hours`.  The zone should always contain the
 225 hash of the live key, and, if a staging key exists, also the hash of the staging
 226 key.
 227
 228 I am managing my DNS zones with
 229 [zonemaker](https://www.ralfj.de/projects/zonemaker/), and wrote some Python
 230 code to automatically generate TLSA records using the `tlsa` tool:
 231
 232 ```
 233 def TLSA_from_crt(protocol, port, crtfile):
 234     crtfile = "/etc/ssl/mycerts/"+crtfile
 235     open(crtfile).close() # check if the file exists
 236     # make sure we match on *the key only*, so that we can renew the certificate without harm
 237     zone_line = subprocess.check_output(["tlsa", "--selector", str(TLSA.Selector.SubjectPublicKeyInfo), "--certificate", crtfile, "example.org"]).decode("utf-8")
 238     m = re.match("^[0-9a-zA-Z_.-]+ IN TLSA ([0-9]+) ([0-9]+) ([0-9]+) ([0-9a-zA-Z]+)$", zone_line)
 239     assert m is not None
 240     assert int(m.group(1)) == TLSA.Usage.EndEntity
 241     assert int(m.group(2)) == TLSA.Selector.SubjectPublicKeyInfo
 242     return TLSA(protocol, port, TLSA.Usage.EndEntity, TLSA.Selector.SubjectPublicKeyInfo, int(m.group(3)), m.group(4))
 243
 244 def TLSA_for_LE(protocol = Protocol.TCP, port = 443):
 245     # add both the live and (potentially) staging certificate to the letsencrypt TLSA record set
 246     r = [TLSA_from_crt(protocol, port, "letsencrypt/live.crt")]
 247     try:
 248         r.append(TLSA_from_crt(protocol, port, "letsencrypt/staging.crt"))
 249     except IOError:
 250         pass
 251     return r
 252 ```
 253
 254 Now I add `TLSA_for_LE(port = 443)` to the records of my domains.  Finally, the
 255 key hook just runs zonemaker and has bind reload the zone (it will automatically
 256 also be resigned).  Now, whenever a staging key is created, it is automatically
 257 added to my zone.  At least 25h later (I have the TTL set to 24h), the key gets
 258 unstaged, and the old TLSA record is removed from the zone.
 259
 260 That's it!  If you have any questions, feel free to report
 261 [issues at GitHub](https://github.com/RalfJung/server-scripts/issues).