From: Peter van Dijk Date: Wed, 16 Mar 2022 11:36:06 +0000 (+0100) Subject: auth docs: add algorithm rolling guide X-Git-Tag: rec-4.7.0-beta1~54^2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=627a85357bb2e6467303c96dd31a0d15616c3ade;p=thirdparty%2Fpdns.git auth docs: add algorithm rolling guide --- diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt index 2cb4babb2b..db0c7250cb 100644 --- a/.github/actions/spell-check/expect.txt +++ b/.github/actions/spell-check/expect.txt @@ -31,6 +31,7 @@ Aki Alenichev alexa algo +algoroll aliceblue allocs Altpeter @@ -416,6 +417,7 @@ dnstcpbench dnstree dnsttl dnsupdate +dnsviz dnswasher dnszone dnt diff --git a/docs/guides/algoroll.rst b/docs/guides/algoroll.rst new file mode 100644 index 0000000000..8b388ae23f --- /dev/null +++ b/docs/guides/algoroll.rst @@ -0,0 +1,132 @@ +Algorithm Rollover +================== + +Before attempting an algorithm rollover, please read :rfc:`RFC 6581 "DNSSEC Operational Practices, Version 2", section 4 <6781#section-4>` carefully to understand the terminology, actions and timelines (TTL and RRSIG expiry) involved in changing DNSKEY algorithms. + +This How To describes the "conservative" approach from the above mentioned RFC, as specified in :rfc:`section 4.1.4 <6781#section-4.1.4>`. +Phases are named after the steps in the diagram in that section. +The following instruction assume a KSK+ZSK setup; if you only have a CSK, ignore the ZSK steps. + + +After every change, use your favourite DNSSEC checker (`DNSViz `__, `VeriSign DNSSEC Analyzer `__, a validating resolver) to make sure no mistakes have crept in. + +During this process, response sizes will be larger than usual, due to double sets of signatures, and double the amount of DNSKEYs. +Please check that these bigger packets can make it out of your network without trouble, and verify that you and your secondaries can serve queries over TCP as well. + +.. warning:: + + For every mutation to your zone (so, every step except updating DS in the parent), make sure that your serial is bumped, so your secondaries pick up the changes too. + If you are using AXFR replication, this usually is as simple as ``pdnsutil increase-serial example.com`` + +Phase: initial +-------------- + +In the ``initial`` situation, we have a KSK+ZSK with our old algorithm, and the parent zone contains a DS matching that KSK. +Assuming this situation has existed for a few days, or perhaps way longer, we can move on to the ``new RRSIGs`` phase without delay. + +Phase: new RRSIGs +----------------- + +To create signatures with the new algorithm, without publishing keys, run something like: + +.. code-block:: shell + + pdnsutil add-zone-key example.com KSK active unpublished ecdsa384 + pdnsutil add-zone-key example.com ZSK active unpublished ecdsa384 + +Note the key IDs that add-zone-key reports. +You can also retrieve these later with ``pdnsutil show-zone example.com``. + +After this, PowerDNS will sign all records in the zone with both the old and new ZSKs, and the DNSKEY set will be signed by both KSKs. + +Please check that your secondaries also show the new signatures. + +In the next step, we will publish the new keys. +Once we do that, some validators will demand that those new keys also sign all records in the zone. +However, those validators may still have records signed with only the old ZSK in cache. +So, we need to wait for those records to expire. + +In your zone, check for the highest TTL you can find. +This includes the SOA TTL and the SOA MINIMUM, which affect negative caching, including NSEC/NSEC3 records. +:ref:`The DNSKEY TTL is also taken from the SOA MINIMUM.` + +Now, wait for that long. +Depending on your setup, this will usually be between a few hours and a few days. + +Phase: new DNSKEY +----------------- + +In the previous step, we generated two new keys, and signed our zone with them, without actually exposing validators to the new keys. +After waiting for all records in our zone to expire from caches, we can publish the DNSKEYs: + +.. code-block:: shell + + pdnsutil publish-zone-key example.com 3 + pdnsutil publish-zone-key example.com 4 + +Replace ``3`` and ``4`` with the key IDs gathered in the previous step, or find them in ``pdnsutil show-zone example.com``. +PowerDNS will now publish the new DNSKEYs that have already been used for signing for a while. +The old DNSKEYs remain published, and active for signing, for now. + +Please check that your secondaries now show both the old and new DNSKEYs when queried for them with ``dig DNSKEY example.com @...``. + +Now that the new DNSKEYs are published, we again need to wait for caches to pick them up, before we switch DS records in the parent. + +Check the DNSKEY TTL - then wait that long. + +Phase: new DS +------------- + +Our zone is currently fully signed with two algorithms, and keys for both algorithms are published. +This means that a DS for either the old or new algorithm is sufficient for validation. +So, we can switch the DS - there is no need to have DSes for both algorithms in the parent zone. + +Using ``pdnsutil show-zone example.com`` or ``pdnsutil export-zone-ds example.com``, extract the new DNSKEYs or new DSes, depending on what the parent zone operator takes as input. +Note that these commands print DNSKEYs and/or DSes for both the old and the new algorithm. + +Check the DS TTL at the parent, for example: ``dig DS example.com @c.gtld-servers.net`` for a delegation from ``.com``. + +Submit the new algorithm DNSKEY/DSes to the parent, and make sure to delete those for the old algorithm. + +Check again with the parent to see whether the new DS is published. + +Then, wait for as long as the TTL on the old DS was. + +Phase: DNSKEY removal +--------------------- + +We are signing with two algorithms. +The parent DS is pointing at the KSK for the new algorithm, and the old DS has expired from all caches. +However, both sets of DNSKEYs are still in caches. +It is time to remove the old DNSKEYs, while keeping their signature: + +.. code-block:: shell + + pdnsutil unpublish-zone-key example.com 1 + pdnsutil unpublish-zone-key example.com 2 + +Replace ``1`` and ``2`` with the IDs of the old keys. + +Please check that your secondaries now only show the new set of keys when queried with ``dig DNSKEY example.com @...``. + +Over the next DNSKEY TTL seconds, validators can still have both sets of keys in cache. +So, we leave our signatures in until that time passes. + +Phase: RRSIGs removal +--------------------- + +After waiting DNSKEY TTL seconds, caches should only have a copy of our new set of keys. +This means we can now safely stop signing with the old keys: + +.. code-block:: shell + + pdnsutil deactivate-zone-key example.com 1 + pdnsutil deactivate-zone-key example.com 2 + +Alternatively, you can use ``remove-zone-key`` to remove all traces of the old keys. + +Conclusion +---------- + +In another hours-to-a-few-days, the old signatures will have expired from caches. +Your algorithm roll is complete. \ No newline at end of file diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 3b6ded0ad5..4363d81599 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -12,5 +12,6 @@ Guides and How Tos kskroll kskrollcdnskey zskroll + algoroll addingrecords