nixos/modules/security/acme/default.md

   1 # SSL/TLS Certificates with ACME {#module-security-acme}
   2
   3 NixOS supports automatic domain validation & certificate retrieval and
   4 renewal using the ACME protocol. Any provider can be used, but by default
   5 NixOS uses Let's Encrypt. The alternative ACME client
   6 [lego](https://go-acme.github.io/lego/) is used under
   7 the hood.
   8
   9 Automatic cert validation and configuration for Apache and Nginx virtual
  10 hosts is included in NixOS, however if you would like to generate a wildcard
  11 cert or you are not using a web server you will have to configure DNS
  12 based validation.
  13
  14 ## Prerequisites {#module-security-acme-prerequisites}
  15
  16 To use the ACME module, you must accept the provider's terms of service
  17 by setting [](#opt-security.acme.acceptTerms)
  18 to `true`. The Let's Encrypt ToS can be found
  19 [here](https://letsencrypt.org/repository/).
  20
  21 You must also set an email address to be used when creating accounts with
  22 Let's Encrypt. You can set this for all certs with
  23 [](#opt-security.acme.defaults.email)
  24 and/or on a per-cert basis with
  25 [](#opt-security.acme.certs._name_.email).
  26 This address is only used for registration and renewal reminders,
  27 and cannot be used to administer the certificates in any way.
  28
  29 Alternatively, you can use a different ACME server by changing the
  30 [](#opt-security.acme.defaults.server) option
  31 to a provider of your choosing, or just change the server for one cert with
  32 [](#opt-security.acme.certs._name_.server).
  33
  34 You will need an HTTP server or DNS server for verification. For HTTP,
  35 the server must have a webroot defined that can serve
  36 {file}`.well-known/acme-challenge`. This directory must be
  37 writeable by the user that will run the ACME client. For DNS, you must
  38 set up credentials with your provider/server for use with lego.
  39
  40 ## Using ACME certificates in Nginx {#module-security-acme-nginx}
  41
  42 NixOS supports fetching ACME certificates for you by setting
  43 `enableACME = true;` in a virtualHost config. We first create self-signed
  44 placeholder certificates in place of the real ACME certs. The placeholder
  45 certs are overwritten when the ACME certs arrive. For
  46 `foo.example.com` the config would look like this:
  47
  48 ```nix
  49 {
  50   security.acme.acceptTerms = true;
  51   security.acme.defaults.email = "admin+acme@example.com";
  52   services.nginx = {
  53     enable = true;
  54     virtualHosts = {
  55       "foo.example.com" = {
  56         forceSSL = true;
  57         enableACME = true;
  58         # All serverAliases will be added as extra domain names on the certificate.
  59         serverAliases = [ "bar.example.com" ];
  60         locations."/" = {
  61           root = "/var/www";
  62         };
  63       };
  64
  65       # We can also add a different vhost and reuse the same certificate
  66       # but we have to append extraDomainNames manually beforehand:
  67       # security.acme.certs."foo.example.com".extraDomainNames = [ "baz.example.com" ];
  68       "baz.example.com" = {
  69         forceSSL = true;
  70         useACMEHost = "foo.example.com";
  71         locations."/" = {
  72           root = "/var/www";
  73         };
  74       };
  75     };
  76   };
  77 }
  78 ```
  79
  80 ## Using ACME certificates in Apache/httpd {#module-security-acme-httpd}
  81
  82 Using ACME certificates with Apache virtual hosts is identical
  83 to using them with Nginx. The attribute names are all the same, just replace
  84 "nginx" with "httpd" where appropriate.
  85
  86 ## Manual configuration of HTTP-01 validation {#module-security-acme-configuring}
  87
  88 First off you will need to set up a virtual host to serve the challenges.
  89 This example uses a vhost called `certs.example.com`, with
  90 the intent that you will generate certs for all your vhosts and redirect
  91 everyone to HTTPS.
  92
  93 ```nix
  94 {
  95   security.acme.acceptTerms = true;
  96   security.acme.defaults.email = "admin+acme@example.com";
  97
  98   # /var/lib/acme/.challenges must be writable by the ACME user
  99   # and readable by the Nginx user. The easiest way to achieve
 100   # this is to add the Nginx user to the ACME group.
 101   users.users.nginx.extraGroups = [ "acme" ];
 102
 103   services.nginx = {
 104     enable = true;
 105     virtualHosts = {
 106       "acmechallenge.example.com" = {
 107         # Catchall vhost, will redirect users to HTTPS for all vhosts
 108         serverAliases = [ "*.example.com" ];
 109         locations."/.well-known/acme-challenge" = {
 110           root = "/var/lib/acme/.challenges";
 111         };
 112         locations."/" = {
 113           return = "301 https://$host$request_uri";
 114         };
 115       };
 116     };
 117   };
 118   # Alternative config for Apache
 119   users.users.wwwrun.extraGroups = [ "acme" ];
 120   services.httpd = {
 121     enable = true;
 122     virtualHosts = {
 123       "acmechallenge.example.com" = {
 124         # Catchall vhost, will redirect users to HTTPS for all vhosts
 125         serverAliases = [ "*.example.com" ];
 126         # /var/lib/acme/.challenges must be writable by the ACME user and readable by the Apache user.
 127         # By default, this is the case.
 128         documentRoot = "/var/lib/acme/.challenges";
 129         extraConfig = ''
 130           RewriteEngine On
 131           RewriteCond %{HTTPS} off
 132           RewriteCond %{REQUEST_URI} !^/\.well-known/acme-challenge [NC]
 133           RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301]
 134         '';
 135       };
 136     };
 137   };
 138 }
 139 ```
 140
 141 Now you need to configure ACME to generate a certificate.
 142
 143 ```nix
 144 {
 145   security.acme.certs."foo.example.com" = {
 146     webroot = "/var/lib/acme/.challenges";
 147     email = "foo@example.com";
 148     # Ensure that the web server you use can read the generated certs
 149     # Take a look at the group option for the web server you choose.
 150     group = "nginx";
 151     # Since we have a wildcard vhost to handle port 80,
 152     # we can generate certs for anything!
 153     # Just make sure your DNS resolves them.
 154     extraDomainNames = [ "mail.example.com" ];
 155   };
 156 }
 157 ```
 158
 159 The private key {file}`key.pem` and certificate
 160 {file}`fullchain.pem` will be put into
 161 {file}`/var/lib/acme/foo.example.com`.
 162
 163 Refer to [](#ch-options) for all available configuration
 164 options for the [security.acme](#opt-security.acme.certs)
 165 module.
 166
 167 ## Configuring ACME for DNS validation {#module-security-acme-config-dns}
 168
 169 This is useful if you want to generate a wildcard certificate, since
 170 ACME servers will only hand out wildcard certs over DNS validation.
 171 There are a number of supported DNS providers and servers you can utilise,
 172 see the [lego docs](https://go-acme.github.io/lego/dns/)
 173 for provider/server specific configuration values. For the sake of these
 174 docs, we will provide a fully self-hosted example using bind.
 175
 176 ```nix
 177 {
 178   services.bind = {
 179     enable = true;
 180     extraConfig = ''
 181       include "/var/lib/secrets/dnskeys.conf";
 182     '';
 183     zones = [
 184       rec {
 185         name = "example.com";
 186         file = "/var/db/bind/${name}";
 187         master = true;
 188         extraConfig = "allow-update { key rfc2136key.example.com.; };";
 189       }
 190     ];
 191   };
 192
 193   # Now we can configure ACME
 194   security.acme.acceptTerms = true;
 195   security.acme.defaults.email = "admin+acme@example.com";
 196   security.acme.certs."example.com" = {
 197     domain = "*.example.com";
 198     dnsProvider = "rfc2136";
 199     environmentFile = "/var/lib/secrets/certs.secret";
 200     # We don't need to wait for propagation since this is a local DNS server
 201     dnsPropagationCheck = false;
 202   };
 203 }
 204 ```
 205
 206 The {file}`dnskeys.conf` and {file}`certs.secret`
 207 must be kept secure and thus you should not keep their contents in your
 208 Nix config. Instead, generate them one time with a systemd service:
 209
 210 ```nix
 211 {
 212   systemd.services.dns-rfc2136-conf = {
 213     requiredBy = ["acme-example.com.service" "bind.service"];
 214     before = ["acme-example.com.service" "bind.service"];
 215     unitConfig = {
 216       ConditionPathExists = "!/var/lib/secrets/dnskeys.conf";
 217     };
 218     serviceConfig = {
 219       Type = "oneshot";
 220       UMask = 0077;
 221     };
 222     path = [ pkgs.bind ];
 223     script = ''
 224       mkdir -p /var/lib/secrets
 225       chmod 755 /var/lib/secrets
 226       tsig-keygen rfc2136key.example.com > /var/lib/secrets/dnskeys.conf
 227       chown named:root /var/lib/secrets/dnskeys.conf
 228       chmod 400 /var/lib/secrets/dnskeys.conf
 229
 230       # extract secret value from the dnskeys.conf
 231       while read x y; do if [ "$x" = "secret" ]; then secret="''${y:1:''${#y}-3}"; fi; done < /var/lib/secrets/dnskeys.conf
 232
 233       cat > /var/lib/secrets/certs.secret << EOF
 234       RFC2136_NAMESERVER='127.0.0.1:53'
 235       RFC2136_TSIG_ALGORITHM='hmac-sha256.'
 236       RFC2136_TSIG_KEY='rfc2136key.example.com'
 237       RFC2136_TSIG_SECRET='$secret'
 238       EOF
 239       chmod 400 /var/lib/secrets/certs.secret
 240     '';
 241   };
 242 }
 243 ```
 244
 245 Now you're all set to generate certs! You should monitor the first invocation
 246 by running `systemctl start acme-example.com.service &
 247 journalctl -fu acme-example.com.service` and watching its log output.
 248
 249 ## Using DNS validation with web server virtual hosts {#module-security-acme-config-dns-with-vhosts}
 250
 251 It is possible to use DNS-01 validation with all certificates,
 252 including those automatically configured via the Nginx/Apache
 253 [`enableACME`](#opt-services.nginx.virtualHosts._name_.enableACME)
 254 option. This configuration pattern is fully
 255 supported and part of the module's test suite for Nginx + Apache.
 256
 257 You must follow the guide above on configuring DNS-01 validation
 258 first, however instead of setting the options for one certificate
 259 (e.g. [](#opt-security.acme.certs._name_.dnsProvider))
 260 you will set them as defaults
 261 (e.g. [](#opt-security.acme.defaults.dnsProvider)).
 262
 263 ```nix
 264 {
 265   # Configure ACME appropriately
 266   security.acme.acceptTerms = true;
 267   security.acme.defaults.email = "admin+acme@example.com";
 268   security.acme.defaults = {
 269     dnsProvider = "rfc2136";
 270     environmentFile = "/var/lib/secrets/certs.secret";
 271     # We don't need to wait for propagation since this is a local DNS server
 272     dnsPropagationCheck = false;
 273   };
 274
 275   # For each virtual host you would like to use DNS-01 validation with,
 276   # set acmeRoot = null
 277   services.nginx = {
 278     enable = true;
 279     virtualHosts = {
 280       "foo.example.com" = {
 281         enableACME = true;
 282         acmeRoot = null;
 283       };
 284     };
 285   };
 286 }
 287 ```
 288
 289 And that's it! Next time your configuration is rebuilt, or when
 290 you add a new virtualHost, it will be DNS-01 validated.
 291
 292 ## Using ACME with services demanding root owned certificates {#module-security-acme-root-owned}
 293
 294 Some services refuse to start if the configured certificate files
 295 are not owned by root. PostgreSQL and OpenSMTPD are examples of these.
 296 There is no way to change the user the ACME module uses (it will always be
 297 `acme`), however you can use systemd's
 298 `LoadCredential` feature to resolve this elegantly.
 299 Below is an example configuration for OpenSMTPD, but this pattern
 300 can be applied to any service.
 301
 302 ```nix
 303 {
 304   # Configure ACME however you like (DNS or HTTP validation), adding
 305   # the following configuration for the relevant certificate.
 306   # Note: You cannot use `systemctl reload` here as that would mean
 307   # the LoadCredential configuration below would be skipped and
 308   # the service would continue to use old certificates.
 309   security.acme.certs."mail.example.com".postRun = ''
 310     systemctl restart opensmtpd
 311   '';
 312
 313   # Now you must augment OpenSMTPD's systemd service to load
 314   # the certificate files.
 315   systemd.services.opensmtpd.requires = ["acme-finished-mail.example.com.target"];
 316   systemd.services.opensmtpd.serviceConfig.LoadCredential = let
 317     certDir = config.security.acme.certs."mail.example.com".directory;
 318   in [
 319     "cert.pem:${certDir}/cert.pem"
 320     "key.pem:${certDir}/key.pem"
 321   ];
 322
 323   # Finally, configure OpenSMTPD to use these certs.
 324   services.opensmtpd = let
 325     credsDir = "/run/credentials/opensmtpd.service";
 326   in {
 327     enable = true;
 328     setSendmail = false;
 329     serverConfiguration = ''
 330       pki mail.example.com cert "${credsDir}/cert.pem"
 331       pki mail.example.com key "${credsDir}/key.pem"
 332       listen on localhost tls pki mail.example.com
 333       action act1 relay host smtp://127.0.0.1:10027
 334       match for local action act1
 335     '';
 336   };
 337 }
 338 ```
 339
 340 ## Regenerating certificates {#module-security-acme-regenerate}
 341
 342 Should you need to regenerate a particular certificate in a hurry, such
 343 as when a vulnerability is found in Let's Encrypt, there is now a convenient
 344 mechanism for doing so. Running
 345 `systemctl clean --what=state acme-example.com.service`
 346 will remove all certificate files and the account data for the given domain,
 347 allowing you to then `systemctl start acme-example.com.service`
 348 to generate fresh ones.
 349
 350 ## Fixing JWS Verification error {#module-security-acme-fix-jws}
 351
 352 It is possible that your account credentials file may become corrupt and need
 353 to be regenerated. In this scenario lego will produce the error `JWS verification error`.
 354 The solution is to simply delete the associated accounts file and
 355 re-run the affected service(s).
 356
 357 ```shell
 358 # Find the accounts folder for the certificate
 359 systemctl cat acme-example.com.service | grep -Po 'accounts/[^:]*'
 360 export accountdir="$(!!)"
 361 # Move this folder to some place else
 362 mv /var/lib/acme/.lego/$accountdir{,.bak}
 363 # Recreate the folder using systemd-tmpfiles
 364 systemd-tmpfiles --create
 365 # Get a new account and reissue certificates
 366 # Note: Do this for all certs that share the same account email address
 367 systemctl start acme-example.com.service
 368 ```