man/dnssec-trust-anchors.d.xml

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