From: Otto Date: Wed, 27 Jan 2021 08:46:16 +0000 (+0100) Subject: Document CD bit better, reference detailed DNSSEC docs from settings X-Git-Tag: dnsdist-1.6.0-alpha1~12^2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=0f1680b96984c36144260a531af18e39e54cb3c1;p=thirdparty%2Fpdns.git Document CD bit better, reference detailed DNSSEC docs from settings and reformat two item lists. --- diff --git a/pdns/recursordist/docs/dnssec.rst b/pdns/recursordist/docs/dnssec.rst index a27342fbc3..4c937e37be 100644 --- a/pdns/recursordist/docs/dnssec.rst +++ b/pdns/recursordist/docs/dnssec.rst @@ -2,10 +2,6 @@ DNSSEC in the PowerDNS Recursor =============================== As of 4.0.0, the PowerDNS Recursor has support for DNSSEC processing and experimental support for DNSSEC validation. -.. warning:: - The DNSSEC implementation in the PowerDNS Recursor 4.0.x is known to have deficiencies due to its original design. - When doing DNSSEC validation, ensure you are running 4.1.0 or later which has a fully reworked (and correct) DNSSEC implementation. - DNSSEC settings --------------- The PowerDNS Recursor has 5 different levels of DNSSEC processing, which can be set with the :ref:`setting-dnssec` setting in the ``recursor.conf``. @@ -15,7 +11,6 @@ In order from least to most processing, these are: ^^^^^^^ In this mode, **no** DNSSEC processing takes place. The PowerDNS Recursor will not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the DO and AD bits in queries. -In this mode, the behaviour is equal to the PowerDNS Recursor 3.X. ``process-no-validate`` ^^^^^^^^^^^^^^^^^^^^^^^ @@ -39,42 +34,43 @@ Responses to client queries are the same as with `process`_. ``validate`` ^^^^^^^^^^^^ The highest mode of DNSSEC processing. -In this mode, all queries will be be validated and will be answered with a SERVFAIL in case of bogus data, regardless of the client's request. +In this mode, all responses will be be validated and and queries will be answered with a SERVFAIL in case of bogus data, even if the client did not request validation by setting the AD or DO bit. + +**Note**: the CD-bit is honored for ``process``, ``log-fail`` and +``validate``. This mean that even if validation fails, results are +returned if the CD-bit is set by the client. For ``log-fail``, failures will be logged too. What, when? ^^^^^^^^^^^ The descriptions above are a bit terse, here's a table describing different scenarios with regards to the ``dnssec`` mode. -+--------------+---------+-------------------------+---------------+---------------+---------------+ -| | ``off`` | ``process-no-validate`` | ``process`` | ``log-fail`` | ``validate`` | -+==============+=========+=========================+===============+===============+===============+ -| Perform | No | No | Only on +AD | Always (logs | Always | -| validation | | | or +DO from | result) | | -| | | | client | | | -+--------------+---------+-------------------------+---------------+---------------+---------------+ -| SERVFAIL on | No | No | Only on +AD | Only on +AD | Always | -| bogus | | | or +DO from | or +DO from | | -| | | | client | client | | -+--------------+---------+-------------------------+---------------+---------------+---------------+ -| AD in | Never | Never | Only on +AD | Only on +AD | Only on +AD | -| response on | | | or +DO from | or +DO from | or +DO from | -| authenticate | | | client | client | client | -| d | | | | | | -| data | | | | | | -+--------------+---------+-------------------------+---------------+---------------+---------------+ -| RRSIGs/NSECs | No | Yes | Yes | Yes | Yes | -| in answer on | | | | | | -| +DO from | | | | | | -| client | | | | | | -+--------------+---------+-------------------------+---------------+---------------+---------------+ ++---------------+---------+-------------------------+---------------+---------------+---------------+ +| | ``off`` | ``process-no-validate`` | ``process`` | ``log-fail`` | ``validate`` | ++===============+=========+=========================+===============+===============+===============+ +| Perform | No | No | Only on +AD | Always (logs | Always | +| validation | | | or +DO from | result) | | +| | | | client | | | ++---------------+---------+-------------------------+---------------+---------------+---------------+ +| SERVFAIL on | No | No | Only on +AD | Only on +AD | If -CD | +| bogus | | | or +DO and | or +DO and | from client | +| | | | -CD from | -CD from | | +| | | | client | client | | ++---------------+---------+-------------------------+---------------+---------------+---------------+ +| AD in | Never | Never | Only on +AD | Only on +AD | Only on +AD | +| response on | | | or +DO from | or +DO from | or +DO from | +| authenticated | | | client | client | client | +| data | | | | | | ++---------------+---------+-------------------------+---------------+---------------+---------------+ +| RRSIGs/NSECs | No | Yes | Yes | Yes | Yes | +| in answer on | | | | | | +| +DO from | | | | | | +| client | | | | | | ++---------------+---------+-------------------------+---------------+---------------+---------------+ **Note**: the ``dig`` tool sets the AD-bit in the query. This might lead to unexpected query results when testing. Set ``+noad`` on the ``dig`` commandline when this is the case. -**Note**: the CD-bit is honored correctly for ``process`` and -``validate``. For ``log-fail``, failures will be logged too. - Trust Anchor Management ----------------------- In the PowerDNS Recursor, both positive and negative trust anchors can be configured during startup (from a persistent configuration file) and at runtime (which is volatile). diff --git a/pdns/recursordist/docs/settings.rst b/pdns/recursordist/docs/settings.rst index 27495cfb1c..acb792ed09 100644 --- a/pdns/recursordist/docs/settings.rst +++ b/pdns/recursordist/docs/settings.rst @@ -405,31 +405,22 @@ See :doc:`dns64` for more flexible but slower alternatives using Lua. - One of ``off``, ``process-no-validate``, ``process``, ``log-fail``, ``validate``, String - Default: ``process-no-validate`` -Set the mode for DNSSEC processing: - -off -^^^ -No DNSSEC processing whatsoever. -Ignore DO-bits in queries, don't request any DNSSEC information from authoritative servers. -This behaviour is similar to PowerDNS Recursor pre-4.0. - -process-no-validate -^^^^^^^^^^^^^^^^^^^ -Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. -Don't do any validation. - -process -^^^^^^^ -Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. -Do validation for clients that request it (by means of the AD- bit or DO-bit in the query). - -log-fail -^^^^^^^^ -Similar behaviour to ``process``, but validate RRSIGs on responses and log bogus responses. - -validate -^^^^^^^^ -Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses. +Set the mode for DNSSEC processing, as detailed in :doc:`dnssec`. + +``off`` + No DNSSEC processing whatsoever. + Ignore DO-bits in queries, don't request any DNSSEC information from authoritative servers. + This behaviour is similar to PowerDNS Recursor pre-4.0. +``process-no-validate`` + Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. + Don't do any validation. +``process`` + Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. + Do validation for clients that request it (by means of the AD- bit or DO-bit in the query). +``log-fail`` + Similar behaviour to ``process``, but validate RRSIGs on responses and log bogus responses. +``validate`` + Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses. .. _setting-dnssec-log-bogus: @@ -1248,19 +1239,16 @@ For instance, when ``foo.example.net`` is negatively cached, any query matching ``*.foo.example.net`` will be answered with NXDOMAIN directly without consulting authoritative servers. -no -^^ -No :rfc:`8020` processing is done. +``no`` + No :rfc:`8020` processing is done. -dnssec -^^^^^^ -:rfc:`8020` processing is only done using cached NXDOMAIN records that are -DNSSEC validated. +``dnssec`` + :rfc:`8020` processing is only done using cached NXDOMAIN records that are + DNSSEC validated. -yes -^^^ -:rfc:`8020` processing is done using any non-Bogus NXDOMAIN record -available in the cache. +``yes`` + :rfc:`8020` processing is done using any non-Bogus NXDOMAIN record + available in the cache. .. _setting-nsec3-max-iterations: