ACME: Difference between revisions
imported>Samuela No edit summary |
WoutSwinkels (talk | contribs) |
||
| (8 intermediate revisions by 6 users not shown) | |||
| Line 2: | Line 2: | ||
== Setup == | == Setup == | ||
=== DNS-01 Challenge === | |||
Following example setup generates certificates using DNS validation. [https://letsencrypt.org/repository/ Let's Encrypt ToS] has to be accepted. Further the contact mail <code>admin+acme@example.com</code> is defined. | Following example setup generates certificates using DNS validation. [https://letsencrypt.org/repository/ Let's Encrypt ToS] has to be accepted. Further the contact mail <code>admin+acme@example.com</code> is defined. | ||
| Line 13: | Line 13: | ||
# Supplying password files like this will make your credentials world-readable | # Supplying password files like this will make your credentials world-readable | ||
# in the Nix store. This is for demonstration purpose only, do not use this in production. | # in the Nix store. This is for demonstration purpose only, do not use this in production. | ||
environmentFile = "${pkgs.writeText "inwx-creds" '' | |||
INWX_USERNAME=xxxxxxxxxx | INWX_USERNAME=xxxxxxxxxx | ||
INWX_PASSWORD=yyyyyyyyyy | INWX_PASSWORD=yyyyyyyyyy | ||
| Line 22: | Line 22: | ||
Certificates are getting generated for the domain <code>mx1.example.org</code> using the DNS provider <code>inwx</code>. See [https://go-acme.github.io/lego/dns upstream documentation] on available providers and their specific configuration for the <code>credentialsFile</code> option. | Certificates are getting generated for the domain <code>mx1.example.org</code> using the DNS provider <code>inwx</code>. See [https://go-acme.github.io/lego/dns upstream documentation] on available providers and their specific configuration for the <code>credentialsFile</code> option. | ||
The next example issues a wildcard certificate and uses Cloudflare for validation. We're also adding the group "nginx" here so that the certificate files can be used by nginx later on.<syntaxhighlight lang="nix"> | |||
security.acme = { | |||
acceptTerms = true; | |||
defaults.email = "admin@example.org"; | |||
certs = { | |||
"example.org" = { | |||
domain = "*.example.org"; | |||
group = "nginx"; | |||
dnsProvider = "cloudflare"; | |||
# location of your CLOUDFLARE_DNS_API_TOKEN=[value] | |||
# https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#EnvironmentFile= | |||
environmentFile = "/home/admin/cloudflare"; | |||
}; | |||
}; | |||
}; | |||
</syntaxhighlight> | |||
=== HTTP-01 Challenge === | |||
Besides DNS validation it is also possible to obtain certificates by placing a file on your webserver at <code>http://example.org/.well-known/acme-challenge</code>. Instead of using the <code>dnsProvider</code> option, we use the <code>webroot</code> option. | |||
<syntaxhighlight lang="nix"> | |||
security.acme = { | |||
acceptTerms = true; | |||
defaults.email = "admin@example.org"; | |||
certs."example.org" = { | |||
# An acme system user is created. This user belongs to the acme group and the home directory is /var/lib/acme. | |||
# This user will try to make the directory .well-known/acme-challenge/ under the webroot directory. | |||
webroot = "/var/lib/acme"; | |||
}; | |||
}; | |||
</syntaxhighlight> | |||
We need to make sure that our webserver knows where to redirect <code>http://example.org/.well-known/acme-challenge</code> to. If you use [[Nginx|nginx]] this can be done as follows: | |||
<syntaxhighlight lang="nginx"> | |||
location /.well-known/acme-challenge/ { | |||
rewrite /.well-known/acme-challenge/(.*) /$1 break; | |||
root /var/lib/acme/.well-known/acme-challenge; | |||
} | |||
</syntaxhighlight> | |||
== Usage == | == Usage == | ||
After successfull generation, certificates can be found in the directory <code>/var/lib/acme</code>. | After successfull generation, certificates can be found in the directory <code>/var/lib/acme</code>. When using certificates in other applications it may be required to change permissions. The group of the certificate files can be adjusted by setting the <code>group</code> option as a string | ||
<syntaxhighlight lang="nix"> | |||
security.acme.certs."example.org".group = "nginx"; | |||
</syntaxhighlight> | |||
or reference. | |||
<syntaxhighlight lang="nix"> | <syntaxhighlight lang="nix"> | ||
security.acme.certs." | security.acme.certs."example.org".group = config.services.nginx.group; | ||
</syntaxhighlight>Resulting in the following files and permissions<syntaxhighlight lang="bash"> | |||
lrwxrwxrwx 1 acme nginx 13 Aug 4 12:57 cert.pem -> fullchain.pem | |||
-rw-r----- 1 acme nginx 1567 Aug 4 12:57 chain.pem | |||
-rw-r----- 1 acme nginx 2865 Aug 4 12:57 fullchain.pem | |||
-rw-r----- 1 acme nginx 3092 Aug 4 12:57 full.pem | |||
-rw-r----- 1 acme nginx 227 Aug 4 12:57 key.pem | |||
</syntaxhighlight> | |||
== Using Let's Encrypt Staging == | |||
If you'd like to use the Let's Encrypt [https://letsencrypt.org/docs/staging-environment/ staging environment], eg for its less stringent rate limits, set | |||
<syntaxhighlight lang="nix"> | |||
security.acme.defaults.server = "https://acme-staging-v02.api.letsencrypt.org/directory"; | |||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 34: | Line 95: | ||
* NixOS manual on [https://nixos.org/manual/nixos/stable/index.html#module-security-acme SSL/TLS Certificates with ACME] | * NixOS manual on [https://nixos.org/manual/nixos/stable/index.html#module-security-acme SSL/TLS Certificates with ACME] | ||
[[Category: Server]] | |||
[[Category: Networking]] | |||