man: add markup to dns resource record labels

[thirdparty/systemd.git] / man / dnssec-trust-anchors.d.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVE'
    xmlns:xi="http://www.w3.org/2001/XInclude">
  <refentryinfo>
    <title>dnssec-trust-anchors.d</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>dnssec-trust-anchors.d</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>dnssec-trust-anchors.d</refname>
    <refname>systemd.positive</refname>
    <refname>systemd.negative</refname>
    <refpurpose>DNSSEC trust anchor configuration files</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para>
    <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para>
    <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para>
    <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para>
    <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para>
    <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>The DNSSEC trust anchor configuration files define positive
    and negative trust anchors
    <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    bases DNSSEC integrity proofs on.</para>
  </refsect1>

  <refsect1>
    <title>Positive Trust Anchors</title>

    <para>Positive trust anchor configuration files contain <constant class='dns'>DNSKEY</constant> and
    <constant class='dns'>DS</constant> resource record definitions to use as base for DNSSEC integrity
    proofs. See <ulink url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, Section 4.4</ulink>
    for more information about DNSSEC trust anchors.</para>

    <para>Positive trust anchors are read from files with the suffix
    <filename>.positive</filename> located in
    <filename>/etc/dnssec-trust-anchors.d/</filename>,
    <filename>/run/dnssec-trust-anchors.d/</filename> and
    <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These
    directories are searched in the specified order, and a trust
    anchor file of the same name in an earlier path overrides a trust
    anchor files in a later path. To disable a trust anchor file
    shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename>
    it is sufficient to provide an identically-named file in
    <filename>/etc/dnssec-trust-anchors.d/</filename> or
    <filename>/run/dnssec-trust-anchors.d/</filename> that is either
    empty or a symlink to <filename>/dev/null</filename> ("masked").</para>

    <para>Positive trust anchor files are simple text files resembling DNS zone files, as documented in
    <ulink url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section 5</ulink>. One <constant
    class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> resource record may be listed per
    line. Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored, which
    may be used for commenting. A <consant class='dns'>DS</consant> resource record is specified like in the
    following example:</para>

    <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting>

    <para>The first word specifies the domain, use
    <literal>.</literal> for the root domain. The domain may be
    specified with or without trailing dot, which is considered
    equivalent. The second word must be <literal>IN</literal> the
    third word <literal>DS</literal>. The following words specify the
    key tag, signature algorithm, digest algorithm, followed by the
    hex-encoded key fingerprint. See <ulink
    url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034,
    Section 5</ulink> for details about the precise syntax and meaning
    of these fields.</para>

    <para>Alternatively, <constant class='dns'>DNSKEY</constant> resource records may be used to define trust
    anchors, like in the following example:</para>

    <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting>

    <para>The first word specifies the domain again, the second word must be <literal>IN</literal>, followed
    by <literal>DNSKEY</literal>. The subsequent words encode the <constant class='dns'>DNSKEY</constant>
    flags, protocol and algorithm fields, followed by the key data encoded in Base64. See <ulink
    url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, Section 2</ulink> for details about the
    precise syntax and meaning of these fields.</para>

    <para>If multiple <constant class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> records
    are defined for the same domain (possibly even in different trust anchor files), all keys are used and
    are considered equivalent as base for DNSSEC proofs.</para>

    <para>Note that <filename>systemd-resolved</filename> will
    automatically use a built-in trust anchor key for the Internet
    root domain if no positive trust anchors are defined for the root
    domain. In most cases it is hence unnecessary to define an
    explicit key with trust anchor files. The built-in key is disabled
    as soon as at least one trust anchor key for the root domain is
    defined in trust anchor files.</para>

    <para>It is generally recommended to encode trust anchors in <constant class='dns'>DS</constant> resource
    records, rather than <constant class='dns'>DNSKEY</constant> resource records.</para>

    <para>If a trust anchor specified via a <constant class='dns'>DS</constant> record is found revoked it is
    automatically removed from the trust anchor database for the runtime. See <ulink
    url="https://tools.ietf.org/html/rfc5011">RFC 5011</ulink> for details about revoked trust anchors. Note
    that <filename>systemd-resolved</filename> will not update its trust anchor database from DNS servers
    automatically. Instead, it is recommended to update the resolver software or update the new trust anchor
    via adding in new trust anchor files.</para>

    <para>The current DNSSEC trust anchor for the Internet's root
    domain is available at the <ulink
    url="https://data.iana.org/root-anchors/root-anchors.xml">IANA
    Trust Anchor and Keys</ulink> page.</para>
  </refsect1>

  <refsect1>
    <title>Negative Trust Anchors</title>

    <para>Negative trust anchors define domains where DNSSEC validation shall be turned
    off. Negative trust anchor files are found at the same location as positive trust anchor files,
    and follow the same overriding rules. They are text files with the
    <filename>.negative</filename> suffix. Empty lines and lines whose first character is
    <literal>;</literal> are ignored. Each line specifies one domain name which is the root of a DNS
    subtree where validation shall be disabled. For example:</para>

    <programlisting># Reverse IPv4 mappings
10.in-addr.arpa
16.172.in-addr.arpa
168.192.in-addr.arpa
...
# Some custom domains
prod
stag
</programlisting>

    <para>Negative trust anchors are useful to support private DNS
    subtrees that are not referenced from the Internet DNS hierarchy,
    and not signed.</para>

    <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC
    7646</ulink> for details on negative trust anchors.</para>

    <para>If no negative trust anchor files are configured a built-in
    set of well-known private DNS zone domains is used as negative
    trust anchors.</para>

    <para>It is also possibly to define per-interface negative trust
    anchors using the <varname>DNSSECNegativeTrustAnchors=</varname>
    setting in
    <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    files.</para>
  </refsect1>

  <refsect1>
      <title>See Also</title>
      <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
      </para>
  </refsect1>

</refentry>