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

<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  SPDX-License-Identifier: LGPL-2.1+
-->

<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>

    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Lennart</firstname>
        <surname>Poettering</surname>
        <email>lennart@poettering.net</email>
      </author>
    </authorgroup>
  </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 DNSKEY and
    DS 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 DS or DNSKEY resource record may be listed per
    line. Empty lines and lines starting with a semicolon
    (<literal>;</literal>) are ignored and considered comments. A DS
    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, DNSKEY 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 DNSKEY
    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 DS or DNSKEY 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 DS
    resource records, rather than DNSKEY resource records.</para>

    <para>If a trust anchor specified via a DS 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.</para>

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