From: Jindrich Roessler Date: Fri, 18 Mar 2022 11:48:41 +0000 (+0100) Subject: updated KSK and ZSK Rollover procedures, small fixes in Algorithm Rollover procedure X-Git-Tag: auth-4.9.0-beta2~2^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fd1dd46b6f1c602e66eda0d7754952dc353fcacd;p=thirdparty%2Fpdns.git updated KSK and ZSK Rollover procedures, small fixes in Algorithm Rollover procedure --- diff --git a/docs/guides/algoroll.rst b/docs/guides/algoroll.rst index 849b6d7639..21badf4e92 100644 --- a/docs/guides/algoroll.rst +++ b/docs/guides/algoroll.rst @@ -79,7 +79,7 @@ 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. +We can now 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. @@ -128,5 +128,6 @@ Alternatively, you can use ``remove-zone-key`` to remove all traces of the old k Conclusion ---------- -In another hours-to-a-few-days, the old signatures will have expired from caches. +In another hours-to-a-few-days, the old signatures will expire from caches. + Your algorithm roll is complete. \ No newline at end of file diff --git a/docs/guides/kskroll.rst b/docs/guides/kskroll.rst index a444210ef1..a73892d364 100644 --- a/docs/guides/kskroll.rst +++ b/docs/guides/kskroll.rst @@ -1,46 +1,81 @@ KSK Rollover ============ -Before attempting a KSK rollover, please read :rfc:`RFC 6781 "DNSSEC -Operational Practices, Version 2", section 4 <6781#section-4>` carefully to -understand the terminology, actions and timelines (TTL and RRSIG expiry) -involved in rolling a KSK. +Before attempting a KSK rollover, please read :rfc:`RFC 6781 "DNSSEC Operational Practices, Version 2", section 4 <6781#section-4>` carefully to understand the terminology, actions and timelines (TTL and RRSIG expiry) involved in rolling a KSK. -This How To describes the "Double-Signature Key Signing Key Rollover" -from the above mentioned RFC. The following instruction work for -both a KSK and a CSK. +This How To describes the "Double-Signature" scheme from the above mentioned RFC, as specified in :rfc:`section 4.1.2 <6781#section-4.1.2>`. +Phases are named after the steps in the diagram in that section. -To start the rollover, add an **active** new KSK to the zone -(example.net in this case): +After every change, use your favourite DNSSEC checker (`DNSViz `__, `VeriSign DNSSEC Analyzer `__, a validating resolver) to make sure no mistakes have crept in. -.. code-block:: shell +.. warning:: + + For every mutation to your zone 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 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 DNSKEY`` phase without delay. + +Phase: new DNSKEY +----------------- - pdnsutil add-zone-key example.net ksk active +At first note down algorithm of currently used KSK, because new KSK shall use the same one, by running following command: -Note that a key with same algorithm as the KSK to be replaced should be -created, as this is not an algorithm roll over. +.. code-block:: shell + + pdnsutil show-zone example.com -If this zone is of the type 'MASTER', increase the SOA serial. The -rollover is now in the "New KSK" stage. Retrieve the DS record(s) for -the new KSK: +To create a new **active** and **published** KSK with the same algorithm for the zone, run something like: .. code-block:: shell - pdnsutil show-zone example.net + pdnsutil add-zone-key example.com ksk active published ALGORITHM + +Please note down the key ID that ``add-zone-key`` reports. You can also retrieve it later with ``pdnsutil show-zone example.com``. + +After this the DNSKEY set will be signed by both KSKs. + +Please check that your secondaries now show both the old and new DNSKEYs when queried for them with ``dig DNSKEY example.com @...``. -And communicate this securely to your registrar/parent zone, replacing -the existing data. Now wait until the new DS is published in the -parent zone and at least the TTL for the DS records has passed. The -rollover is now in the "DS Change" state and can continue to the -"DNSKEY Removal" stage by actually deleting the old KSK. +Now that the new DNSKEY is active and published, we need to wait for caches to pick it up. Check the DNSKEY TTL and then wait for at least that long. -.. note:: - The key-id for the old KSK is shown in the output of - ``pdnsutil show-zone example.net``. +Phase: DS change +---------------- + +The DNSKEY set is currently signed with both KSKs and keys of both are published. +This means that a DS for either old or new KSK is sufficient for validation. +We can now switch the DS record in the parent zone - there is no need to have DSes for both KSKs in the parent zone. + +Using ``pdnsutil show-zone example.com`` or ``pdnsutil export-zone-ds example.com``, extract the DNSKEY or DS for new KSK, 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 KSK. + +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 DNSKEY and/or DS for of new KSK to the parent, and make sure to delete those for the old KSK. + +Check again with the parent to see whether the new DS is published. + +Then, wait for at least as long as the TTL for the old DS was. + +Phase: DNSKEY removal +--------------------- + +The parent DS is pointing at the new KSK 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 DNSKEY: .. code-block:: shell - pdnsutil remove-zone-key example.net KEY-ID + pdnsutil remove-zone-key example.com OLD_KSK_ID + +Please check that your secondaries now only show the new set of keys when queried with ``dig DNSKEY example.com @...``. + +Conclusion +---------- + +After at least another DNSKEY TTL time the old DNSKEY shall expire from caches. -If this zone is of the type 'MASTER', increase the SOA serial. -The rollover is now complete. +Your KSK Rollover is complete. \ No newline at end of file diff --git a/docs/guides/zskroll.rst b/docs/guides/zskroll.rst index aa7631a07c..22b73e6ba3 100644 --- a/docs/guides/zskroll.rst +++ b/docs/guides/zskroll.rst @@ -1,42 +1,86 @@ ZSK Rollover ============ -This how to describes the way to roll a ZSK that is not a secure -entrypoint (a ZSK that is not tied to a DS record in the parent zone) -using the :rfc:`"RFC 6781 Pre-Publish Zone Signing Key -Rollover" <6781#section-4.1.1.1>` -method. The documentation linked above also lists the minimum time -between stages. **PLEASE READ THAT DOCUMENT CAREFULLY** +Before attempting a ZSK rollover, please read :rfc:`RFC 6781 "DNSSEC Operational Practices, Version 2", section 4 <6781#section-4>` carefully to understand the terminology, actions and timelines (TTL and RRSIG expiry) involved in rolling a ZSK. -First, create a new inactive ZSK for the zone (if one already exists, -you can skip this step), we add an ECDSA 256 bit key (algorithm 13) -here: +This How To describes the "Pre-Publish" approach from the above mentioned RFC, as specified in :rfc:`section 4.1.1.1 <6781#section-4.1.1.1>`. +Phases are named after the steps in the diagram in that section. + +.. warning:: + + The following instructions assume rollover of a key which is NOT a Secure Entry Point (SEP), please confirm this fact before proceeding any further. + +After every change, use your favourite DNSSEC checker (`DNSViz `__, `VeriSign DNSSEC Analyzer `__, a validating resolver) to make sure no mistakes have crept in. + +.. warning:: + + For every mutation to your zone 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 old ZSK key used to sign all the data in the zone. +Assuming this situation has existed for a few days, or perhaps way longer, we can move on to the ``new DNSKEY`` phase without delay. + +Phase: new DNSKEY +----------------- + +At first note down algorithm of currently used ZSK, because new ZSK shall use the same one, by running following command: + +.. code-block:: shell + + pdnsutil show-zone example.com + +To create a new **inactive** but **published** ZSK with the same algorithm, run something like: .. code-block:: shell - pdnsutil add-zone-key example.net zsk inactive ecdsa256 + pdnsutil add-zone-key example.com zsk inactive published ALGORITHM + +Please note down the key ID that ``add-zone-key`` reports. You can also retrieve it later with ``pdnsutil show-zone example.com``. + +PowerDNS will now publish the new DNSKEY while the old DNSKEY remains published and active for signing. -You are now almost at the "new DNSKEY"-stage of the rollover, if the -zone is of type 'MASTER' you'll need to update the SOA serial in the -database and wait for the slaves to pickup the zone change. +Please check that your secondaries now show both the old and new DNSKEYs when queried for them with ``dig DNSKEY example.com @...``. -To change the RRSIGs on your records, the new key must be made active. -Note: you can get the key-ids with ``pdnsutil show-zone example.net``: +Now that the new DNSKEY is published, we need to wait for caches to pick it up. Check the DNSKEY TTL and then wait at least that long. + +Phase: new RRSIGs +----------------- + +To change the RRSIGs on records in the zone, the new DNSKEY must be made active and the old DNSKEY must be made inactive. .. code-block:: shell - pdnsutil activate-zone-key example.net new-key-id - pdnsutil deactivate-zone-key example.net previous-key-id + pdnsutil activate-zone-key example.com NEW-ZSK-ID + pdnsutil deactivate-zone-key example.com OLD-ZSK-ID + +After this, PowerDNS will sign all records in the zone with the new ZSK and remove all signatures made with the old ZSK. -Again, if this is a 'MASTER'-zone, update the SOA serial. You are now at -the "new RRSIGs" stage of the roll over. +Please check that your secondaries now show only the new signatures. -The last step is to remove the old key from the completely: +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 at least that long. +Depending on your setup, this will usually be between a few hours and a few days. + +Phase: DNSKEY removal +--------------------- + +The last step is to remove the old DNSKEY from the zone: .. code-block:: shell - pdnsutil remove-zone-key example.net previous-key-id + pdnsutil remove-zone-key example.com OLD-ZSK-ID + +Please check that your secondaries now show only the new DNSKEY when queried with ``dig DNSKEY example.com @...``. + +Conclusion +---------- -Don't forget to update the SOA serial for 'MASTER' zones. The rollover -is now at the "DNSKEY removal" stage and complete. +After at least another DNSKEY TTL time the old DNSKEY shall expire from caches. +Your ZSK Rollover is complete. \ No newline at end of file