From c4667147da0a4f53b6f13cbc11a53bdf8a548ae2 Mon Sep 17 00:00:00 2001
From: Libor Peltan <libor.peltan@nic.cz>
Date: Wed, 26 Apr 2017 11:05:55 +0200
Subject: [PATCH] doc: shared KSK rollover

---
 doc/configuration.rst | 20 ++++++++++++++++++++
 doc/man/knot.conf.5in |  6 ++++++
 doc/reference.rst     | 10 +++++++++-
 3 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/doc/configuration.rst b/doc/configuration.rst
index d8ff450ae..6bfc06114 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -375,6 +375,26 @@ convenience delay the submittion is started. The server publishes CDS and CDNSKE
 and the user shall propagate them to the parent. The server periodically checks for
 DS at the master and when positive, finishes the rollover.
 
+To share KSKs among zones, set the ksk-shared policy parameter. It is strongly discouraged to
+change the policy ``id`` afterwards! The shared key's creation timestamp will be equal for all
+zones, but other timers (e.g. activate, retire) may get out of sync. ::
+
+  policy:
+    - id: sharedp
+      ksk-lifetime: 365d
+      ksk-shared: true
+      ksk-submittion-check: [cz_zone]
+
+  zone:
+    - domain: firstzone.test
+      dnssec-signing: on
+      dnssec-policy: sharedp
+
+  zone:
+    - domain: secondzone.test
+      dnssec-signing: on
+      dnssec-policy: sharedp
+
 .. _dnssec-manual-key-management:
 
 Manual key management
diff --git a/doc/man/knot.conf.5in b/doc/man/knot.conf.5in
index 8a93a6c3d..603a3f55c 100644
--- a/doc/man/knot.conf.5in
+++ b/doc/man/knot.conf.5in
@@ -511,6 +511,7 @@ policy:
     algorithm: dsa | rsasha1 | dsa\-nsec3\-sha1 | rsasha1\-nsec3\-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384
     ksk\-size: SIZE
     zsk\-size: SIZE
+    ksk\-shared: BOOL
     dnskey\-ttl: TIME
     zsk\-lifetime: TIME
     ksk\-lifetime: TIME
@@ -570,6 +571,11 @@ A length of newly generated KSK keys.
 A length of newly generated ZSK keys.
 .sp
 \fIDefault:\fP see default for \fI\%ksk\-size\fP
+.SS ksk\-shared
+.sp
+If enabled, all zones with this policy assigned will share one KSK.
+.sp
+\fIDefault:\fP off
 .SS dnskey\-ttl
 .sp
 A TTL value for DNSKEY records added into zone apex.
diff --git a/doc/reference.rst b/doc/reference.rst
index c36bde7f0..0d82274ff 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -571,6 +571,7 @@ DNSSEC policy configuration.
      algorithm: dsa | rsasha1 | dsa-nsec3-sha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384
      ksk-size: SIZE
      zsk-size: SIZE
+     ksk-shared: BOOL
      dnskey-ttl: TIME
      zsk-lifetime: TIME
      ksk-lifetime: TIME
@@ -651,7 +652,14 @@ A length of newly generated :abbr:`ZSK (Zone Signing Key)` keys.
 
 *Default:* see default for :ref:`ksk-size<policy_ksk-size>`
 
-.. _policy_dnskey-ttl:
+.. _policy_ksk-shared:
+
+ksk-shared
+----------
+
+If enabled, all zones with this policy assigned will share one KSK.
+
+*Default:* off
 
 dnskey-ttl
 ----------