From b4c1f3b832808f7eb8a48382691be48808630b9a Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Fri, 25 Jun 2021 11:38:37 +0200 Subject: [PATCH] Update documentation Update ARM and DNSSEC guide with the new checkds feature. --- doc/arm/reference.rst | 12 ++++++++++-- doc/dnssec-guide/recipes.rst | 4 +++- doc/dnssec-guide/signing.rst | 35 ++++++++++++++++++++++++++++++----- 3 files changed, 43 insertions(+), 8 deletions(-) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index da6d3d6020..0f14eeb17e 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -861,6 +861,8 @@ responses such as NXDOMAIN. ``parental-agents`` lists allow for a common set of parental agents to be easily used by multiple primary and secondary zones in their ``parental-agents`` lists. +A parental agent is the entity that the zone has a relationship with to +change its delegation information (defined in :rfc:`7344`). .. _primaries_grammar: @@ -5143,8 +5145,14 @@ BIND has mechanisms in place to facilitate automated KSK rollovers. It publishes CDS and CDNSKEY records that can be used by the parent zone to publish or withdraw the zone's DS records. BIND will query the parental agents to see if the new DS is actually published before withdrawing the -old DNSSEC key. The following options apply to DS queries sent to -``parental-agents``: +old DNSSEC key. + + .. note:: + The DS response is not validated so it is recommended to set up a + trust relationship with the parental agent. For example, use TSIG to + authenticate the parental agent, or point to a validating resolver. + +The following options apply to DS queries sent to ``parental-agents``: ``parental-source`` ``parental-source`` determines which local source address, and diff --git a/doc/dnssec-guide/recipes.rst b/doc/dnssec-guide/recipes.rst index 6fc52e06c0..91d14be07f 100644 --- a/doc/dnssec-guide/recipes.rst +++ b/doc/dnssec-guide/recipes.rst @@ -1103,7 +1103,9 @@ unsigned. When the DS records have been removed from the parent zone, use ``rndc dnssec -checkds -key withdrawn example.com`` to tell ``named`` that the DS is removed, and the remaining DNSSEC records will be removed in a timely -manner. +manner. Or if you have parental agents configured, the DNSSEC records will be +automatically removed after BIND has seen that the parental agents no longer +serves the DS RRset for this zone. After a while, your zone is reverted back to the traditional, insecure DNS format. You can verify by checking that all DNSKEY and RRSIG records have been diff --git a/doc/dnssec-guide/signing.rst b/doc/dnssec-guide/signing.rst index 616983474d..f9f65deaad 100644 --- a/doc/dnssec-guide/signing.rst +++ b/doc/dnssec-guide/signing.rst @@ -888,11 +888,36 @@ you may not even have to do that [#]_. When the time approaches for the roll of a KSK or CSK, BIND adds a CDS and a CDNSKEY record for the key in question to the apex of the zone. If your parent zone supports polling for CDS/CDNSKEY records, they -are uploaded and the DS record published in the parent - at least ideally. At -the time of this writing (mid-2020) BIND does not check for the presence of a -DS record in the parent zone before completing the KSK or CSK rollover -and withdrawing the old key. Instead, you need to use the ``rndc`` tool -to tell ``named`` that the DS record has been published. For example: +are uploaded and the DS record published in the parent - at least ideally. + +If BIND is configured with ``parental-agents``, it will check for the DS +presence. Let's look at the following configuration excerpt: + +:: + + parental-agents { + 10.53.0.11, 10.53.0.12; + }; + + zone "example.net" in { + ... + dnssec-policy standard; + parental-agents { "net"; }; + ... + }; + +BIND will check for the presence of the DS record in the parent zone by querying +its parental agents (defined in :rfc:`7344` to be the entities that the child +zone has a relationship with to change its delegation information). In the +example above, The zone `example.net` is configured with two parental agents, +at the addresses 10.53.0.11 and 10.53.0.12. These addresses are used as an +example only. Both addresses will have to respond with a DS RRset that +includes the DS record identifying the key that is being rolled. If one or +both don't have the DS included yet the rollover is paused, and the check for +DS presence is retried after an hour. The same applies for DS withdrawal. + +Alternatively, you can use the ``rndc`` tool to tell ``named`` that the DS +record has been published or withdrawn. For example: ::