From da0ae5299f51c0ffdd4edc3b880d105a64590cf6 Mon Sep 17 00:00:00 2001
From: Matthijs Mekking <matthijs@isc.org>
Date: Tue, 1 Oct 2019 15:40:01 +0200
Subject: [PATCH] arm: Update DNSSEC documentation

---
 doc/arm/dnssec.xml | 37 +++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/doc/arm/dnssec.xml b/doc/arm/dnssec.xml
index 6210a12a7f..be702849c3 100644
--- a/doc/arm/dnssec.xml
+++ b/doc/arm/dnssec.xml
@@ -16,9 +16,10 @@
 
   </section>
   <para>
-    Changing a zone from insecure to secure can be done in two
-    ways: using a dynamic DNS update, or the
-    <command>auto-dnssec</command> zone option.
+    Changing a zone from insecure to secure can be done in three
+    ways: using a dynamic DNS update, use the
+    <command>auto-dnssec</command> zone option, or set a DNSSEC
+    policy for the zone with <command>dnssec-policy</command>.
   </para>
   <para>
     For either method, you need to configure
@@ -26,8 +27,9 @@
     <filename>K*</filename> files which contain the public and private
     parts of the keys that will be used to sign the zone. These files
     will have been generated by
-    <command>dnssec-keygen</command>. You can do this by placing them
-    in the key-directory, as specified in
+    <command>dnssec-keygen</command> (or created when needed by
+    <command>named</command> if <command>dnssec-policy</command> is
+    used).  Keys should be placed in the key-directory, as specified in
     <filename>named.conf</filename>:</para>
     <programlisting>
 	zone example.net {
@@ -44,6 +46,18 @@
     well. An NSEC chain will be generated as part of the initial
     signing process.
   </para>
+  <para>
+    With <command>dnssec-policy</command> you specify what keys should
+    be KSK and/or ZSK. If you want a key to sign all records with a key
+    you will need to specify a CSK:
+  </para>
+  <programlisting>
+	dnssec-policy csk {
+		keys {
+			csk key-directory P5Y 13;
+		};
+	};
+  </programlisting>
 
   <section><info><title>Dynamic DNS update method</title></info>
 
@@ -95,7 +109,8 @@
 
   </section>
   <para>
-    To enable automatic signing, add the
+    To enable automatic signing, you can set a
+    <command>dnssec-policy</command>, or add the
     <command>auto-dnssec</command> option to the zone statement in
     <filename>named.conf</filename>.
     <command>auto-dnssec</command> has two possible arguments:
@@ -117,6 +132,13 @@
     (See <xref linkend="man.dnssec-keygen"/> and
     <xref linkend="man.dnssec-settime"/> for more information.)
   </para>
+  <para>
+    <command>dnssec-policy</command> is like
+    <command>auto-dnssec maintain</command>, but will also automatically
+    create new keys when necessary.  Also any configuration related
+    to DNSSEC signing is retrieved from the policy (ignoring existing
+    DNSSEC named.conf options).
+  </para>
   <para>
     <command>named</command> will periodically search the key directory
     for keys matching the zone, and if the keys' metadata indicates
@@ -288,6 +310,9 @@
     chain will be generated before the NSEC chain is
     destroyed.
   </para>
+  <para>
+    NSEC3 is not supported yet with <command>dnssec-policy</command>.
+  </para>
 
   <section><info><title>Converting from NSEC3 to NSEC</title></info>