Adding upstream version 1:9.18.19.upstream/1%9.18.19upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1084 insertions, 0 deletions

diff --git a/doc/dnssec-guide/recipes.rst b/doc/dnssec-guide/recipes.rst
new file mode 100644
index 0000000..42ee782
--- /dev/null
+++ b/doc/dnssec-guide/recipes.rst
@@ -0,0 +1,1084 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0.  If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. _dnssec_recipes:
+
+Recipes
+-------
+
+This chapter provides step-by-step "recipes" for some common
+DNSSEC configurations.
+
+.. _recipes_inline_signing:
+
+DNSSEC Signing
+~~~~~~~~~~~~~~
+
+There are two recipes here: the first shows an example using DNSSEC
+signing on the primary server, which has been covered in this
+guide; the second shows how to setup a "bump in the
+wire" between a hidden primary and the secondary servers to seamlessly
+sign the zone "on the fly."
+
+.. _recipes_inline_signing_primary:
+
+Primary Server DNSSEC Signing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this recipe, our servers are illustrated as shown in
+:ref:`dnssec-signing-1`: we have a primary server
+(192.168.1.1) and three secondary servers (192.168.1.2, 192.168.1.3, and
+192.168.1.4) that receive zone transfers. To get the zone
+signed, we need to reconfigure the primary server. Once reconfigured, a
+signed version of the zone is generated on the fly;
+zone transfers take care of synchronizing the signed zone data
+to all secondary name servers, without configuration or software changes
+on them.
+
+.. _dnssec-signing-1:
+
+.. figure:: ../dnssec-guide/img/dnssec-inline-signing-1.png
+   :alt: DNSSEC Signing Recipe #1
+   :width: 80.0%
+
+   DNSSEC Signing Recipe #1
+
+Using the method described in
+:ref:`easy_start_guide_for_authoritative_servers`, we just need to
+add a :any:`dnssec-policy` statement to the relevant zone clause. This is
+what the :iscman:`named.conf` zone statement looks like on the primary server, 192.168.1.1:
+
+::
+
+   zone "example.com" IN {
+       type primary;
+       file "db/example.com.db";
+       key-directory "keys/example.com";
+       dnssec-policy default;
+       inline-signing yes;
+       allow-transfer { 192.168.1.2; 192.168.1.3; 192.168.1.4; };
+   };
+
+We have chosen to use the default policy, storing the keys generated for
+the zone in the directory ``keys/example.com``. To use a
+custom policy, define the policy in the configuration
+file and select it in the zone statement (as described in
+:ref:`signing_custom_policy`).
+
+On the secondary servers, :iscman:`named.conf` does not need to be updated,
+and it looks like this:
+
+::
+
+   zone "example.com" IN {
+       type secondary;
+       file "db/example.com.db";
+       primaries { 192.168.1.1; };
+   };
+
+In fact, the secondary servers do not even need to be running BIND; they
+can run any DNS product that supports DNSSEC.
+
+.. _recipes_inline_signing_bump_in_the_wire:
+
+"Bump in the Wire" Signing
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this recipe, we take advantage of the power of automated signing
+by placing an additional name server (192.168.1.5) between the hidden
+primary (192.168.1.1) and the DNS secondaries (192.168.1.2, 192.168.1.3,
+and 192.168.1.4). The additional name server, 192.168.1.5, acts as a "bump
+in the wire," taking an unsigned zone from the hidden primary,
+and sending out signed data on the other end to the secondary name
+servers. The steps described in this recipe may be used as part of a
+DNSSEC deployment strategy, since it requires only minimal changes made to
+the existing hidden DNS primary and DNS secondaries.
+
+.. _dnssec-signing-2:
+
+.. figure:: ../dnssec-guide/img/dnssec-inline-signing-2.png
+   :alt: DNSSEC Signing Recipe #2
+   :width: 100.0%
+
+   DNSSEC Signing Recipe #2
+
+It is important to remember that 192.168.1.1 in this case is a hidden
+primary not exposed to the world, and it must not be listed in the NS RRset.
+Otherwise the world will get conflicting answers: unsigned answers from
+the hidden primary and signed answers from the other name servers.
+
+The only configuration change needed on the hidden primary, 192.168.1.1,
+is to make sure it allows our middle box to perform a zone transfer:
+
+::
+
+   zone "example.com" IN {
+       ...
+       allow-transfer { 192.168.1.5; };
+       ...
+   };
+
+On the middle box, 192.168.1.5, all the tasks described in
+:ref:`easy_start_guide_for_authoritative_servers` still need to be
+performed, such as generating key pairs and uploading information to
+the parent zone. This server is configured as secondary to the hidden
+primary 192.168.1.1 to receive the unsigned data; then, using keys
+accessible to this middle box, to sign data on the fly; and finally, to send out the
+signed data via zone transfer to the other three DNS secondaries. Its
+:iscman:`named.conf` zone statement looks like this:
+
+::
+
+   zone example.com {
+       type secondary;
+       primaries { 192.168.1.1; };
+       file "db/example.com.db";
+       key-directory "keys/example.com";
+       dnssec-policy default;
+       inline-signing yes;
+       allow-transfer { 192.168.1.2; 192.168.1.3; 192.168.1.4; };
+   };
+
+(As before, the default policy has been selected here. See
+:ref:`signing_custom_policy` for instructions on how to define
+and use a custom policy.)
+
+Finally, on the three secondary servers, the configuration should be updated
+to receive a zone transfer from 192.168.1.5 (the middle box) instead of
+from 192.168.1.1 (the hidden primary). If using BIND, the :iscman:`named.conf` file looks
+like this:
+
+::
+
+   zone "example.com" IN {
+       type secondary;
+       file "db/example.com.db";
+       primaries { 192.168.1.5; };   # this was 192.168.1.1 before!
+   };
+
+.. _recipes_rollovers:
+
+Rollovers
+~~~~~~~~~
+
+If you are signing your zone using a :any:`dnssec-policy` statement, this
+section is not really relevant to you. In the policy statement, you set how long
+you want your keys to be valid for, the time
+taken for information to propagate through your zone, the time it takes
+for your parent zone to register a new DS record, etc., and that's more
+or less it. :iscman:`named` implements everything for you automatically, apart from
+uploading the new DS records to your parent zone - which is covered in
+:ref:`signing_easy_start_upload_to_parent_zone`. (Some
+screenshots from a session where a KSK is uploaded to the parent zone
+are presented here for convenience.) However, these recipes may be useful
+in describing what happens
+through the rollover process and what you should be monitoring.
+
+.. _recipes_zsk_rollover:
+
+ZSK Rollover
+^^^^^^^^^^^^
+
+This recipe covers how to perform a ZSK rollover using what is known as
+the Pre-Publication method. For other ZSK rolling methods, please see
+:ref:`zsk_rollover_methods` in :ref:`dnssec_advanced_discussions`.
+
+Below is a sample timeline for a ZSK rollover to occur on January 1, 2021:
+
+1. December 1, 2020 (one month before rollover)
+
+   -  Generate new ZSK
+
+   -  Add DNSKEY for new ZSK to zone
+
+2. January 1, 2021 (day of rollover)
+
+   -  New ZSK used to replace RRSIGs for the bulk of the zone
+
+3. February 1, 2021 (one month after rollover)
+
+   -  Remove old ZSK DNSKEY RRset from zone
+
+   -  DNSKEY signatures made with KSK are changed
+
+The current active ZSK has the ID 17694 in the example below. For more
+information on key management and rollovers, please see
+:ref:`advanced_discussions_key_management`.
+
+One Month Before ZSK Rollover
++++++++++++++++++++++++++++++
+
+On December 1, 2020, a month before the example rollover, you (as administrator)
+should change the parameters on the current key (17694). Set it to become inactive on
+January 1, 2021 and be deleted from the zone on February 1, 2021; also,
+generate a successor key (51623):
+
+::
+
+   # cd /etc/bind/keys/example.com/
+   # dnssec-settime -I 20210101 -D 20210201 Kexample.com.+008+17694
+   ./Kexample.com.+008+17694.key/GoDaddy
+
+   ./Kexample.com.+008+17694.private
+   # dnssec-keygen -S Kexample.com.+008+17694
+   Generating key pair..++++++ ...........++++++
+   Kexample.com.+008+51623
+
+The first command gets us into the key directory
+``/etc/bind/keys/example.com/``, where keys for ``example.com`` are
+stored.
+
+The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
+2021, and a deletion (:option:`-D <dnssec-settime -D>`) date of February 1, 2021, for the current ZSK
+(``Kexample.com.+008+17694``).
+
+The third command, :iscman:`dnssec-keygen`, creates a successor key, using
+the exact same parameters (algorithms, key sizes, etc.) as the current
+ZSK. The new ZSK created in our example is ``Kexample.com.+008+51623``.
+
+Make sure the successor keys are readable by :iscman:`named`.
+
+:iscman:`named`'s logging messages indicate when the next
+key checking event is scheduled to occur, the frequency of which can be
+controlled by :any:`dnssec-loadkeys-interval`. The log message looks like
+this:
+
+::
+
+   zone example.com/IN (signed): next key event: 01-Dec-2020 00:13:05.385
+
+And you can check the publish date of the key by looking at the key
+file:
+
+::
+
+   # cd /etc/bind/keys/example.com
+   # cat Kexample.com.+008+51623.key
+   ; This is a zone-signing key, keyid 11623, for example.com.
+   ; Created: 20201130160024 (Mon Dec  1 00:00:24 2020)
+   ; Publish: 20201202000000 (Fri Dec  2 08:00:00 2020)
+   ; Activate: 20210101000000 (Sun Jan  1 08:00:00 2021)
+   ...
+
+Since the publish date is set to the morning of December 2, and our example
+scenario takes place on December 1, the next
+morning you will notice that your zone has gained a new DNSKEY record,
+but the new ZSK is not yet being used to generate signatures. Below is
+the abbreviated output - with shortened DNSKEY and RRSIG - when querying the
+authoritative name server, 192.168.1.13:
+
+::
+
+   $ dig @192.168.1.13 example.com. DNSKEY +dnssec +multiline
+
+   ...
+   ;; ANSWER SECTION:
+   example.com.        600 IN DNSKEY 257 3 8 (
+                   AwEAAcWDps...lM3NRn/G/R
+                   ) ; KSK; alg = RSASHA256; key id = 6817
+   example.com.        600 IN DNSKEY 256 3 8 (
+                   AwEAAbi6Vo...qBW5+iAqNz
+                   ) ; ZSK; alg = RSASHA256; key id = 51623
+   example.com.        600 IN DNSKEY 256 3 8 (
+                   AwEAAcjGaU...0rzuu55If5
+                   ) ; ZSK; alg = RSASHA256; key id = 17694
+   example.com.        600 IN RRSIG DNSKEY 8 2 600 (
+                   20210101000000 20201201230000 6817 example.com.
+                   LAiaJM26T7...FU9syh/TQ= )
+   example.com.        600 IN RRSIG DNSKEY 8 2 600 (
+                   20210101000000 20201201230000 17694 example.com.
+                   HK4EBbbOpj...n5V6nvAkI= )
+   ...
+
+For good measure, let's take a look at the SOA record and its
+signature for this zone. Notice the RRSIG is signed by the current ZSK,
+17694. This will come in handy later when you want to verify whether
+the new ZSK is in effect:
+
+::
+
+   $ dig @192.168.1.13 example.com. SOA +dnssec +multiline
+
+   ...
+   ;; ANSWER SECTION:
+   example.com.        600 IN SOA ns1.example.com. admin.example.com. (
+                   2020120102 ; serial
+                   1800       ; refresh (30 minutes)
+                   900        ; retry (15 minutes)
+                   2419200    ; expire (4 weeks)
+                   300        ; minimum (5 minutes)
+                   )
+   example.com.        600 IN RRSIG SOA 8 2 600 (
+                   20201230160109 20201130150109 17694 example.com.
+                   YUTC8rFULaWbW+nAHzbfGwNqzARHevpryzRIJMvZBYPo
+                   NAeejNk9saNAoCYKWxGJ0YBc2k+r5fYq1Mg4ll2JkBF5
+                   buAsAYLw8vEOIxVpXwlArY+oSp9T1w2wfTZ0vhVIxaYX
+                   6dkcz4I3wbDx2xmG0yngtA6A8lAchERx2EGy0RM= )
+
+These are all the manual tasks you need to perform for a ZSK rollover.
+If you have followed the configuration examples in this guide of using
+:any:`inline-signing` and :any:`auto-dnssec`, everything else is automated for
+you by BIND.
+
+Day of ZSK Rollover
++++++++++++++++++++
+
+On the actual day of the rollover, although there is technically nothing
+for you to do, you should still keep an eye on the zone to make sure new
+signatures are being generated by the new ZSK (51623 in this example).
+The easiest way is to query the authoritative name server 192.168.1.13
+for the SOA record as you did a month ago:
+
+::
+
+   $ dig @192.168.1.13 example.com. SOA +dnssec +multiline
+
+   ...
+   ;; ANSWER SECTION:
+   example.com.        600 IN SOA ns1.example.com. admin.example.com. (
+                   2020112011 ; serial
+                   1800       ; refresh (30 minutes)
+                   900        ; retry (15 minutes)
+                   2419200    ; expire (4 weeks)
+                   300        ; minimum (5 minutes)
+                   )
+   example.com.        600 IN RRSIG SOA 8 2 600 (
+                   20210131000000 20201231230000 51623 example.com.
+                   J4RMNpJPOmMidElyBugJp0RLqXoNqfvo/2AT6yAAvx9X
+                   zZRL1cuhkRcyCSLZ9Z+zZ2y4u2lvQGrNiondaKdQCor7
+                   uTqH5WCPoqalOCBjqU7c7vlAM27O9RD11nzPNpVQ7xPs
+                   y5nkGqf83OXTK26IfnjU1jqiUKSzg6QR7+XpLk0= )
+   ...
+
+As you can see, the signature generated by the old ZSK (17694) has
+disappeared, replaced by a new signature generated from the new ZSK
+(51623).
+
+.. note::
+
+   Not all signatures will disappear magically on the same day;
+   it depends on when each one was generated. In the worst-case scenario,
+   a new signature could have been signed by the old ZSK (17694) moments
+   before it was deactivated, meaning that the signature could live for almost
+   30 more days, until just before February 1.
+
+   This is why it is important to keep the old ZSK in the
+   zone and not delete it right away.
+
+One Month After ZSK Rollover
+++++++++++++++++++++++++++++
+
+Again, technically there is nothing you need to do on this day,
+but it doesn't hurt to verify that the old ZSK (17694) is now completely
+gone from your zone. :iscman:`named` will not touch
+``Kexample.com.+008+17694.private`` and ``Kexample.com.+008+17694.key``
+on your file system. Running the same :iscman:`dig` command for DNSKEY should
+suffice:
+
+::
+
+   $ dig @192.168.1.13 example.com. DNSKEY +multiline +dnssec
+
+   ...
+   ;; ANSWER SECTION:
+   example.com.        600 IN DNSKEY 257 3 8 (
+                   AwEAAcWDps...lM3NRn/G/R
+                   ) ; KSK; alg = RSASHA256; key id = 6817
+   example.com.        600 IN DNSKEY 256 3 8 (
+                   AwEAAdeCGr...1DnEfX+Xzn
+                   ) ; ZSK; alg = RSASHA256; key id = 51623
+   example.com.        600 IN RRSIG DNSKEY 8 2 600 (
+                   20170203000000 20170102230000 6817 example.com.
+                   KHY8P0zE21...Y3szrmjAM= )
+   example.com.        600 IN RRSIG DNSKEY 8 2 600 (
+                   20170203000000 20170102230000 51623 example.com.
+                   G2g3crN17h...Oe4gw6gH8= )
+   ...
+
+Congratulations, the ZSK rollover is complete! As for the actual key
+files (the files ending in ``.key`` and ``.private``), they may be deleted at this
+point, but they do not have to be.
+
+.. _recipes_ksk_rollover:
+
+KSK Rollover
+^^^^^^^^^^^^
+
+This recipe describes how to perform KSK rollover using the Double-DS
+method. For other KSK rolling methods, please see
+:ref:`ksk_rollover_methods` in
+:ref:`dnssec_advanced_discussions`. The registrar used in this
+recipe is `GoDaddy <https://www.godaddy.com>`__. Also for this recipe,
+we are keeping the number of DS records down to just one per active set
+using just SHA-1, for the sake of better clarity, although in practice
+most zone operators choose to upload two DS records as shown in
+:ref:`working_with_parent_zone`. For more information on key
+management and rollovers,
+please see :ref:`advanced_discussions_key_management`.
+
+Below is a sample timeline for a KSK rollover to occur on January 1, 2021:
+
+1. December 1, 2020 (one month before rollover)
+
+   -  Change timer on the current KSK
+
+   -  Generate new KSK and DS records
+
+   -  Add DNSKEY for the new KSK to zone
+
+   -  Upload new DS records to parent zone
+
+2. January 1, 2021 (day of rollover)
+
+   -  Use the new KSK to sign all DNSKEY RRsets, which generates new
+      RRSIGs
+
+   -  Add new RRSIGs to the zone
+
+   -  Remove RRSIG for the old ZSK from zone
+
+   -  Start using the new KSK to sign DNSKEY
+
+3. February 1, 2021 (one month after rollover)
+
+   -  Remove the old KSK DNSKEY from zone
+
+   -  Remove old DS records from parent zone
+
+The current active KSK has the ID 24828, and this is the DS record that
+has already been published by the parent zone:
+
+::
+
+   # dnssec-dsfromkey -a SHA-1 Kexample.com.+007+24828.key
+   example.com. IN DS 24828 7 1 D4A33E8DD550A9567B4C4971A34AD6C4B80A6AD3
+
+.. _one_month_before_ksk_rollover:
+
+One Month Before KSK Rollover
++++++++++++++++++++++++++++++
+
+On December 1, 2020, a month before the planned rollover, you (as
+administrator) should
+change the parameters on the current key. Set it to become inactive on January
+1, 2021, and be deleted from the zone on February 1st, 2021;
+also generate a successor key (23550). Finally, generate a new
+DS record based on the new key, 23550:
+
+::
+
+   # cd /etc/bind/keys/example.com/
+   # dnssec-settime -I 20210101 -D 20210201 Kexample.com.+007+24828
+   ./Kexample.com.+007+24848.key
+   ./Kexample.com.+007+24848.private
+   # dnssec-keygen -S Kexample.com.+007+24848
+   Generating key pair.......................................................................................++ ...................................++
+   Kexample.com.+007+23550
+   # dnssec-dsfromkey -a SHA-1 Kexample.com.+007+23550.key
+   example.com. IN DS 23550 7 1 54FCF030AA1C79C0088FDEC1BD1C37DAA2E70DFB
+
+The first command gets us into the key directory
+``/etc/bind/keys/example.com/``, where keys for ``example.com`` are
+stored.
+
+The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
+2021, and a deletion (:option:`-D <dnssec-settime -D>`) date of February 1, 2021 for the current KSK
+(``Kexample.com.+007+24848``).
+
+The third command, :iscman:`dnssec-keygen`, creates a successor key, using
+the exact same parameters (algorithms, key sizes, etc.) as the current
+KSK. The new key pair created in our example is ``Kexample.com.+007+23550``.
+
+The fourth and final command, :iscman:`dnssec-dsfromkey`, creates a DS record
+from the new KSK (23550), using SHA-1 as the digest type. Again, in
+practice most people generate two DS records for both supported digest
+types (SHA-1 and SHA-256), but for our example here we are only using
+one to keep the output small and hopefully clearer.
+
+Make sure the successor keys are readable by :iscman:`named`.
+
+The :any:`syslog` message indicates when the next key
+checking event is. The log message looks like this:
+
+::
+
+   zone example.com/IN (signed): next key event: 01-Dec-2020 00:13:05.385
+
+You can check the publish date of the key by looking at the key
+file:
+
+::
+
+   # cd /etc/bind/keys/example.com
+   # cat Kexample.com.+007+23550.key
+   ; This is a key-signing key, keyid 23550, for example.com.
+   ; Created: 20201130160024 (Thu Dec  1 00:00:24 2020)
+   ; Publish: 20201202000000 (Fri Dec  2 08:00:00 2020)
+   ; Activate: 20210101000000 (Sun Jan  1 08:00:00 2021)
+   ...
+
+Since the publish date is set to the morning of December 2, and our example
+scenario takes place on December 1, the next
+morning you will notice that your zone has gained a new DNSKEY record
+based on your new KSK, but with no corresponding RRSIG yet. Below is the
+abbreviated output - with shortened DNSKEY and RRSIG - when querying the
+authoritative name server, 192.168.1.13:
+
+::
+
+   $ dig @192.168.1.13 example.com. DNSKEY +dnssec +multiline
+
+   ...
+   ;; ANSWER SECTION:
+   example.com.   300 IN DNSKEY 256 3 7 (
+                   AwEAAdYqAc...TiSlrma6Ef
+                   ) ; ZSK; alg = NSEC3RSASHA1; key id = 29747
+   example.com.   300 IN DNSKEY 257 3 7 (
+                   AwEAAeTJ+w...O+Zy9j0m63
+                   ) ; KSK; alg = NSEC3RSASHA1; key id = 24828
+   example.com.   300 IN DNSKEY 257 3 7 (
+                   AwEAAc1BQN...Wdc0qoH21H
+                   ) ; KSK; alg = NSEC3RSASHA1; key id = 23550
+   example.com.   300 IN RRSIG DNSKEY 7 2 300 (
+                   20201206125617 20201107115617 24828 example.com.
+                   4y1iPVJOrK...aC3iF9vgc= )
+   example.com.   300 IN RRSIG DNSKEY 7 2 300 (
+                   20201206125617 20201107115617 29747 example.com.
+                   g/gfmPjr+y...rt/S/xjPo= )
+
+   ...
+
+Anytime after generating the DS record, you can upload it;
+it is not necessary to wait for the DNSKEY to be published in your zone,
+since this new KSK is not active yet. You can do it
+immediately after the new DS record has been generated on December 1,
+or you can wait until the next day after you have verified that the
+new DNSKEY record is added to the zone. Below are some screenshots from
+GoDaddy's web-based interface, used to add a new DS record [#]_.
+
+1. After logging in, click the green "Launch" button next to the domain
+   name you want to manage.
+
+   .. _add-ds-1:
+
+   .. figure:: ../dnssec-guide/img/add-ds-1.png
+      :alt: Upload DS Record Step #1
+      :width: 70.0%
+
+      Upload DS Record Step #1
+
+2. Scroll down to the "DS Records" section and click "Manage."
+
+   .. _add-ds-2:
+
+   .. figure:: ../dnssec-guide/img/add-ds-2.png
+      :alt: Upload DS Record Step #2
+      :width: 40.0%
+
+      Upload DS Record Step #2
+
+3. A dialog appears, displaying the current key (24828). Click "Add DS
+   Record."
+
+   .. _add-ds-3:
+
+   .. figure:: ../dnssec-guide/img/add-ds-3.png
+      :alt: Upload DS Record Step #3
+      :width: 80.0%
+
+      Upload DS Record Step #3
+
+4. Enter the Key ID, algorithm, digest type, and the digest, then click
+   "Next."
+
+   .. _add-ds-4:
+
+   .. figure:: ../dnssec-guide/img/add-ds-4.png
+      :alt: Upload DS Record Step #4
+      :width: 80.0%
+
+      Upload DS Record Step #4
+
+5. Address any errors and click "Finish."
+
+   .. _add-ds-5:
+
+   .. figure:: ../dnssec-guide/img/add-ds-5.png
+      :alt: Upload DS Record Step #5
+      :width: 80.0%
+
+      Upload DS Record Step #5
+
+6. Both DS records are shown. Click "Save."
+
+   .. _add-ds-6:
+
+   .. figure:: ../dnssec-guide/img/add-ds-6.png
+      :alt: Upload DS Record Step #6
+      :width: 80.0%
+
+      Upload DS Record Step #6
+
+Finally, let's verify that the registrar has published the new DS
+record. This may take anywhere from a few minutes to a few days,
+depending on your parent zone. You can verify whether your
+parent zone has published the new DS record by querying for the DS
+record of your zone. In the example below, the Google public DNS server
+8.8.8.8 is used:
+
+::
+
+   $ dig @8.8.8.8 example.com. DS
+
+   ...
+   ;; ANSWER SECTION:
+   example.com.    21552   IN  DS  24828 7 1 D4A33E8DD550A9567B4C4971A34AD6C4B80A6AD3
+   example.com.    21552   IN  DS  23550 7 1 54FCF030AA1C79C0088FDEC1BD1C37DAA2E70DFB
+
+You can also query your parent zone's authoritative name servers
+directly to see if these records have been published. DS records will
+not show up on your own authoritative zone, so you cannot query your own
+name servers for them. In this recipe, the parent zone is ``.com``, so
+querying a few of the ``.com`` name servers is another appropriate
+verification.
+
+Day of KSK Rollover
++++++++++++++++++++
+
+If you have followed the examples in this document, as described in
+:ref:`easy_start_guide_for_authoritative_servers`, there is
+technically nothing you need to do manually on the actual day of the
+rollover. However, you should still keep an eye on the zone to make sure
+new signature(s) are being generated by the new KSK (23550 in this
+example). The easiest way is to query the authoritative name server
+192.168.1.13 for the same DNSKEY and signatures, as you did a month
+ago:
+
+::
+
+   $ dig @192.168.1.13 example.com. DNSKEY +dnssec +multiline
+
+   ...
+   ;; ANSWER SECTION:
+   example.com.   300 IN DNSKEY 256 3 7 (
+                   AwEAAdYqAc...TiSlrma6Ef
+                   ) ; ZSK; alg = NSEC3RSASHA1; key id = 29747
+   example.com.   300 IN DNSKEY 257 3 7 (
+                   AwEAAeTJ+w...O+Zy9j0m63
+                   ) ; KSK; alg = NSEC3RSASHA1; key id = 24828
+   example.com.   300 IN DNSKEY 257 3 7 (
+                   AwEAAc1BQN...Wdc0qoH21H
+                   ) ; KSK; alg = NSEC3RSASHA1; key id = 23550
+   example.com.    300 IN RRSIG DNSKEY 7 2 300 (
+                   20210201074900 20210101064900 23550 mydnssecgood.org.
+                   S6zTbBTfvU...Ib5eXkbtE= )
+   example.com.    300 IN RRSIG DNSKEY 7 2 300 (
+                   20210105074900 20201206064900 29747 mydnssecgood.org.
+                   VY5URQA2/d...OVKr1+KX8= )
+   ...
+
+As you can see, the signature generated by the old KSK (24828) has
+disappeared, replaced by a new signature generated from the new KSK
+(23550).
+
+One Month After KSK Rollover
+++++++++++++++++++++++++++++
+
+While the removal of the old DNSKEY from the zone should be automated by
+:iscman:`named`, the removal of the DS record is manual. You should make sure
+the old DNSKEY record is gone from your zone first, by querying for the
+DNSKEY records of the zone; this time we expect not to see
+the key with an ID of 24828:
+
+::
+
+   $ dig @192.168.1.13 example.com. DNSKEY +dnssec +multiline
+
+   ...
+   ;; ANSWER SECTION:
+   example.com.    300 IN DNSKEY 256 3 7 (
+                   AwEAAdYqAc...TiSlrma6Ef
+                   ) ; ZSK; alg = NSEC3RSASHA1; key id = 29747
+   example.com.    300 IN DNSKEY 257 3 7 (
+                   AwEAAc1BQN...Wdc0qoH21H
+                   ) ; KSK; alg = NSEC3RSASHA1; key id = 23550
+   example.com.    300 IN RRSIG DNSKEY 7 2 300 (
+                   20210208000000 20210105230000 23550 mydnssecgood.org.
+                   Qw9Em3dDok...bNCS7KISw= )
+   example.com.    300 IN RRSIG DNSKEY 7 2 300 (
+                   20210208000000 20210105230000 29747 mydnssecgood.org.
+                   OuelpIlpY9...XfsKupQgc= )
+   ...
+
+Since the key with the ID 24828 is gone, you can now remove the old DS
+record for that key from our parent zone.
+Be careful to remove the correct DS record. If you accidentally remove
+the new DS record(s) with key ID 23550, it could lead to a problem called
+"security lameness," as discussed in
+:ref:`troubleshooting_security_lameness`, and may cause users to be unable
+to resolve any names in the zone.
+
+1. After logging in (again, GoDaddy.com in our example) and launching the domain, scroll down to the "DS
+   Records" section and click Manage.
+
+   .. _remove-ds-1:
+
+   .. figure:: ../dnssec-guide/img/remove-ds-1.png
+      :alt: Remove DS Record Step #1
+      :width: 40.0%
+
+      Remove DS Record Step #1
+
+2. A dialog appears, displaying both keys (24828 and 23550). Use the far
+   right-hand X button to remove key 24828.
+
+   .. _remove-ds-2:
+
+   .. figure:: ../dnssec-guide/img/remove-ds-2.png
+      :alt: Remove DS Record Step #2
+      :width: 80.0%
+
+      Remove DS Record Step #2
+
+3. Key 24828 now appears crossed out; click "Save" to complete the
+   removal.
+
+   .. _remove-ds-3:
+
+   .. figure:: ../dnssec-guide/img/remove-ds-3.png
+      :alt: Remove DS Record Step #3
+      :width: 80.0%
+
+      Remove DS Record Step #3
+
+Congratulations, the KSK rollover is complete! As for the actual key
+files (ending in ``.key`` and ``.private``), they may be deleted at this
+point, but they do not have to be.
+
+.. [#]
+   The screenshots were taken from GoDaddy's interface at the time the
+   original version of this guide was published (2015). It may have
+   changed since then.
+
+.. _recipes_nsec3:
+
+NSEC and NSEC3
+~~~~~~~~~~~~~~
+
+.. _recipes_nsec_to_nsec3:
+
+Migrating from NSEC to NSEC3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This recipe describes how to transition from using NSEC to NSEC3, as described
+in :ref:`advanced_discussions_proof_of_nonexistence`. This recipe
+assumes that the zones are already signed, and that :iscman:`named` is configured
+according to the steps described in
+:ref:`easy_start_guide_for_authoritative_servers`.
+
+.. warning::
+
+   If your zone is signed with RSASHA1 (algorithm 5), you cannot migrate
+   to NSEC3 without also performing an
+   algorithm rollover
+   to RSASHA1-NSEC3-SHA1 (algorithm 7), as described in
+   :ref:`advanced_discussions_DNSKEY_algorithm_rollovers`. This
+   ensures that older validating resolvers that do not understand
+   NSEC3 will fall back to treating the zone as unsecured (rather than
+   "bogus"), as described in Section 2 of :rfc:`5155`.
+
+To enable NSEC3, update your :any:`dnssec-policy` and add the desired NSEC3
+parameters. The example below enables NSEC3 for zones with the ``standard``
+DNSSEC policy, using 0 additional iterations, no opt-out, and a zero-length salt:
+
+::
+
+    dnssec-policy "standard" {
+        nsec3param iterations 0 optout no salt-length 0;
+    };
+
+Then reconfigure the server with :iscman:`rndc`. You can tell that it worked if you
+see the following debug log messages:
+
+::
+
+   Oct 21 13:47:21 received control channel command 'reconfig'
+   Oct 21 13:47:21 zone example.com/IN (signed): zone_addnsec3chain(1,CREATE,0,-)
+
+You can also verify that it worked by querying for a name that you know
+does not exist, and checking for the presence of the NSEC3 record.
+For example:
+
+::
+
+   $ dig @192.168.1.13 thereisnowaythisexists.example.com. A +dnssec +multiline
+
+   ...
+   5A03TL362CS8VSIH69CVA4MJIKRHFQH3.example.com. 300 IN NSEC3 1 0 0 - (
+                   TQ9QBEGA6CROHEOC8KIH1A2C06IVQ5ER
+                   NS SOA RRSIG DNSKEY NSEC3PARAM )
+   ...
+
+Our example used four parameters: 1, 0, 0, and -, in
+order. 1 represents the algorithm, 0 represents the
+opt-out flag, 0 represents the number of additional iterations, and
+- denotes no salt is used. To learn more about each of these
+parameters, please see :ref:`advanced_discussions_nsec3param`.
+
+.. _recipes_nsec3_to_nsec:
+
+Migrating from NSEC3 to NSEC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Migrating from NSEC3 back to NSEC is easy; just remove the :any:`nsec3param`
+configuration option from your :any:`dnssec-policy` and reconfigure the name
+server. You can tell that it worked if you see these messages in the log:
+
+::
+
+   named[14093]: received control channel command 'reconfig'
+   named[14093]: zone example.com/IN: zone_addnsec3chain(1,REMOVE,0,-)
+
+You can also query for a name that you know does not exist,
+and you should no longer see any traces of NSEC3 records.
+
+::
+
+   $ dig @192.168.1.13 reieiergiuhewhiouwe.example.com. A +dnssec +multiline
+
+   ...
+   example.com.        300 IN NSEC aaa.example.com. NS SOA RRSIG NSEC DNSKEY
+   ...
+   ns1.example.com.    300 IN NSEC web.example.com. A RRSIG NSEC
+   ...
+
+.. _recipes_nsec3_optout:
+
+NSEC3 Opt-Out
+^^^^^^^^^^^^^
+
+This recipe discusses how to enable and disable NSEC3 opt-out, and how to show
+the results of each action. As discussed in
+:ref:`advanced_discussions_nsec3_optout`, NSEC3 opt-out is a feature
+that can help conserve resources on parent zones with many
+delegations that have not yet been signed.
+
+.. warning::
+   NSEC3 Opt-Out feature brings benefit only to _extremely_ large zones with lots
+   of insecure delegations. It's use is counterproductive in all other cases as
+   it decreases tamper-resistance of the zone and also decreases efficiency of
+   resolver cache (see :rfc:`8198`).
+
+   In other words, don't enable Opt-Out unless you are serving an equivalent of
+   ``com.`` zone.
+
+Because the NSEC3PARAM record does not keep track of whether opt-out is used,
+it is hard to check whether changes need to be made to the NSEC3 chain if the flag
+is changed. Similar to changing the NSEC3 salt, your best option is to change
+the value of ``optout`` together with another NSEC3 parameter, like
+``iterations``, and in a following step restore the ``iterations`` value.
+
+For this recipe we assume the zone ``example.com``
+has the following four entries (for this example, it is not relevant what
+record types these entries are):
+
+-  ``ns1.example.com``
+
+-  ``ftp.example.com``
+
+-  ``www.example.com``
+
+-  ``web.example.com``
+
+And the zone ``example.com`` has five delegations to five subdomains, only one of
+which is signed and has a valid DS RRset:
+
+-  ``aaa.example.com``, not signed
+
+-  ``bbb.example.com``, signed
+
+-  ``ccc.example.com``, not signed
+
+-  ``ddd.example.com``, not signed
+
+-  ``eee.example.com``, not signed
+
+Before enabling NSEC3 opt-out, the zone ``example.com`` contains ten
+NSEC3 records; below is the list with the plain text name before the actual
+NSEC3 record:
+
+-  *aaa.example.com*: IFA1I3IE7EKCTPHM6R58URO3Q846I52M.example.com
+
+-  *bbb.example.com*: ROJUF3VJSJO6LQ2LC1DNSJ5GBAUJPVHE.example.com
+
+-  *ccc.example.com*: 0VPUT696LUVDPDS5NIHSHBH9KLV20V5K.example.com
+
+-  *ddd.example.com*: UHPBD5U4HRGB84MLC2NQOVEFNAKJU0CA.example.com
+
+-  *eee.example.com*: NF7I61FA4C2UEKPMEDSOC25FE0UJIMKT.example.com
+
+-  *ftp.example.com*: 8P15KCUAT1RHCSDN46HBQVPI5T532IN1.example.com
+
+-  *ns1.example.com*: GUFVRA2SFIO8RSFP7UO41E8AD1KR41FH.example.com
+
+-  *web.example.com*: CVQ4LA4ALPQIAO2H3N2RB6IR8UHM91E7.example.com
+
+-  *www.example.com*: MIFDNDT3NFF3OD53O7TLA1HRFF95JKUK.example.com
+
+-  *example.com*: ONIB9MGUB9H0RML3CDF5BGRJ59DKJHVK.example.com
+
+We can enable NSEC3 opt-out with the following configuration, changing
+the ``optout`` configuration value from ``no`` to ``yes``:
+
+::
+
+   dnssec-policy "standard" {
+       nsec3param iterations 0 optout yes salt-length 0;
+   };
+
+After NSEC3 opt-out is enabled, the number of NSEC3 records is reduced.
+Notice that the unsigned delegations ``aaa``, ``ccc``, ``ddd``, and
+``eee`` no longer have corresponding NSEC3 records.
+
+-  *bbb.example.com*: ROJUF3VJSJO6LQ2LC1DNSJ5GBAUJPVHE.example.com
+
+-  *ftp.example.com*: 8P15KCUAT1RHCSDN46HBQVPI5T532IN1.example.com
+
+-  *ns1.example.com*: GUFVRA2SFIO8RSFP7UO41E8AD1KR41FH.example.com
+
+-  *web.example.com*: CVQ4LA4ALPQIAO2H3N2RB6IR8UHM91E7.example.com
+
+-  *www.example.com*: MIFDNDT3NFF3OD53O7TLA1HRFF95JKUK.example.com
+
+-  *example.com*: ONIB9MGUB9H0RML3CDF5BGRJ59DKJHVK.example.com
+
+To undo NSEC3 opt-out, change the configuration again:
+
+::
+
+   dnssec-policy "standard" {
+       nsec3param iterations 0 optout no salt-length 0;
+   };
+
+.. note::
+
+   NSEC3 hashes the plain text domain name, and we can compute our own
+   hashes using the tool :iscman:`nsec3hash`. For example, to compute the
+   hashed name for ``www.example.com`` using the parameters we listed
+   above, we can execute this command:
+
+   ::
+
+      # nsec3hash - 1 0 www.example.com.
+      MIFDNDT3NFF3OD53O7TLA1HRFF95JKUK (salt=-, hash=1, iterations=0)
+
+.. _revert_to_unsigned:
+
+Reverting to Unsigned
+~~~~~~~~~~~~~~~~~~~~~
+
+This recipe describes how to revert from a signed zone (DNSSEC) back to
+an unsigned (DNS) zone.
+
+Here is what :iscman:`named.conf` looks like when it is signed:
+
+.. code-block:: none
+  :emphasize-lines: 4
+
+   zone "example.com" IN {
+       type primary;
+       file "db/example.com.db";
+       dnssec-policy "default";
+       inline-signing yes;
+   };
+
+To indicate the reversion to unsigned, change the :any:`dnssec-policy` line:
+
+.. code-block:: none
+  :emphasize-lines: 4
+
+   zone "example.com" IN {
+       type primary;
+       file "db/example.com.db";
+       dnssec-policy "insecure";
+       inline-signing yes;
+   };
+
+Then use :option:`rndc reload` to reload the zone.
+
+The "insecure" policy is a built-in policy (like "default"). It makes sure
+the zone is still DNSSEC-maintained, to allow for a graceful transition to
+unsigned. It also publishes the CDS and CDNSKEY DELETE records automatically
+at the appropriate time.
+
+If the parent zone allows management of DS records via CDS/CDNSKEY, as described in
+:rfc:`8078`, the DS record should be removed from the parent automatically.
+
+Otherwise, DS records can be removed via the registrar. Below is an example
+showing how to remove DS records using the
+`GoDaddy <https://www.godaddy.com>`__ web-based interface:
+
+1. After logging in, click the green "Launch" button next to the domain
+   name you want to manage.
+
+.. _unsign-1:
+
+   .. figure:: ../dnssec-guide/img/unsign-1.png
+      :alt: Revert to Unsigned Step #1
+      :width: 60.0%
+
+      Revert to Unsigned Step #1
+
+2. Scroll down to the "DS Records" section and click Manage.
+
+.. _unsign-2:
+
+   .. figure:: ../dnssec-guide/img/unsign-2.png
+      :alt: Revert to Unsigned Step #2
+      :width: 40.0%
+
+      Revert to Unsigned Step #2
+
+3. A dialog appears, displaying all current keys. Use the far right-hand
+   X button to remove each key.
+
+.. _unsign-3:
+
+   .. figure:: ../dnssec-guide/img/unsign-3.png
+      :alt: Revert to Unsigned Step #3
+      :width: 70.0%
+
+      Revert to Unsigned Step #3
+
+4. Click Save.
+
+.. _unsign-4:
+
+   .. figure:: ../dnssec-guide/img/unsign-4.png
+      :alt: Revert to Unsigned Step #4
+      :width: 70.0%
+
+      Revert to Unsigned Step #4
+
+When the DS records have been removed from the parent zone, use
+:option:`rndc dnssec -checkds -key id withdrawn example.com <rndc dnssec>` to tell :iscman:`named` that
+the DS is removed, and the remaining DNSSEC records will be removed in a timely
+manner. Or, if parental agents are configured, the DNSSEC records will be
+automatically removed after BIND has seen that the parental agents no longer
+serve the DS RRset for this zone.
+
+After a while, the zone is reverted back to the traditional, insecure DNS
+format. This can be verified by checking that all DNSKEY and RRSIG records have been
+removed from the zone.
+
+The :any:`dnssec-policy` line can then be removed from :iscman:`named.conf` and
+the zone reloaded. The zone will no longer be subject to any DNSSEC
+maintenance.