Update documentation

Update ARM and DNSSEC guide with the new checkds feature.

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

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 <id> 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

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:
 
 ::