From: Gert van Dijk Date: Tue, 2 Apr 2019 09:09:19 +0000 (+0200) Subject: docs: update pdnsutil 'set-nsec3' and NSEC3 narrow mode X-Git-Tag: rec-4.2.0-rc1~45^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f02f619d59fba8e2275c96a3e3cb4a108d028bff;p=thirdparty%2Fpdns.git docs: update pdnsutil 'set-nsec3' and NSEC3 narrow mode * The 4-parameter quoted string argument in "pdnsutil set-nsec3" appears to have a default value of "1 0 1 ab" according to the sources: https://github.com/PowerDNS/pdns/blob/e62422ce0e86cfe959073ef061f07873ceff6be8/pdns/pdnsutil.cc#L2459 introduced with b8adb30dff5fc18b55e27580c07799d8fae1bafb (in 3.3+) * The example command included smart quotes, which don't really work when copy-pasted to a shell - changed to monospaced formatting. * Include note about online signing requirement for "White Lies" / narrow mode support and that zone transfers are denied in this mode. * Mention RFC about "White Lies". * Mention defaults on 'DNSSEC Modes of Operation'. * Mention possible limits of ITERATIONS via 'max-nsec3-iterations'. --- diff --git a/docs/dnssec/modes-of-operation.rst b/docs/dnssec/modes-of-operation.rst index 9e6c2e5145..c03759263e 100644 --- a/docs/dnssec/modes-of-operation.rst +++ b/docs/dnssec/modes-of-operation.rst @@ -55,13 +55,16 @@ As described above, there are several ways in which DNSSEC can deny the existence of a record, and this setting, which is also stored away from zone records, lives with the DNSSEC keying material. +.. _dnssec-nsec-modes: + (Hashed) Denial of Existence ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PowerDNS supports unhashed secure denial-of-existence using NSEC records. These are generated with the help of the (database) backend, which needs to be able to supply the 'previous' and 'next' records in -canonical ordering. +canonical ordering. NSEC is the default mode for secured zones in +PowerDNS. The Generic SQL Backends have fields that allow them to supply these relative record names. @@ -72,11 +75,15 @@ the help of some additional calculations. NSEC3 in 'broad' or 'inclusive' mode works with the aid of the backend, where the backend should be able to supply the previous and next domain -names in hashed order. +names in hashed order. This is the default mode for NSEC3 in PowerDNS. NSEC3 in 'narrow' mode uses additional hashing calculations to provide -hashed secure denial-of-existence 'on the fly', without further -involving the database. +hashed secure denial-of-existence 'on the fly' per +`RFC 7129 `__, without further +involving the database. This mode will make PowerDNS to send out "white +lies" and prevents zone enumeration, but these responses require online +signing capabilities by all nameservers and therefore denies incoming +AXFRs for zones in this mode. .. _dnssec-signatures: diff --git a/docs/dnssec/operational.rst b/docs/dnssec/operational.rst index ce3db3e05e..c5e4b328ca 100644 --- a/docs/dnssec/operational.rst +++ b/docs/dnssec/operational.rst @@ -28,6 +28,8 @@ Going insecure parent zone will make the zone BOGUS. Make sure the parent zone removes the DS record *before* going insecure. +.. _dnssec-operational-nsec-modes-params: + Setting the NSEC modes and parameters ------------------------------------- @@ -36,7 +38,7 @@ NSEC3 instead, issue: .. code-block:: shell - pdnsutil set-nsec3 ZONE [PARAMETERS] + pdnsutil set-nsec3 ZONE [PARAMETERS] ['narrow'] e.g. @@ -51,9 +53,13 @@ The quoted part is the content of the NSEC3PARAM records, as defined in - Flags, set to ``1`` for :rfc:`NSEC3 Opt-out <5155#section-6>`, this best set as ``0`` - Number of iterations of the hash function, read :rfc:`RFC 5155, Section - 10.3 <5155#section-10.3>` for recommendations + 10.3 <5155#section-10.3>` for recommendations. Limited by the + :ref:`setting-max-nsec3-iterations` setting. - Salt to apply during hashing, in hexadecimal, or ``-`` to use no salt +Optionally, NSEC3 can be set to 'narrow' mode. For more information refer +to :ref:`dnssec-nsec-modes`. + To convert a zone from NSEC3 to NSEC operations, run: .. code-block:: shell diff --git a/docs/manpages/pdnsutil.1.rst b/docs/manpages/pdnsutil.1.rst index 3b02ccfbc7..28912612b0 100644 --- a/docs/manpages/pdnsutil.1.rst +++ b/docs/manpages/pdnsutil.1.rst @@ -80,7 +80,7 @@ import-zone-key *ZONE* *FILE* {**KSK**,\ **ZSK**} the added key. remove-zone-key *ZONE* *KEY-ID* Remove a key with id *KEY-ID* from a zone called *ZONE*. -set-nsec3 *ZONE* '*HASH-ALGORITHM* *FLAGS* *ITERATIONS* *SALT*' [**narrow**] +set-nsec3 *ZONE* ['*HASH-ALGORITHM* *FLAGS* *ITERATIONS* *SALT*'] [**narrow**] Sets NSEC3 parameters for this zone. The quoted parameters are 4 values that are used for the the NSEC3PARAM record and decide how NSEC3 records are created. The NSEC3 parameters must be quoted on @@ -88,14 +88,18 @@ set-nsec3 *ZONE* '*HASH-ALGORITHM* *FLAGS* *ITERATIONS* *SALT*' [**narrow**] *FLAGS* to 1 enables NSEC3 opt-out operation. Only do this if you know you need it. For *ITERATIONS*, please consult RFC 5155, section 10.3. And be aware that a high number might overload validating - resolvers. The *SALT* is a hexadecimal string encoding the bits for - the salt, or - to use no salt. Setting **narrow** will make PowerDNS - send out "white lies" about the next secure record. Instead of - looking it up in the database, it will send out the hash + 1 as the - next secure record. A sample commandline is: "pdnsutil set-nsec3 - powerdnssec.org '1 1 1 ab' narrow". **WARNING**: If running in - RSASHA1 mode (algorithm 5 or 7), switching from NSEC to NSEC3 will - require a DS update in the parent zone. + resolvers and that a limit can be set with ``max-nsec3-iterations`` + in ``pdns.conf``. The *SALT* is a hexadecimal string encoding the bits + for the salt, or - to use no salt. Setting **narrow** will make PowerDNS + send out "white lies" (RFC 7129) about the next secure record to + prevent zone enumeration. Instead of looking it up in the database, + it will send out the hash + 1 as the next secure record. Narrow mode + requires online signing capabilities by the nameserver and therefore + zone transfers are denied. If only the zone is provided as argument, + the 4-parameter quoted string defaults to ``'1 0 1 ab'``. A sample + commandline is: ``pdnsutil set-nsec3 powerdnssec.org '1 1 1 ab' narrow``. + **WARNING**: If running in RSASHA1 mode (algorithm 5 or 7), switching + from NSEC to NSEC3 will require a DS update in the parent zone. unset-nsec3 *ZONE* Converts *ZONE* to NSEC operations. **WARNING**: If running in RSASHA1 mode (algorithm 5 or 7), switching from NSEC to NSEC3 will diff --git a/docs/settings.rst b/docs/settings.rst index 70b862b11a..b8a9a21276 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -910,7 +910,8 @@ protection measure to avoid database explosion due to long names. - Integer - Default: 500 -Limit the number of NSEC3 hash iterations +Limit the number of NSEC3 hash iterations for zone configurations. +For more information see :ref:`dnssec-operational-nsec-modes-params`. .. _setting-max-packet-cache-entries: