]>
Commit | Line | Data |
---|---|---|
b5a8703f LP |
1 | <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
4 | ||
5 | <!-- | |
572eb058 ZJS |
6 | SPDX-License-Identifier: LGPL-2.1+ |
7 | ||
b5a8703f LP |
8 | This file is part of systemd. |
9 | ||
10 | Copyright 2016 Lennart Poettering | |
11 | ||
12 | systemd is free software; you can redistribute it and/or modify it | |
13 | under the terms of the GNU Lesser General Public License as published by | |
14 | the Free Software Foundation; either version 2.1 of the License, or | |
15 | (at your option) any later version. | |
16 | ||
17 | systemd is distributed in the hope that it will be useful, but | |
18 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
20 | Lesser General Public License for more details. | |
21 | ||
22 | You should have received a copy of the GNU Lesser General Public License | |
23 | along with systemd; If not, see <http://www.gnu.org/licenses/>. | |
24 | --> | |
25 | ||
1ec57f33 | 26 | <refentry id="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVE' |
b5a8703f LP |
27 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
28 | <refentryinfo> | |
29 | <title>dnssec-trust-anchors.d</title> | |
30 | <productname>systemd</productname> | |
31 | ||
32 | <authorgroup> | |
33 | <author> | |
34 | <contrib>Developer</contrib> | |
35 | <firstname>Lennart</firstname> | |
36 | <surname>Poettering</surname> | |
37 | <email>lennart@poettering.net</email> | |
38 | </author> | |
39 | </authorgroup> | |
40 | </refentryinfo> | |
41 | ||
42 | <refmeta> | |
43 | <refentrytitle>dnssec-trust-anchors.d</refentrytitle> | |
44 | <manvolnum>5</manvolnum> | |
45 | </refmeta> | |
46 | ||
47 | <refnamediv> | |
48 | <refname>dnssec-trust-anchors.d</refname> | |
49 | <refname>systemd.positive</refname> | |
50 | <refname>systemd.negative</refname> | |
51 | <refpurpose>DNSSEC trust anchor configuration files</refpurpose> | |
52 | </refnamediv> | |
53 | ||
54 | <refsynopsisdiv> | |
55 | <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para> | |
56 | <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para> | |
57 | <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para> | |
58 | <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para> | |
59 | <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para> | |
60 | <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para> | |
61 | </refsynopsisdiv> | |
62 | ||
63 | <refsect1> | |
64 | <title>Description</title> | |
65 | ||
66 | <para>The DNSSEC trust anchor configuration files define positive | |
67 | and negative trust anchors | |
68 | <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
69 | bases DNSSEC integrity proofs on.</para> | |
70 | </refsect1> | |
71 | ||
72 | <refsect1> | |
73 | <title>Positive Trust Anchors</title> | |
74 | ||
75 | <para>Positive trust anchor configuration files contain DNSKEY and | |
76 | DS resource record definitions to use as base for DNSSEC integrity | |
77 | proofs. See <ulink | |
78 | url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, | |
79 | Section 4.4</ulink> for more information about DNSSEC trust | |
80 | anchors.</para> | |
81 | ||
82 | <para>Positive trust anchors are read from files with the suffix | |
83 | <filename>.positive</filename> located in | |
84 | <filename>/etc/dnssec-trust-anchors.d/</filename>, | |
85 | <filename>/run/dnssec-trust-anchors.d/</filename> and | |
86 | <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These | |
87 | directories are searched in the specified order, and a trust | |
88 | anchor file of the same name in an earlier path overrides a trust | |
89 | anchor files in a later path. To disable a trust anchor file | |
90 | shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename> | |
91 | it is sufficient to provide an identically-named file in | |
92 | <filename>/etc/dnssec-trust-anchors.d/</filename> or | |
93 | <filename>/run/dnssec-trust-anchors.d/</filename> that is either | |
94 | empty or a symlink to <filename>/dev/null</filename> ("masked").</para> | |
95 | ||
96 | <para>Positive trust anchor files are simple text files resembling | |
97 | DNS zone files, as documented in <ulink | |
98 | url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section | |
99 | 5</ulink>. One DS or DNSKEY resource record may be listed per | |
100 | line. Empty lines and lines starting with a semicolon | |
101 | (<literal>;</literal>) are ignored and considered comments. A DS | |
102 | resource record is specified like in the following example:</para> | |
103 | ||
104 | <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting> | |
105 | ||
106 | <para>The first word specifies the domain, use | |
107 | <literal>.</literal> for the root domain. The domain may be | |
108 | specified with or without trailing dot, which is considered | |
109 | equivalent. The second word must be <literal>IN</literal> the | |
110 | third word <literal>DS</literal>. The following words specify the | |
111 | key tag, signature algorithm, digest algorithm, followed by the | |
112 | hex-encoded key fingerprint. See <ulink | |
113 | url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034, | |
114 | Section 5</ulink> for details about the precise syntax and meaning | |
115 | of these fields.</para> | |
116 | ||
117 | <para>Alternatively, DNSKEY resource records may be used to define | |
118 | trust anchors, like in the following example:</para> | |
119 | ||
120 | <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting> | |
121 | ||
122 | <para>The first word specifies the domain again, the second word | |
123 | must be <literal>IN</literal>, followed by | |
124 | <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY | |
125 | flags, protocol and algorithm fields, followed by the key data | |
b8e1d4d1 | 126 | encoded in Base64. See <ulink |
b5a8703f LP |
127 | url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, |
128 | Section 2</ulink> for details about the precise syntax and meaning | |
129 | of these fields.</para> | |
130 | ||
131 | <para>If multiple DS or DNSKEY records are defined for the same | |
132 | domain (possibly even in different trust anchor files), all keys | |
133 | are used and are considered equivalent as base for DNSSEC | |
134 | proofs.</para> | |
135 | ||
136 | <para>Note that <filename>systemd-resolved</filename> will | |
137 | automatically use a built-in trust anchor key for the Internet | |
138 | root domain if no positive trust anchors are defined for the root | |
139 | domain. In most cases it is hence unnecessary to define an | |
140 | explicit key with trust anchor files. The built-in key is disabled | |
141 | as soon as at least one trust anchor key for the root domain is | |
142 | defined in trust anchor files.</para> | |
143 | ||
144 | <para>It is generally recommended to encode trust anchors in DS | |
145 | resource records, rather than DNSKEY resource records.</para> | |
146 | ||
147 | <para>If a trust anchor specified via a DS record is found revoked | |
148 | it is automatically removed from the trust anchor database for the | |
149 | runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC | |
150 | 5011</ulink> for details about revoked trust anchors. Note that | |
151 | <filename>systemd-resolved</filename> will not update its trust | |
152 | anchor database from DNS servers automatically. Instead, it is | |
153 | recommended to update the resolver software or update the new | |
154 | trust anchor via adding in new trust anchor files.</para> | |
155 | ||
156 | <para>The current DNSSEC trust anchor for the Internet's root | |
b8e1d4d1 | 157 | domain is available at the <ulink |
b5a8703f LP |
158 | url="https://data.iana.org/root-anchors/root-anchors.xml">IANA |
159 | Trust Anchor and Keys</ulink> page.</para> | |
160 | </refsect1> | |
161 | ||
162 | <refsect1> | |
163 | <title>Negative Trust Anchors</title> | |
164 | ||
e788ef48 ZJS |
165 | <para>Negative trust anchors define domains where DNSSEC validation shall be turned |
166 | off. Negative trust anchor files are found at the same location as positive trust anchor files, | |
167 | and follow the same overriding rules. They are text files with the | |
168 | <filename>.negative</filename> suffix. Empty lines and lines whose first character is | |
169 | <literal>;</literal> are ignored. Each line specifies one domain name which is the root of a DNS | |
170 | subtree where validation shall be disabled.</para> | |
b5a8703f LP |
171 | |
172 | <para>Negative trust anchors are useful to support private DNS | |
173 | subtrees that are not referenced from the Internet DNS hierarchy, | |
174 | and not signed.</para> | |
175 | ||
176 | <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC | |
177 | 7646</ulink> for details on negative trust anchors.</para> | |
30c77809 LP |
178 | |
179 | <para>If no negative trust anchor files are configured a built-in | |
180 | set of well-known private DNS zone domains is used as negative | |
181 | trust anchors.</para> | |
8a516214 LP |
182 | |
183 | <para>It is also possibly to define per-interface negative trust | |
184 | anchors using the <varname>DNSSECNegativeTrustAnchors=</varname> | |
185 | setting in | |
186 | <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
187 | files.</para> | |
b5a8703f LP |
188 | </refsect1> |
189 | ||
190 | <refsect1> | |
191 | <title>See Also</title> | |
192 | <para> | |
193 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
194 | <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
8a516214 LP |
195 | <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
196 | <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
b5a8703f LP |
197 | </para> |
198 | </refsect1> | |
199 | ||
200 | </refentry> |