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