pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="module-security-acme">
6 <title>SSL/TLS Certificates with ACME</title>
7 <para>
8 NixOS supports automatic domain validation & certificate retrieval and
9 renewal using the ACME protocol. Any provider can be used, but by default
10 NixOS uses Let's Encrypt. The alternative ACME client <literal>lego</literal>
11 is used under the hood.
12 </para>
13 <para>
14 Automatic cert validation and configuration for Apache and Nginx virtual
15 hosts is included in NixOS, however if you would like to generate a wildcard
16 cert or you are not using a web server you will have to configure DNS
17 based validation.
18 </para>
19 <section xml:id="module-security-acme-prerequisites">
20 <title>Prerequisites</title>
21
22 <para>
23 To use the ACME module, you must accept the provider's terms of service
24 by setting <literal><xref linkend="opt-security.acme.acceptTerms" /></literal>
25 to <literal>true</literal>. The Let's Encrypt ToS can be found
26 <link xlink:href="https://letsencrypt.org/repository/">here</link>.
27 </para>
28
29 <para>
30 You must also set an email address to be used when creating accounts with
31 Let's Encrypt. You can set this for all certs with
32 <literal><xref linkend="opt-security.acme.email" /></literal>
33 and/or on a per-cert basis with
34 <literal><xref linkend="opt-security.acme.certs._name_.email" /></literal>.
35 This address is only used for registration and renewal reminders,
36 and cannot be used to administer the certificates in any way.
37 </para>
38
39 <para>
40 Alternatively, you can use a different ACME server by changing the
41 <literal><xref linkend="opt-security.acme.server" /></literal> option
42 to a provider of your choosing, or just change the server for one cert with
43 <literal><xref linkend="opt-security.acme.certs._name_.server" /></literal>.
44 </para>
45
46 <para>
47 You will need an HTTP server or DNS server for verification. For HTTP,
48 the server must have a webroot defined that can serve
49 <filename>.well-known/acme-challenge</filename>. This directory must be
50 writeable by the user that will run the ACME client. For DNS, you must
51 set up credentials with your provider/server for use with lego.
52 </para>
53 </section>
54 <section xml:id="module-security-acme-nginx">
55 <title>Using ACME certificates in Nginx</title>
56
57 <para>
58 NixOS supports fetching ACME certificates for you by setting
59 <literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link>
60 = true;</literal> in a virtualHost config. We first create self-signed
61 placeholder certificates in place of the real ACME certs. The placeholder
62 certs are overwritten when the ACME certs arrive. For
63 <literal>foo.example.com</literal> the config would look like.
64 </para>
65
66<programlisting>
67<xref linkend="opt-security.acme.acceptTerms" /> = true;
68<xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";
69services.nginx = {
70 <link linkend="opt-services.nginx.enable">enable</link> = true;
71 <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
72 "foo.example.com" = {
73 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
74 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
75 # All serverAliases will be added as <link linkend="opt-security.acme.certs._name_.extraDomainNames">extra domain names</link> on the certificate.
76 <link linkend="opt-services.nginx.virtualHosts._name_.serverAliases">serverAliases</link> = [ "bar.example.com" ];
77 locations."/" = {
78 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.root">root</link> = "/var/www";
79 };
80 };
81
82 # We can also add a different vhost and reuse the same certificate
83 # but we have to append extraDomainNames manually.
84 <link linkend="opt-security.acme.certs._name_.extraDomainNames">security.acme.certs."foo.example.com".extraDomainNames</link> = [ "baz.example.com" ];
85 "baz.example.com" = {
86 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
87 <link linkend="opt-services.nginx.virtualHosts._name_.useACMEHost">useACMEHost</link> = "foo.example.com";
88 locations."/" = {
89 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.root">root</link> = "/var/www";
90 };
91 };
92 };
93}
94</programlisting>
95 </section>
96 <section xml:id="module-security-acme-httpd">
97 <title>Using ACME certificates in Apache/httpd</title>
98
99 <para>
100 Using ACME certificates with Apache virtual hosts is identical
101 to using them with Nginx. The attribute names are all the same, just replace
102 "nginx" with "httpd" where appropriate.
103 </para>
104 </section>
105 <section xml:id="module-security-acme-configuring">
106 <title>Manual configuration of HTTP-01 validation</title>
107
108 <para>
109 First off you will need to set up a virtual host to serve the challenges.
110 This example uses a vhost called <literal>certs.example.com</literal>, with
111 the intent that you will generate certs for all your vhosts and redirect
112 everyone to HTTPS.
113 </para>
114
115<programlisting>
116<xref linkend="opt-security.acme.acceptTerms" /> = true;
117<xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";
118
119# /var/lib/acme/.challenges must be writable by the ACME user
120# and readable by the Nginx user. The easiest way to achieve
121# this is to add the Nginx user to the ACME group.
122<link linkend="opt-users.users._name_.extraGroups">users.users.nginx.extraGroups</link> = [ "acme" ];
123
124services.nginx = {
125 <link linkend="opt-services.nginx.enable">enable</link> = true;
126 <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
127 "acmechallenge.example.com" = {
128 # Catchall vhost, will redirect users to HTTPS for all vhosts
129 <link linkend="opt-services.nginx.virtualHosts._name_.serverAliases">serverAliases</link> = [ "*.example.com" ];
130 locations."/.well-known/acme-challenge" = {
131 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.root">root</link> = "/var/lib/acme/.challenges";
132 };
133 locations."/" = {
134 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.return">return</link> = "301 https://$host$request_uri";
135 };
136 };
137 };
138}
139# Alternative config for Apache
140<link linkend="opt-users.users._name_.extraGroups">users.users.wwwrun.extraGroups</link> = [ "acme" ];
141services.httpd = {
142 <link linkend="opt-services.httpd.enable">enable = true;</link>
143 <link linkend="opt-services.httpd.virtualHosts">virtualHosts</link> = {
144 "acmechallenge.example.com" = {
145 # Catchall vhost, will redirect users to HTTPS for all vhosts
146 <link linkend="opt-services.httpd.virtualHosts._name_.serverAliases">serverAliases</link> = [ "*.example.com" ];
147 # /var/lib/acme/.challenges must be writable by the ACME user and readable by the Apache user.
148 # By default, this is the case.
149 <link linkend="opt-services.httpd.virtualHosts._name_.documentRoot">documentRoot</link> = "/var/lib/acme/.challenges";
150 <link linkend="opt-services.httpd.virtualHosts._name_.extraConfig">extraConfig</link> = ''
151 RewriteEngine On
152 RewriteCond %{HTTPS} off
153 RewriteCond %{REQUEST_URI} !^/\.well-known/acme-challenge [NC]
154 RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301]
155 '';
156 };
157 };
158}
159</programlisting>
160
161 <para>
162 Now you need to configure ACME to generate a certificate.
163 </para>
164
165<programlisting>
166<xref linkend="opt-security.acme.certs"/>."foo.example.com" = {
167 <link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/lib/acme/.challenges";
168 <link linkend="opt-security.acme.certs._name_.email">email</link> = "foo@example.com";
169 # Ensure that the web server you use can read the generated certs
170 # Take a look at the <link linkend="opt-services.nginx.group">group</link> option for the web server you choose.
171 <link linkend="opt-security.acme.certs._name_.group">group</link> = "nginx";
172 # Since we have a wildcard vhost to handle port 80,
173 # we can generate certs for anything!
174 # Just make sure your DNS resolves them.
175 <link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link> = [ "mail.example.com" ];
176};
177</programlisting>
178
179 <para>
180 The private key <filename>key.pem</filename> and certificate
181 <filename>fullchain.pem</filename> will be put into
182 <filename>/var/lib/acme/foo.example.com</filename>.
183 </para>
184
185 <para>
186 Refer to <xref linkend="ch-options" /> for all available configuration
187 options for the <link linkend="opt-security.acme.certs">security.acme</link>
188 module.
189 </para>
190 </section>
191 <section xml:id="module-security-acme-config-dns">
192 <title>Configuring ACME for DNS validation</title>
193
194 <para>
195 This is useful if you want to generate a wildcard certificate, since
196 ACME servers will only hand out wildcard certs over DNS validation.
197 There a number of supported DNS providers and servers you can utilise,
198 see the <link xlink:href="https://go-acme.github.io/lego/dns/">lego docs</link>
199 for provider/server specific configuration values. For the sake of these
200 docs, we will provide a fully self-hosted example using bind.
201 </para>
202
203<programlisting>
204services.bind = {
205 <link linkend="opt-services.bind.enable">enable</link> = true;
206 <link linkend="opt-services.bind.extraConfig">extraConfig</link> = ''
207 include "/var/lib/secrets/dnskeys.conf";
208 '';
209 <link linkend="opt-services.bind.zones">zones</link> = [
210 rec {
211 name = "example.com";
212 file = "/var/db/bind/${name}";
213 master = true;
214 extraConfig = "allow-update { key rfc2136key.example.com.; };";
215 }
216 ];
217}
218
219# Now we can configure ACME
220<xref linkend="opt-security.acme.acceptTerms" /> = true;
221<xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";
222<xref linkend="opt-security.acme.certs" />."example.com" = {
223 <link linkend="opt-security.acme.certs._name_.domain">domain</link> = "*.example.com";
224 <link linkend="opt-security.acme.certs._name_.dnsProvider">dnsProvider</link> = "rfc2136";
225 <link linkend="opt-security.acme.certs._name_.credentialsFile">credentialsFile</link> = "/var/lib/secrets/certs.secret";
226 # We don't need to wait for propagation since this is a local DNS server
227 <link linkend="opt-security.acme.certs._name_.dnsPropagationCheck">dnsPropagationCheck</link> = false;
228};
229</programlisting>
230
231 <para>
232 The <filename>dnskeys.conf</filename> and <filename>certs.secret</filename>
233 must be kept secure and thus you should not keep their contents in your
234 Nix config. Instead, generate them one time with these commands:
235 </para>
236
237<programlisting>
238mkdir -p /var/lib/secrets
239tsig-keygen rfc2136key.example.com > /var/lib/secrets/dnskeys.conf
240chown named:root /var/lib/secrets/dnskeys.conf
241chmod 400 /var/lib/secrets/dnskeys.conf
242
243# Copy the secret value from the dnskeys.conf, and put it in
244# RFC2136_TSIG_SECRET below
245
246cat > /var/lib/secrets/certs.secret << EOF
247RFC2136_NAMESERVER='127.0.0.1:53'
248RFC2136_TSIG_ALGORITHM='hmac-sha256.'
249RFC2136_TSIG_KEY='rfc2136key.example.com'
250RFC2136_TSIG_SECRET='your secret key'
251EOF
252chmod 400 /var/lib/secrets/certs.secret
253</programlisting>
254
255 <para>
256 Now you're all set to generate certs! You should monitor the first invokation
257 by running <literal>systemctl start acme-example.com.service &
258 journalctl -fu acme-example.com.service</literal> and watching its log output.
259 </para>
260 </section>
261 <section xml:id="module-security-acme-regenerate">
262 <title>Regenerating certificates</title>
263
264 <para>
265 Should you need to regenerate a particular certificate in a hurry, such
266 as when a vulnerability is found in Let's Encrypt, there is now a convenient
267 mechanism for doing so. Running
268 <literal>systemctl clean --what=state acme-example.com.service</literal>
269 will remove all certificate files and the account data for the given domain,
270 allowing you to then <literal>systemctl start acme-example.com.service</literal>
271 to generate fresh ones.
272 </para>
273 </section>
274 <section xml:id="module-security-acme-fix-jws">
275 <title>Fixing JWS Verification error</title>
276
277 <para>
278 It is possible that your account credentials file may become corrupt and need
279 to be regenerated. In this scenario lego will produce the error <literal>JWS verification error</literal>.
280 The solution is to simply delete the associated accounts file and
281 re-run the affected service(s).
282 </para>
283
284<programlisting>
285# Find the accounts folder for the certificate
286systemctl cat acme-example.com.service | grep -Po 'accounts/[^:]*'
287export accountdir="$(!!)"
288# Move this folder to some place else
289mv /var/lib/acme/.lego/$accountdir{,.bak}
290# Recreate the folder using systemd-tmpfiles
291systemd-tmpfiles --create
292# Get a new account and reissue certificates
293# Note: Do this for all certs that share the same account email address
294systemctl start acme-example.com.service
295</programlisting>
296
297 </section>
298</chapter>