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