1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVE'
7    xmlns:xi="http://www.w3.org/2001/XInclude">
8  <refentryinfo>
9    <title>dnssec-trust-anchors.d</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>dnssec-trust-anchors.d</refentrytitle>
15    <manvolnum>5</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>dnssec-trust-anchors.d</refname>
20    <refname>systemd.positive</refname>
21    <refname>systemd.negative</refname>
22    <refpurpose>DNSSEC trust anchor configuration files</refpurpose>
23  </refnamediv>
24
25  <refsynopsisdiv>
26    <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para>
27    <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para>
28    <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para>
29    <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para>
30    <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para>
31    <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para>
32  </refsynopsisdiv>
33
34  <refsect1>
35    <title>Description</title>
36
37    <para>The DNSSEC trust anchor configuration files define positive
38    and negative trust anchors
39    <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
40    bases DNSSEC integrity proofs on.</para>
41  </refsect1>
42
43  <refsect1>
44    <title>Positive Trust Anchors</title>
45
46    <para>Positive trust anchor configuration files contain <constant class='dns'>DNSKEY</constant> and
47    <constant class='dns'>DS</constant> resource record definitions to use as base for DNSSEC integrity
48    proofs. See <ulink url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, Section 4.4</ulink>
49    for more information about DNSSEC trust anchors.</para>
50
51    <para>Positive trust anchors are read from files with the suffix
52    <filename>.positive</filename> located in
53    <filename>/etc/dnssec-trust-anchors.d/</filename>,
54    <filename>/run/dnssec-trust-anchors.d/</filename> and
55    <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These
56    directories are searched in the specified order, and a trust
57    anchor file of the same name in an earlier path overrides a trust
58    anchor files in a later path. To disable a trust anchor file
59    shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename>
60    it is sufficient to provide an identically-named file in
61    <filename>/etc/dnssec-trust-anchors.d/</filename> or
62    <filename>/run/dnssec-trust-anchors.d/</filename> that is either
63    empty or a symlink to <filename>/dev/null</filename> ("masked").</para>
64
65    <para>Positive trust anchor files are simple text files resembling DNS zone files, as documented in
66    <ulink url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section 5</ulink>. One <constant
67    class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> resource record may be listed per
68    line. Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored, which
69    may be used for commenting. A <constant class='dns'>DS</constant> resource record is specified like in the
70    following example:</para>
71
72    <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting>
73
74    <para>The first word specifies the domain, use
75    <literal>.</literal> for the root domain. The domain may be
76    specified with or without trailing dot, which is considered
77    equivalent. The second word must be <literal>IN</literal> the
78    third word <literal>DS</literal>. The following words specify the
79    key tag, signature algorithm, digest algorithm, followed by the
80    hex-encoded key fingerprint. See <ulink
81    url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034,
82    Section 5</ulink> for details about the precise syntax and meaning
83    of these fields.</para>
84
85    <para>Alternatively, <constant class='dns'>DNSKEY</constant> resource records may be used to define trust
86    anchors, like in the following example:</para>
87
88    <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting>
89
90    <para>The first word specifies the domain again, the second word must be <literal>IN</literal>, followed
91    by <literal>DNSKEY</literal>. The subsequent words encode the <constant class='dns'>DNSKEY</constant>
92    flags, protocol and algorithm fields, followed by the key data encoded in Base64. See <ulink
93    url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, Section 2</ulink> for details about the
94    precise syntax and meaning of these fields.</para>
95
96    <para>If multiple <constant class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> records
97    are defined for the same domain (possibly even in different trust anchor files), all keys are used and
98    are considered equivalent as base for DNSSEC proofs.</para>
99
100    <para>Note that <filename>systemd-resolved</filename> will
101    automatically use a built-in trust anchor key for the Internet
102    root domain if no positive trust anchors are defined for the root
103    domain. In most cases it is hence unnecessary to define an
104    explicit key with trust anchor files. The built-in key is disabled
105    as soon as at least one trust anchor key for the root domain is
106    defined in trust anchor files.</para>
107
108    <para>It is generally recommended to encode trust anchors in <constant class='dns'>DS</constant> resource
109    records, rather than <constant class='dns'>DNSKEY</constant> resource records.</para>
110
111    <para>If a trust anchor specified via a <constant class='dns'>DS</constant> record is found revoked it is
112    automatically removed from the trust anchor database for the runtime. See <ulink
113    url="https://tools.ietf.org/html/rfc5011">RFC 5011</ulink> for details about revoked trust anchors. Note
114    that <filename>systemd-resolved</filename> will not update its trust anchor database from DNS servers
115    automatically. Instead, it is recommended to update the resolver software or update the new trust anchor
116    via adding in new trust anchor files.</para>
117
118    <para>The current DNSSEC trust anchor for the Internet's root
119    domain is available at the <ulink
120    url="https://data.iana.org/root-anchors/root-anchors.xml">IANA
121    Trust Anchor and Keys</ulink> page.</para>
122  </refsect1>
123
124  <refsect1>
125    <title>Negative Trust Anchors</title>
126
127    <para>Negative trust anchors define domains where DNSSEC validation shall be turned
128    off. Negative trust anchor files are found at the same location as positive trust anchor files,
129    and follow the same overriding rules. They are text files with the
130    <filename>.negative</filename> suffix. Empty lines and lines whose first character is
131    <literal>;</literal> are ignored. Each line specifies one domain name which is the root of a DNS
132    subtree where validation shall be disabled. For example:</para>
133
134    <programlisting># Reverse IPv4 mappings
13510.in-addr.arpa
13616.172.in-addr.arpa
137168.192.in-addr.arpa
138...
139# Some custom domains
140prod
141stag
142</programlisting>
143
144    <para>Negative trust anchors are useful to support private DNS
145    subtrees that are not referenced from the Internet DNS hierarchy,
146    and not signed.</para>
147
148    <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC
149    7646</ulink> for details on negative trust anchors.</para>
150
151    <para>If no negative trust anchor files are configured a built-in
152    set of well-known private DNS zone domains is used as negative
153    trust anchors.</para>
154
155    <para>It is also possibly to define per-interface negative trust
156    anchors using the <varname>DNSSECNegativeTrustAnchors=</varname>
157    setting in
158    <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
159    files.</para>
160  </refsect1>
161
162  <refsect1>
163      <title>See Also</title>
164      <para>
165      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
166      <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
167      <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
168      <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
169      </para>
170  </refsect1>
171
172</refentry>
173