Merge pull request #2269 from poettering/dnssec11

Eleventh DNSSEC patch set

1 files changed, 58 insertions, 0 deletions

diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml
index 4680b6a4e5..8473bbe5c9 100644
--- a/man/resolved.conf.xml
+++ b/man/resolved.conf.xml
@@ -124,6 +124,63 @@
         global setting is on.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>DNSSEC=</varname></term>
+        <listitem><para>Takes a boolean argument or
+        <literal>downgrade-ok</literal>. If true all DNS lookups are
+        DNSSEC-validated locally. If a response for a lookup request
+        is detected invalid this is returned as lookup failure to
+        applications. Note that this mode requires a DNS server that
+        supports DNSSEC. If the DNS server does not properly support
+        DNSSEC all validations will fail. If set to
+        <literal>downgrade-ok</literal> DNSSEC validation is
+        attempted, but if the server does not support DNSSEC properly,
+        DNSSEC mode is automatically disabled. Note that this mode
+        makes DNSSEC validation vulnerable to "downgrade" attacks,
+        where an attacker might be able to trigger a downgrade to
+        non-DNSSEC mode by synthesizing a DNS response that suggests
+        DNSSEC was not supported. If set to false, DNS lookups are not
+        DNSSEC validated.</para>
+
+        <para>Note that DNSSEC validation requires retrieval of
+        additional DNS data, and thus results in a small DNS look-up
+        time penalty.</para>
+
+        <para>DNSSEC requires knowledge of "trust anchors" to prove
+        data integrity. The trust anchor for the Internet root domain
+        is built into the resolver, additional trust anchors may be
+        defined with
+        <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        Trust anchors may change in regular intervals, and old trust
+        anchors may be revoked. In such a case DNSSEC validation is
+        not possible until new trust anchors are configured locally or
+        the resolver software package is updated with the new root
+        trust anchor. In effect, when the built-in trust anchor is
+        revoked and <varname>DNSSEC=</varname> is true, all further
+        lookups will fail, as it cannot be proved anymore whether
+        lookups are correctly signed, or validly unsigned. If
+        <varname>DNSSEC=</varname> is set to
+        <literal>downgrade-ok</literal> the resolver will
+        automatically turn of DNSSEC validation in such a case.</para>
+
+        <para>Client programs looking up DNS data will be informed
+        whether lookups could be verified using DNSSEC, or whether the
+        returned data could not be verified (either because the data
+        was found unsigned in the DNS, or the DNS server did not
+        support DNSSEC or no appropriate trust anchors were known). In
+        the latter case it is assumed that client programs employ a
+        secondary scheme to validate the returned DNS data, should
+        this be required.</para>
+
+        <para>It is recommended to set <varname>DNSSEC=</varname> to
+        true on systems where it is kown that the DNS server supports
+        DNSSEC correctly, and where software or trust anchor updates
+        happen regularly. On other systems it is recommended to set
+        <varname>DNSSEC=</varname> to
+        <literal>missing-ok</literal>.</para>
+        </listitem>
+      </varlistentry>
+
     </variablelist>
   </refsect1>
 
@@ -133,6 +190,7 @@
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry>
       </para>
   </refsect1>