man: add basic documentation for resolved.conf's DNSSEC= switch

diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml
index 4680b6a..857a93b 100644 (file)
--- a/man/resolved.conf.xml
+++ b/man/resolved.conf.xml
@@ -124,6 +124,61 @@
         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. However, 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>