rec: Document the new DNSSEC states and helpers

diff --git a/pdns/recursordist/docs/lua-scripting/dq.rst b/pdns/recursordist/docs/lua-scripting/dq.rst
index f92cd2b205a54f5e737f5eb92f90be12c81b87ba..debc6e018839be987c449bdab6f9ac2ed3e92078 100644 (file)
--- a/pdns/recursordist/docs/lua-scripting/dq.rst
+++ b/pdns/recursordist/docs/lua-scripting/dq.rst
@@ -170,6 +170,37 @@ The DNSQuestion object contains at least the following fields:
       Possible states are ``pdns.validationstates.Indeterminate``, ``pdns.validationstates.Bogus``, ``pdns.validationstates.Insecure`` and ``pdns.validationstates.Secure``.
       The result will always be ``pdns.validationstates.Indeterminate`` is validation is disabled or was not requested.
 
+  .. attribute:: DNSQuestion.detailedValidationState
+
+      .. versionadded:: 4.4.2
+
+      The result of the DNSSEC validation, accessible from the ``postresolve``, ``nxdomain`` and ``nodata`` hooks.
+      By contrast with :attr:`validationState <DNSQuestion.validationState>`, there are several Bogus states to be
+      able to better understand the reason for a DNSSEC validation failure.
+      Possible states are :
+      - ``pdns.validationstates.Indeterminate``
+      - ``pdns.validationstates.BogusNoValidDNSKEY``
+      - ``pdns.validationstates.BogusInvalidDenial``
+      - ``pdns.validationstates.BogusUnableToGetDSs``
+      - ``pdns.validationstates.BogusUnableToGetDNSKEYs``
+      - ``pdns.validationstates.BogusSelfSignedDS``
+      - ``pdns.validationstates.BogusNoRRSIG``
+      - ``pdns.validationstates.BogusNoValidRRSIG``
+      - ``pdns.validationstates.BogusMissingNegativeIndication``
+      - ``pdns.validationstates.BogusSignatureNotYetValid``
+      - ``pdns.validationstates.BogusSignatureExpired``
+      - ``pdns.validationstates.BogusUnsupportedDNSKEYAlgo``
+      - ``pdns.validationstates.BogusUnsupportedDSDigestType``
+      - ``pdns.validationstates.BogusNoZoneKeyBitSet``
+      - ``pdns.validationstates.BogusRevokedDNSKEY``
+      - ``pdns.validationstates.BogusInvalidDNSKEYProtocol``
+      - ``pdns.validationstates.Insecure``
+      - ``pdns.validationstates.Secure``
+
+      The result will always be ``pdns.validationstates.Indeterminate`` is validation is disabled or was not requested.
+      There is a convenience function named ``isValidationStateBogus`` that accepts such a state and return a boolean
+      indicating whether this state is a Bogus one.
+
   .. attribute:: DNSQuestion.logResponse
 
       .. versionadded:: 4.2.0

diff --git a/pdns/recursordist/docs/metrics.rst b/pdns/recursordist/docs/metrics.rst
index beebdfe991cba86075f17c091b84af905938106b..ebbdee72bc467fe3dba937a4cfb03e205e4c5c57 100644 (file)
--- a/pdns/recursordist/docs/metrics.rst
+++ b/pdns/recursordist/docs/metrics.rst
@@ -226,7 +226,97 @@ number of queries received with the DO bit set
 
 dnssec-result-bogus
 ^^^^^^^^^^^^^^^^^^^
-number of DNSSEC validations that had the   Bogus state
+number of DNSSEC validations that had the   Bogus state. Since 4.4.2 detailed counters are available, see below.
+
+dnssec-result-bogus-no-valid-dnskey
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because a valid DNSKEY could not be found.
+
+dnssec-result-bogus-invalid-denial
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because a valid denial of existence proof could not be found.
+
+dnssec-result-bogus-unable-to-get-dss
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because a valid DS could not be retrieved.
+
+dnssec-result-bogus-unable-to-get-dnskeys
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because a valid DNSKEY could not be retrieved.
+
+dnssec-result-bogus-self-signed-ds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because a DS record was signed by itself.
+
+dnssec-result-bogus-no-rrsig
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because required RRSIG records were not present in an answer.
+
+dnssec-result-bogus-no-valid-rrsig
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because only invalid RRSIG records were present in an answer.
+
+dnssec-result-bogus-missing-negative-indication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because a NODATA or NXDOMAIN answer lacked the required SOA and/or NSEC(3) records.
+
+dnssec-result-bogus-signature-no-yet-valid
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because the signature inception time in the RRSIG was not yet valid.
+
+dnssec-result-bogus-signature-expired
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because the signature expired time in the RRSIG was in the past.
+
+dnssec-result-bogus-unsupported-dnskey-algo
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because a DNSKEY RRset contained only unsupported DNSSEC algorithms.
+
+dnssec-result-bogus-unsupported-ds-digest-type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because a DS RRset contained only unsupported digest types.
+
+dnssec-result-bogus-no-zone-key-bit-set
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because no DNSKEY with the Zone Key bit set was found.
+
+dnssec-result-bogus-revoked-dnskey
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because all DNSKEYs were revoked.
+
+dnssec-result-bogus-invalid-dnskey-protocol
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. versionadded:: 4.4.2
+
+number of DNSSEC validations that had the Bogus state because all DNSKEYs had invalid protocols.
 
 dnssec-result-indeterminate
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^