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+ -->
   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 DNSKEY and
  47     DS resource record definitions to use as base for DNSSEC integrity
  48     proofs. See <ulink
  49     url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035,
  50     Section 4.4</ulink> for more information about DNSSEC trust
  51     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
  68     DNS zone files, as documented in <ulink
  69     url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section
  70     5</ulink>. One DS or DNSKEY resource record may be listed per
  71     line. Empty lines and lines starting with a semicolon
  72     (<literal>;</literal>) are ignored and considered comments. A DS
  73     resource record is specified like in the following example:</para>
  74
  75     <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting>
  76
  77     <para>The first word specifies the domain, use
  78     <literal>.</literal> for the root domain. The domain may be
  79     specified with or without trailing dot, which is considered
  80     equivalent. The second word must be <literal>IN</literal> the
  81     third word <literal>DS</literal>. The following words specify the
  82     key tag, signature algorithm, digest algorithm, followed by the
  83     hex-encoded key fingerprint. See <ulink
  84     url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034,
  85     Section 5</ulink> for details about the precise syntax and meaning
  86     of these fields.</para>
  87
  88     <para>Alternatively, DNSKEY resource records may be used to define
  89     trust anchors, like in the following example:</para>
  90
  91     <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting>
  92
  93     <para>The first word specifies the domain again, the second word
  94     must be <literal>IN</literal>, followed by
  95     <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY
  96     flags, protocol and algorithm fields, followed by the key data
  97     encoded in Base64. See <ulink
  98     url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034,
  99     Section 2</ulink> for details about the precise syntax and meaning
 100     of these fields.</para>
 101
 102     <para>If multiple DS or DNSKEY records are defined for the same
 103     domain (possibly even in different trust anchor files), all keys
 104     are used and are considered equivalent as base for DNSSEC
 105     proofs.</para>
 106
 107     <para>Note that <filename>systemd-resolved</filename> will
 108     automatically use a built-in trust anchor key for the Internet
 109     root domain if no positive trust anchors are defined for the root
 110     domain. In most cases it is hence unnecessary to define an
 111     explicit key with trust anchor files. The built-in key is disabled
 112     as soon as at least one trust anchor key for the root domain is
 113     defined in trust anchor files.</para>
 114
 115     <para>It is generally recommended to encode trust anchors in DS
 116     resource records, rather than DNSKEY resource records.</para>
 117
 118     <para>If a trust anchor specified via a DS record is found revoked
 119     it is automatically removed from the trust anchor database for the
 120     runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC
 121     5011</ulink> for details about revoked trust anchors. Note that
 122     <filename>systemd-resolved</filename> will not update its trust
 123     anchor database from DNS servers automatically. Instead, it is
 124     recommended to update the resolver software or update the new
 125     trust anchor via adding in new trust anchor files.</para>
 126
 127     <para>The current DNSSEC trust anchor for the Internet's root
 128     domain is available at the <ulink
 129     url="https://data.iana.org/root-anchors/root-anchors.xml">IANA
 130     Trust Anchor and Keys</ulink> page.</para>
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>Negative Trust Anchors</title>
 135
 136     <para>Negative trust anchors define domains where DNSSEC validation shall be turned
 137     off. Negative trust anchor files are found at the same location as positive trust anchor files,
 138     and follow the same overriding rules. They are text files with the
 139     <filename>.negative</filename> suffix. Empty lines and lines whose first character is
 140     <literal>;</literal> are ignored. Each line specifies one domain name which is the root of a DNS
 141     subtree where validation shall be disabled.</para>
 142
 143     <para>Negative trust anchors are useful to support private DNS
 144     subtrees that are not referenced from the Internet DNS hierarchy,
 145     and not signed.</para>
 146
 147     <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC
 148     7646</ulink> for details on negative trust anchors.</para>
 149
 150     <para>If no negative trust anchor files are configured a built-in
 151     set of well-known private DNS zone domains is used as negative
 152     trust anchors.</para>
 153
 154     <para>It is also possibly to define per-interface negative trust
 155     anchors using the <varname>DNSSECNegativeTrustAnchors=</varname>
 156     setting in
 157     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 158     files.</para>
 159   </refsect1>
 160
 161   <refsect1>
 162       <title>See Also</title>
 163       <para>
 164       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 165       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 166       <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 167       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 168       </para>
 169   </refsect1>
 170
 171 </refentry>