dnssec-trust-anchors.d.xml revision 30c778094b90a637c6691c462a66df81eeb865b5
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering This file is part of systemd.
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering Copyright 2016 Lennart Poettering
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering systemd is free software; you can redistribute it and/or modify it
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering under the terms of the GNU Lesser General Public License as published by
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering the Free Software Foundation; either version 2.1 of the License, or
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering (at your option) any later version.
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering systemd is distributed in the hope that it will be useful, but
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering Lesser General Public License for more details.
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering You should have received a copy of the GNU Lesser General Public License
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering<refentry id="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVED'
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering xmlns:xi="http://www.w3.org/2001/XInclude">
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <refentryinfo>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering </authorgroup>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering </refentryinfo>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <refentrytitle>dnssec-trust-anchors.d</refentrytitle>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <refname>dnssec-trust-anchors.d</refname>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <refpurpose>DNSSEC trust anchor configuration files</refpurpose>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <refsynopsisdiv>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering </refsynopsisdiv>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>The DNSSEC trust anchor configuration files define positive
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering and negative trust anchors
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering bases DNSSEC integrity proofs on.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>Positive trust anchor configuration files contain DNSKEY and
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering DS resource record definitions to use as base for DNSSEC integrity
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering proofs. See <ulink
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035,
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering Section 4.4</ulink> for more information about DNSSEC trust
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering anchors.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>Positive trust anchors are read from files with the suffix
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <filename>.positive</filename> located in
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <filename>/etc/dnssec-trust-anchors.d/</filename>,
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <filename>/run/dnssec-trust-anchors.d/</filename> and
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering directories are searched in the specified order, and a trust
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering anchor file of the same name in an earlier path overrides a trust
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering anchor files in a later path. To disable a trust anchor file
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering it is sufficient to provide an identically-named file in
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <filename>/etc/dnssec-trust-anchors.d/</filename> or
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <filename>/run/dnssec-trust-anchors.d/</filename> that is either
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering empty or a symlink to <filename>/dev/null</filename> ("masked").</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>Positive trust anchor files are simple text files resembling
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering DNS zone files, as documented in <ulink
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering 5</ulink>. One DS or DNSKEY resource record may be listed per
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering line. Empty lines and lines starting with a semicolon
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering (<literal>;</literal>) are ignored and considered comments. A DS
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering resource record is specified like in the following example:</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>The first word specifies the domain, use
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <literal>.</literal> for the root domain. The domain may be
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering specified with or without trailing dot, which is considered
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering equivalent. The second word must be <literal>IN</literal> the
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering third word <literal>DS</literal>. The following words specify the
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering key tag, signature algorithm, digest algorithm, followed by the
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering hex-encoded key fingerprint. See <ulink
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034,
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering Section 5</ulink> for details about the precise syntax and meaning
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering of these fields.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>Alternatively, DNSKEY resource records may be used to define
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering trust anchors, like in the following example:</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>The first word specifies the domain again, the second word
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering must be <literal>IN</literal>, followed by
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering flags, protocol and algorithm fields, followed by the key data
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering encoded in Base64. See See <ulink
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034,
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering Section 2</ulink> for details about the precise syntax and meaning
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering of these fields.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>If multiple DS or DNSKEY records are defined for the same
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering domain (possibly even in different trust anchor files), all keys
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering are used and are considered equivalent as base for DNSSEC
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering proofs.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>Note that <filename>systemd-resolved</filename> will
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering automatically use a built-in trust anchor key for the Internet
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering root domain if no positive trust anchors are defined for the root
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering domain. In most cases it is hence unnecessary to define an
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering explicit key with trust anchor files. The built-in key is disabled
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering as soon as at least one trust anchor key for the root domain is
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering defined in trust anchor files.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>It is generally recommended to encode trust anchors in DS
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering resource records, rather than DNSKEY resource records.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>If a trust anchor specified via a DS record is found revoked
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering it is automatically removed from the trust anchor database for the
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering 5011</ulink> for details about revoked trust anchors. Note that
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <filename>systemd-resolved</filename> will not update its trust
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering anchor database from DNS servers automatically. Instead, it is
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering recommended to update the resolver software or update the new
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering trust anchor via adding in new trust anchor files.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>The current DNSSEC trust anchor for the Internet's root
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering domain is available a the <ulink
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering url="https://data.iana.org/root-anchors/root-anchors.xml">IANA
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering Trust Anchor and Keys</ulink> page.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>Negative trust anchors define domains where DNSSEC
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering validation shall be turned off. Negative trust anchor files are
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering found at the same location as positive trust anchor files, and
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering follow the same overriding rules. They are text files with the
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <filename>.negative</filename> suffix. Empty lines and lines whose
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering first character is <literal>;</literal> are ignored. Each line
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering specifies one domain name where DNSSEC validation shall be
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering disabled on.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para>Negative trust anchors are useful to support private DNS
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering subtrees that are not referenced from the Internet DNS hierarchy,
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering and not signed.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering 7646</ulink> for details on negative trust anchors.</para>
30c778094b90a637c6691c462a66df81eeb865b5Lennart Poettering <para>If no negative trust anchor files are configured a built-in
30c778094b90a637c6691c462a66df81eeb865b5Lennart Poettering set of well-known private DNS zone domains is used as negative
30c778094b90a637c6691c462a66df81eeb865b5Lennart Poettering trust anchors.</para>
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>