man/dnssec-trust-anchors.d.xml

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