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