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