summaryrefslogtreecommitdiffstats
path: root/man/dnssec-trust-anchors.d.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/dnssec-trust-anchors.d.xml')
-rw-r--r--man/dnssec-trust-anchors.d.xml172
1 files changed, 172 insertions, 0 deletions
diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml
new file mode 100644
index 0000000..39b9515
--- /dev/null
+++ b/man/dnssec-trust-anchors.d.xml
@@ -0,0 +1,172 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVE'
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refentryinfo>
+ <title>dnssec-trust-anchors.d</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>dnssec-trust-anchors.d</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>dnssec-trust-anchors.d</refname>
+ <refname>systemd.positive</refname>
+ <refname>systemd.negative</refname>
+ <refpurpose>DNSSEC trust anchor configuration files</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para>
+ <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para>
+ <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para>
+ <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para>
+ <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para>
+ <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>The DNSSEC trust anchor configuration files define positive
+ and negative trust anchors
+ <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ bases DNSSEC integrity proofs on.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Positive Trust Anchors</title>
+
+ <para>Positive trust anchor configuration files contain <constant class='dns'>DNSKEY</constant> and
+ <constant class='dns'>DS</constant> resource record definitions to use as base for DNSSEC integrity
+ proofs. See <ulink url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, Section 4.4</ulink>
+ for more information about DNSSEC trust anchors.</para>
+
+ <para>Positive trust anchors are read from files with the suffix
+ <filename>.positive</filename> located in
+ <filename>/etc/dnssec-trust-anchors.d/</filename>,
+ <filename>/run/dnssec-trust-anchors.d/</filename> and
+ <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These
+ directories are searched in the specified order, and a trust
+ anchor file of the same name in an earlier path overrides a trust
+ anchor files in a later path. To disable a trust anchor file
+ shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename>
+ it is sufficient to provide an identically-named file in
+ <filename>/etc/dnssec-trust-anchors.d/</filename> or
+ <filename>/run/dnssec-trust-anchors.d/</filename> that is either
+ empty or a symlink to <filename>/dev/null</filename> ("masked").</para>
+
+ <para>Positive trust anchor files are simple text files resembling DNS zone files, as documented in
+ <ulink url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section 5</ulink>. One <constant
+ class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> resource record may be listed per
+ line. Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored, which
+ may be used for commenting. A <constant class='dns'>DS</constant> resource record is specified like in the
+ following example:</para>
+
+ <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting>
+
+ <para>The first word specifies the domain, use
+ <literal>.</literal> for the root domain. The domain may be
+ specified with or without trailing dot, which is considered
+ equivalent. The second word must be <literal>IN</literal> the
+ third word <literal>DS</literal>. The following words specify the
+ key tag, signature algorithm, digest algorithm, followed by the
+ hex-encoded key fingerprint. See <ulink
+ url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034,
+ Section 5</ulink> for details about the precise syntax and meaning
+ of these fields.</para>
+
+ <para>Alternatively, <constant class='dns'>DNSKEY</constant> resource records may be used to define trust
+ anchors, like in the following example:</para>
+
+ <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting>
+
+ <para>The first word specifies the domain again, the second word must be <literal>IN</literal>, followed
+ by <literal>DNSKEY</literal>. The subsequent words encode the <constant class='dns'>DNSKEY</constant>
+ flags, protocol and algorithm fields, followed by the key data encoded in Base64. See <ulink
+ url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, Section 2</ulink> for details about the
+ precise syntax and meaning of these fields.</para>
+
+ <para>If multiple <constant class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> records
+ are defined for the same domain (possibly even in different trust anchor files), all keys are used and
+ are considered equivalent as base for DNSSEC proofs.</para>
+
+ <para>Note that <filename>systemd-resolved</filename> will
+ automatically use a built-in trust anchor key for the Internet
+ root domain if no positive trust anchors are defined for the root
+ domain. In most cases it is hence unnecessary to define an
+ explicit key with trust anchor files. The built-in key is disabled
+ as soon as at least one trust anchor key for the root domain is
+ defined in trust anchor files.</para>
+
+ <para>It is generally recommended to encode trust anchors in <constant class='dns'>DS</constant> resource
+ records, rather than <constant class='dns'>DNSKEY</constant> resource records.</para>
+
+ <para>If a trust anchor specified via a <constant class='dns'>DS</constant> record is found revoked it is
+ automatically removed from the trust anchor database for the runtime. See <ulink
+ url="https://tools.ietf.org/html/rfc5011">RFC 5011</ulink> for details about revoked trust anchors. Note
+ that <filename>systemd-resolved</filename> will not update its trust anchor database from DNS servers
+ automatically. Instead, it is recommended to update the resolver software or update the new trust anchor
+ via adding in new trust anchor files.</para>
+
+ <para>The current DNSSEC trust anchor for the Internet's root
+ domain is available at the <ulink
+ url="https://data.iana.org/root-anchors/root-anchors.xml">IANA
+ Trust Anchor and Keys</ulink> page.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Negative Trust Anchors</title>
+
+ <para>Negative trust anchors define domains where DNSSEC validation shall be turned
+ off. Negative trust anchor files are found at the same location as positive trust anchor files,
+ and follow the same overriding rules. They are text files with the
+ <filename>.negative</filename> suffix. Empty lines and lines whose first character is
+ <literal>;</literal> are ignored. Each line specifies one domain name which is the root of a DNS
+ subtree where validation shall be disabled. For example:</para>
+
+ <programlisting># Reverse IPv4 mappings
+10.in-addr.arpa
+16.172.in-addr.arpa
+168.192.in-addr.arpa
+...
+# Some custom domains
+prod
+stag
+</programlisting>
+
+ <para>Negative trust anchors are useful to support private DNS
+ subtrees that are not referenced from the Internet DNS hierarchy,
+ and not signed.</para>
+
+ <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC
+ 7646</ulink> for details on negative trust anchors.</para>
+
+ <para>If no negative trust anchor files are configured a built-in
+ set of well-known private DNS zone domains is used as negative
+ trust anchors.</para>
+
+ <para>It is also possibly to define per-interface negative trust
+ anchors using the <varname>DNSSECNegativeTrustAnchors=</varname>
+ setting in
+ <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ files.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>