doc: algorithm rollover with keymgr described

doc/operation.rst

@@ -277,6 +277,54 @@ each other, e.g. periodically changing few zone records, re-signing whole zone..
 The diff between zone file and zone is thus preserved, even if journal deletes some
 older changesets.
 
+.. _Algorithm rollover:
+
+DNSSEC keys algorithm rollover
+==============================
+
+Algorithm rollover is a process of changing DNSSEC signing keys, where the
+new keys are of different algorithm. The zone signatures must never go Bogus
+during the process, even considering records cached in resolvers. The process
+is generally described in RFC 6781. Following are some hints how to implement
+algorithm rollover when using Knot DNS.
+
+The prerequisite is having a zone with automatic DNSSEC signing enabled, active
+KSK and ZSK present. (The CSK case should work analogously, not mentioned further.)
+It is recommended to disable automatic key management during the rollover. Note
+that from the view of common key rollovers, here we must put the keys into a weird
+state: active, but not published. This is done by hard-setting their timers so that
+created <= active < publish < retire.
+
+First we need to generate new keys. They must be first used for signing, and
+after some period (propagation delay let's say 1h + zone records' TTL let's say
+1h) published. We have to preprate the timestamps carefully, using the notation
+'now+2h' can be creepy with "now" changing between the Keymgr invokes. We then
+resign the zone just to force knotd to reload zone keys::
+
+  $ NOW=$(date +%s)
+  $ NOW2H=$((NOW + 7200))
+  $ keymgr example.com. generate algorithm=14 size=384 ksk=yes \
+                                 ready=$NOW2H active=0 publish=$NOW2H
+  $ keymgr example.com. generate algorithm=14 size=384 ksk=no \
+                                 ready=$NOW active=$NOW publish=$NOW2H
+  $ knotc zone-sign example.com.
+
+After waiting for the keys to get published as scheduled, we may tell the parent
+zone operator to renew our DS record. As the KSK is in ready state, we have the
+CDS/CDNSKEY records in our zone. After waiting again for some propagation period,
+we continue with removing old KSK and putting old ZSK into active-not-published
+state (we must first obtain the keys' IDs with 'keymgr example.com. list'). We may
+also confirm the new KSK submission (which reloads KASP DB as a side-effect)::
+
+  $ keymgr example.com. set $OLD_KSK_ID retire=now+0 remove=now+0
+  $ keymgr example.com. set $OLD_ZSK_ID publish=0
+  $ knotc zone-ksk-submitted example.com.
+
+Finally, after one more propagation period, we remove old ZSK::
+
+  $ keymgr example.com. set $OLD_ZSK_ID retire=now+0 remove=now+1
+  $ knotc zone-sign example.com.
+
 .. _Controlling running daemon:
 
 Daemon controls