Update documentation with "insecure" policy

Update the ARM to mention the new built-in "insecure" policy.  Update
the DNSSEC guide recipe "Revert to unsigned" to add the additional
step of reconfiguring the zone to "insecure" (instead of immediately
set it to "none").

(cherry picked from commit fadc57d3d03bb30c036104f7923a164b22db053b)

diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst
index 0a7ae18d29a38c16a8e7f4df9d0b5e0d5233af35..20cc1fb45d3ea866b6f4fd8153c3cdd32221dc1a 100644 (file)
--- a/doc/arm/reference.rst
+++ b/doc/arm/reference.rst
@@ -1430,12 +1430,12 @@ default is used.
    reduced.
 
 ``dnssec-policy``
-   This specifies which key and signing policy (KASP) should be used for this zone.
-   This is a string referring to a ``dnssec-policy`` statement.  There are two
-   built-in policies: ``default``, which uses the default policy, and
-   ``none``, which means no DNSSEC policy and keeps the zone unsigned.  The
-   default is ``none``.  See :ref:`dnssec-policy Grammar
-   <dnssec_policy_grammar>` for more details.
+   This specifies which key and signing policy (KASP) should be used for this
+   zone. This is a string referring to a ``dnssec-policy`` statement.  There
+   are three built-in policies: ``default``, which uses the default policy,
+   ``insecure``, to be used when you want to gracefully unsign your zone, and
+   ``none``, which means no DNSSEC policy.  The default is ``none``.
+   See :ref:`dnssec-policy Grammar <dnssec_policy_grammar>` for more details.
 
 ``dnssec-update-mode``
    If this option is set to its default value of ``maintain`` in a zone

diff --git a/doc/dnssec-guide/recipes.rst b/doc/dnssec-guide/recipes.rst
index 0b98b42b8ed2acc7c1c3e88c78f14d4fe855ed6c..1d45c039f3ccd19d8f774b11507ef47ac5f1cfc5 100644 (file)
--- a/doc/dnssec-guide/recipes.rst
+++ b/doc/dnssec-guide/recipes.rst
@@ -1069,8 +1069,8 @@ Below is an example showing how to remove DS records using the
 To be on the safe side, wait a while before actually deleting
 all signed data from your zone, just in case some validating resolvers
 have cached information. After you are certain that all cached
-information has expired (usually this means one TTL interval has passed), you may
-reconfigure your zone.
+information has expired (usually this means one TTL interval has passed),
+you may reconfigure your zone.
 
 Here is what ``named.conf`` looks like when it is signed:
 
@@ -1083,7 +1083,7 @@ Here is what ``named.conf`` looks like when it is signed:
        dnssec-policy "default";
    };
 
-Remove the ``dnssec-policy`` line so your ``named.conf`` looks like this:
+Change your ``dnssec-policy`` line to indicate you want to revert to unsigned:
 
 ::
 
@@ -1091,8 +1091,24 @@ Remove the ``dnssec-policy`` line so your ``named.conf`` looks like this:
        type primary;
        file "db/example.com.db";
        allow-transfer { any; };
+       dnssec-policy "insecure";
    };
 
 Then use ``rndc reload`` to reload the zone.
 
-Your zone is now reverted back to the traditional, insecure DNS format.
+The "insecure" policy is a built-in policy (like "default"). It will make sure
+the zone is still DNSSEC maintained, to allow for a graceful transition to
+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.
+
+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
+removed from the zone.
+
+You can then remove the ``dnssec-policy`` line from your ``named.conf`` and
+reload the zone. The zone will now no longer be subject to any DNSSEC
+maintenance.