Document initial-ds and static-ds keywords

bin/named/named.conf.docbook

@@ -13,7 +13,7 @@
 
 <refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.named.conf">
   <info>
-    <date>2019-08-07</date>
+    <date>2019-08-12</date>
   </info>
   <refentryinfo>
     <corpname>ISC</corpname>
@@ -113,7 +113,8 @@ dlz <replaceable>string</replaceable> {
   <refsection><info><title>DNSSEC-KEYS</title></info>
     <literallayout class="normal">
 dnssec-keys { <replaceable>string</replaceable> ( static-key |
-    initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
+    initial-key | static-ds | initial-ds )
+    <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
     <replaceable>quoted_string</replaceable>; ... };
 </literallayout>
   </refsection>
@@ -158,9 +159,9 @@ logging {
   <para>Deprecated - see DNSSEC-KEYS.</para>
     <literallayout class="normal">
 managed-keys { <replaceable>string</replaceable> ( static-key
-    | initial-key ) <replaceable>integer</replaceable>
+    | initial-key | static-ds |
-    <replaceable>integer</replaceable> <replaceable>integer</replaceable>
+    initial-ds ) <replaceable>integer</replaceable> <replaceable>integer</replaceable>
-    <replaceable>quoted_string</replaceable>; ... }; deprecated
+    <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... }; deprecated
 </literallayout>
   </refsection>
 
@@ -607,8 +608,9 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
 	dnssec-accept-expired <replaceable>boolean</replaceable>;
 	dnssec-dnskey-kskonly <replaceable>boolean</replaceable>;
 	dnssec-keys { <replaceable>string</replaceable> ( static-key |
-	    initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable>
+	    initial-key | static-ds | initial-ds
-	    <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
+	    ) <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
+	    <replaceable>quoted_string</replaceable>; ... };
 	dnssec-loadkeys-interval <replaceable>integer</replaceable>;
 	dnssec-must-be-secure <replaceable>string</replaceable> <replaceable>boolean</replaceable>;
 	dnssec-secure-to-insecure <replaceable>boolean</replaceable>;
@@ -646,6 +648,7 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
 	lmdb-mapsize <replaceable>sizeval</replaceable>;
 	managed-keys { <replaceable>string</replaceable> (
 	    static-key | initial-key
+	    | static-ds | initial-ds
 	    ) <replaceable>integer</replaceable> <replaceable>integer</replaceable>
 	    <replaceable>integer</replaceable>
 	    <replaceable>quoted_string</replaceable>; ... }; deprecated

doc/arm/Bv9ARM-book.xml

@@ -2230,13 +2230,14 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
 	  The keys specified in <command>dnssec-keys</command>
 	  copies of DNSKEY RRs for zones that are used to form the
 	  first link in the cryptographic chain of trust.  Keys configured
-	  with the keyword <command>static-key</command> are loaded directly
+	  with the keyword <command>static-key</command> or
+	  <command>static-ds</command> are loaded directly
 	  into the table of trust anchors, and can only be changed by
 	  altering the configuration. Keys configured with
-	  <command>initial-key</command> are used to initialize
+	  <command>initial-key</command> or <command>initial-ds</command>
-	  RFC 5011 trust anchor maintenance, and will be kept up to
+	  are used to initialize RFC 5011 trust anchor maintenance, and
-	  date automatically after the first time <command>named</command>
+	  will be kept up to date automatically after the first time
-	  runs.
+	  <command>named</command> runs.
 	</para>
 
 	<para>
@@ -2276,17 +2277,7 @@ dnssec-keys {
 				 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ
 				 dgxbcDTClU0CRBdiieyLMNzXG3";
 	/* Key for our organization's forward zone */
-	example.com. static-key 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6
+	example.com. static-ds 54135 5 2 "8EF922C97F1D07B23134440F19682E7519ADDAE180E20B1B1EC52E7F58B2831D"
-			      5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z
-			      GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb
-			      4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL
-			      kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O
-			      g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S
-			      TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq
-			      FxmAVZP20igTixin/1LcrgX/KMEGd/biuv
-			      F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm
-			      /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o
-			      1OTQ09A0=";
 
 	/* Key for our reverse zone. */
 	2.0.192.IN-ADDRPA.NET. static-key 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc
@@ -3215,11 +3206,14 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
 	      </entry>
 	      <entry colname="2">
 		<para>
-		  defines DNSSEC keys: if used with the
+		  defines DNSSEC trust anchors: if used with
-		  <command>initial-key</command> keyword,
+		  the <command>initial-key</command> or
-		  keys are kept up to date using RFC 5011
+		  <command>initial-ds</command> keyword,
-		  trust anchor maintenance, and if used with
+		  trust anchors are kept up to date using RFC
-		  <command>static-key</command>, keys are permanent.
+		  5011 trust anchor maintenance, and if used with
+		  <command>static-key</command> or
+		  <command>static-ds</command>, trust anchors
+		  are permanent.
 		</para>
 	      </entry>
 	    </row>
@@ -4628,7 +4622,8 @@ badresp:1,adberr:0,findfail:0,valfail:0]
 	      <para>
 		Specifies the directory in which to store the files that
 		track managed DNSSEC keys (i.e., those configured using
-		the <command>initial-key</command> keyword in a
+		the <command>initial-key</command> or
+		<command>initial-ds</command> keywords in a
 		<command>dnssec-keys</command> statement).  By default,
 		this is the working directory.  The directory
 		<emphasis>must</emphasis> be writable by the effective
@@ -10864,12 +10859,12 @@ example.com                 CNAME   rpz-tcp-only.
 	    trust anchors.  DNSSEC is described in <xref linkend="DNSSEC"/>.
 	  </para>
 	  <para>
-	    A trust anchor is defined when the public key for
+	    A trust anchor is defined when the public key or public key
-	    a non-authoritative zone is known, but cannot be securely
+	    digest for a non-authoritative zone is known, but cannot be
-	    obtained through DNS, either because it is the DNS root zone
+	    securely obtained through DNS, either because it is the DNS
-	    or because its parent zone is unsigned.  Once a key has been
+	    root zone or because its parent zone is unsigned.  Once a key
-	    configured as a trust anchor, it is treated as if it had
+	    or digest has been configured as a trust anchor, it is treated
-	    been validated and proven secure.
+	    as if it had been validated and proven secure.
 	  </para>
 	  <para>
 	    The resolver attempts DNSSEC validation on all DNS data
@@ -10881,19 +10876,9 @@ example.com                 CNAME   rpz-tcp-only.
 	  <para>
 	    All keys listed in <command>dnssec-keys</command>, and
 	    their corresponding zones, are deemed to exist regardless
-	    of what parent zones say.   Only keys configured as trust anchors
+	    of what parent zones say.  Only keys configured as trust anchors
 	    are used to validate the DNSKEY RRset for the corresponding
-	    name.  The parent's DS RRset will not be used.
+	    name. The parent's DS RRset will not be used.
-	  </para>
-	  <para>
-	    The <command>dnssec-keys</command> statement can contain
-	    multiple key entries, each consisting of the key's
-	    domain name, followed by the <command>static-key</command> or
-	    <command>initial-key</command> keyword, then the key's flags,
-	    protocol, algorithm, and the Base64 representation of the key
-	    data.  Spaces, tabs, newlines and carriage returns are ignored
-	    in the key data, so the configuration may be split up into
-	    multiple lines.
 	  </para>
 	  <para>
 	    <command>dnssec-keys</command> may be set at the top level
@@ -10903,11 +10888,33 @@ example.com                 CNAME   rpz-tcp-only.
 	    defined in a view are only used within that view.
 	  </para>
 	  <para>
-	    <command>dnssec-keys</command> entries can be configured with
+	    The <command>dnssec-keys</command> statement can contain
-	    two keywords: <command>static-key</command> or
+	    multiple trust anchor entries, each consisting of a
-	    <command>initial-key</command>.  Keys configured with
+	    domain name, followed by an "anchor type" keyword indicating
-	    <command>static-key</command> are immutable,
+	    the trust anchor's format, followed by the key or digest data.
-	    while keys configured with <command>initial-key</command>
+	  </para>
+	  <para>
+	    If the anchor type is <command>static-key</command> or
+	    <command>initial-key</command>, then it is followed with the
+	    key's flags, protocol, algorithm, and the Base64 representation
+	    of the public key data. This is identical to the text
+	    representation of a DNSKEY record.  Spaces, tabs, newlines and
+	    carriage returns are ignored in the key data, so the
+	    configuration may be split up into multiple lines.
+	  </para>
+	  <para>
+	    If the anchor type is <command>static-ds</command> or
+	    <command>initial-ds</command>, then it is followed with the
+	    key tag, algorithm, digest type, and the hexidecimal
+	    representation of the key digest. This is identical to the
+	    text representation of a DS record.  Spaces, tabs, newlines
+	    and carriage returns are ignored.
+	  </para>
+	  <para>
+	    Trust anchors configured with the
+	    <command>static-key</command> or <command>static-ds</command>
+	    anchor types are immutable, while keys configured with
+	    <command>initial-key</command> or <command>initial-ds</command>
 	    can be kept up to date automatically, without intervention
 	    from the resolver operator. (<command>static-key</command>
 	    keys are identical to keys configured using the deprecated
@@ -10917,45 +10924,55 @@ example.com                 CNAME   rpz-tcp-only.
 	    Suppose, for example, that a zone's key-signing
 	    key was compromised, and the zone owner had to revoke and
 	    replace the key.  A resolver which had the original key
-	    configured as a <command>static-key</command> would be
+	    configured using <command>static-key</command> or
-	    unable to validate this zone any longer; it would
+	    <command>static-ds</command> would be unable to validate
-	    reply with a SERVFAIL response code.  This would
+	    this zone any longer; it would reply with a SERVFAIL response
-	    continue until the resolver operator had updated the
+	    code.  This would continue until the resolver operator had
-	    <command>dnssec-keys</command> statement with the new key.
+	    updated the <command>dnssec-keys</command> statement with
+	    the new key.
 	  </para>
 	  <para>
 	    If, however, the trust anchor had been configured with
-	    <command>initial-key</command> instead, then the
+	    <command>initial-key</command> or <command>initial-ds</command>
-	    zone owner could add a "stand-by" key to their zone in advance.
+	    instead, then the zone owner could add a "stand-by" key to
-	    <command>named</command> would store the stand-by key, and
+	    their zone in advance.  <command>named</command> would store
-	    when the original key was revoked, <command>named</command>
+	    the stand-by key, and when the original key was revoked,
-	    would be able to transition smoothly to the new key.  It would
+	    <command>named</command> would be able to transition smoothly
-	    also recognize that the old key had been revoked, and cease
+	    to the new key.  It would also recognize that the old key had
-	    using that key to validate answers, minimizing the damage that
+	    been revoked, and cease using that key to validate answers,
-	    the compromised key could do. This is the process used to
+	    minimizing the damage that the compromised key could do.
-	    keep the ICANN root DNSSEC key up to date.
+	    This is the process used to keep the ICANN root DNSSEC key
+	    up to date.
 	  </para>
 	  <para>
-	    Whereas <command>static-key</command>
+	    Whereas <command>static-key</command> and
-	    keys continue to be trusted until they are removed from
+	    <command>static-ds</command> trust anchors continue
+	    to be trusted until they are removed from
 	    <filename>named.conf</filename>, an
-	    <command>initial-key</command> is only trusted
+	    <command>initial-key</command> or <command>initial-ds</command>
-	    <emphasis>once</emphasis>: for as long as it
+	    is only trusted <emphasis>once</emphasis>: for as long as it
 	    takes to load the managed key database and start the RFC 5011
 	    key maintenance process.
 	  </para>
+	  <para>
+	    It is not possible to mix static with initial trust anchors
+	    for the same domain name. It is also not possible to mix
+	    <command>key</command> with <command>ds</command> trust anchors.
+	  </para>
 	  <para>
 	    The first time <command>named</command> runs with an
-	    <command>initial-key</command> configured in
+	    <command>initial-key</command> or <command>initial-ds</command>
-	    <filename>named.conf</filename>, it fetches the
+	    configured in <filename>named.conf</filename>, it fetches the
 	    DNSKEY RRset directly from the zone apex, and validates it
-	    using the key specified in <command>dnssec-keys</command>.
+	    using the trust anchor specified in <command>dnssec-keys</command>.
-	    If the DNSKEY RRset is validly signed, then it is
+	    If the DNSKEY RRset is validly signed by a key matching
-	    used as the basis for a new managed keys database.
+	    the trust anchor, then it is used as the basis for a new
+	    managed keys database.
 	  </para>
 	  <para>
 	    From that point on, whenever <command>named</command> runs, it
-	    sees the <command>initial-key</command> listed in
+	    sees the <command>initial-key</command> or
+	    <command>initial-ds</command> listed in
 	    <command>dnssec-keys</command>, checks to
 	    make sure RFC 5011 key maintenance has already been initialized
 	    for the specified domain, and if so, it simply moves on.  The
@@ -10966,13 +10983,13 @@ example.com                 CNAME   rpz-tcp-only.
 	  </para>
 	  <para>
 	    The next time <command>named</command> runs after an
-	    <command>initial-key</command> has been
+	    <command>initial-key</command> or <command>initial-ds</command>
-	    <emphasis>removed</emphasis> from the
+	    trust anchor has been <emphasis>removed</emphasis> from the
 	    <command>dnssec-keys</command> statement (or changed to
-	    a <command>static-key</command>), the corresponding
+	    a <command>static-key</command> or <command>static-ds</command>),
-	    zone will be removed from the managed keys database,
+	    the corresponding keys will be removed from the managed keys
-	    and RFC 5011 key maintenance will no longer be used for that
+	    database, and RFC 5011 key maintenance will no longer be used
-	    domain.
+	    for that domain.
 	  </para>
 	  <para>
 	    In the current implementation, the managed keys database

doc/arm/dnssec-keys.grammar.xml

@@ -13,6 +13,7 @@
 
 <programlisting>
 <command>dnssec-keys</command> { <replaceable>string</replaceable> ( static-key |
-    <command>initial-key</command> ) <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
+    <command>initial-key</command> | static-ds | initial-ds )
+    <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
     <replaceable>quoted_string</replaceable>; ... };
 </programlisting>

doc/arm/libdns.xml

@@ -138,7 +138,8 @@ $ <userinput>make</userinput>
       <filename>named.conf</filename>, except that all
       <command>managed-keys</command> entries will be treated as
       if they were configured with the <command>static-key</command>
-      keyword, even if they are configured with <command>initial-key</command>.
+      or <command>static-ds</command> keywords, even if they are configured
+      with <command>initial-key</command> or <command>iniital-ds</command>.
       (See <xref linkend="managed-keys"/> for syntax details.)
     </para>
   </section>

doc/arm/managed-keys.grammar.xml

@@ -13,7 +13,7 @@
 
 <programlisting>
 <command>managed-keys</command> { <replaceable>string</replaceable> ( static-key
-    | initial-key ) <replaceable>integer</replaceable>
+    | initial-key | static-ds |
-    <replaceable>integer</replaceable> <replaceable>integer</replaceable>
+    <command>initial-ds</command> ) <replaceable>integer</replaceable> <replaceable>integer</replaceable>
-    <replaceable>quoted_string</replaceable>; ... }; deprecated
+    <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... }; deprecated
 </programlisting>

doc/arm/managed-keys.xml

@@ -25,8 +25,8 @@
     <para>To configure a validating resolver to use RFC 5011 to
     maintain a trust anchor, configure the trust anchor using a
     <command>dnssec-keys</command> statement and the
-    <command>initial-key</command> keyword. Information about
+    <command>initial-key</command> or <command>initial-ds</command>
-    this can be found in
+    keyword. Information about this can be found in
     <xref linkend="dnssec-keys"/>.</para>
   </section>
   <section><info><title>Authoritative Server</title></info>

doc/misc/options

@@ -22,7 +22,8 @@ dlz <string> {
 }; // may occur multiple times
 
 dnssec-keys { <string> ( static-key |
-    initial-key ) <integer> <integer> <integer>
+    initial-key | static-ds | initial-ds )
+    <integer> <integer> <integer>
     <quoted_string>; ... }; // may occur multiple times
 
 dnssec-policy <string> {
@@ -68,9 +69,9 @@ logging {
 lwres { <unspecified-text> }; // obsolete, may occur multiple times
 
 managed-keys { <string> ( static-key
-    | initial-key ) <integer>
+    | initial-key | static-ds |
-    <integer> <integer>
+    initial-ds ) <integer> <integer>
-    <quoted_string>; ... }; // may occur multiple times, deprecated
+    <integer> <quoted_string>; ... }; // may occur multiple times, deprecated
 
 masters <string> [ port <integer> ] [ dscp
     <integer> ] { ( <masters> | <ipv4_address> [
@@ -209,7 +210,7 @@ options {
         fstrm-set-output-queue-model ( mpsc | spsc ); // not configured
         fstrm-set-output-queue-size <integer>; // not configured
         fstrm-set-reopen-interval <ttlval>; // not configured
-        geoip-directory ( <quoted_string> | none ); // not configured
+        geoip-directory ( <quoted_string> | none );
         geoip-use-ecs <boolean>; // obsolete
         glue-cache <boolean>;
         has-old-clients <boolean>; // ancient
@@ -230,7 +231,7 @@ options {
         listen-on-v6 [ port <integer> ] [ dscp
             <integer> ] {
             <address_match_element>; ... }; // may occur multiple times
-        lmdb-mapsize <sizeval>; // non-operational
+        lmdb-mapsize <sizeval>;
         lock-file ( <quoted_string> | none );
         maintain-ixfr-base <boolean>; // ancient
         managed-keys-directory <quoted_string>;
@@ -538,8 +539,9 @@ view <string> [ <class> ] {
         dnssec-dnskey-kskonly <boolean>;
         dnssec-enable <boolean>; // obsolete
         dnssec-keys { <string> ( static-key |
-            initial-key ) <integer> <integer>
+            initial-key | static-ds | initial-ds
-            <integer> <quoted_string>; ... }; // may occur multiple times
+            ) <integer> <integer> <integer>
+            <quoted_string>; ... }; // may occur multiple times
         dnssec-loadkeys-interval <integer>;
         dnssec-lookaside ( <string>
             trust-anchor <string> |
@@ -581,10 +583,11 @@ view <string> [ <class> ] {
         }; // may occur multiple times
         key-directory <quoted_string>;
         lame-ttl <ttlval>;
-        lmdb-mapsize <sizeval>; // non-operational
+        lmdb-mapsize <sizeval>;
         maintain-ixfr-base <boolean>; // ancient
         managed-keys { <string> (
             static-key | initial-key
+            | static-ds | initial-ds
             ) <integer> <integer>
             <integer>
             <quoted_string>; ... }; // may occur multiple times, deprecated

doc/misc/options.active

@@ -22,7 +22,8 @@ dlz <string> {
 }; // may occur multiple times
 
 dnssec-keys { <string> ( static-key |
-    initial-key ) <integer> <integer> <integer>
+    initial-key | static-ds | initial-ds )
+    <integer> <integer> <integer>
     <quoted_string>; ... }; // may occur multiple times
 
 dyndb <string> <quoted_string> {
@@ -50,9 +51,9 @@ logging {
 };
 
 managed-keys { <string> ( static-key
-    | initial-key ) <integer>
+    | initial-key | static-ds |
-    <integer> <integer>
+    initial-ds ) <integer> <integer>
-    <quoted_string>; ... }; // may occur multiple times, deprecated
+    <integer> <quoted_string>; ... }; // may occur multiple times, deprecated
 
 masters <string> [ port <integer> ] [ dscp
     <integer> ] { ( <masters> | <ipv4_address> [
@@ -175,7 +176,7 @@ options {
         fstrm-set-output-queue-model ( mpsc | spsc ); // not configured
         fstrm-set-output-queue-size <integer>; // not configured
         fstrm-set-reopen-interval <ttlval>; // not configured
-        geoip-directory ( <quoted_string> | none ); // not configured
+        geoip-directory ( <quoted_string> | none );
         glue-cache <boolean>;
         heartbeat-interval <integer>;
         hostname ( <quoted_string> | none );
@@ -192,7 +193,7 @@ options {
         listen-on-v6 [ port <integer> ] [ dscp
             <integer> ] {
             <address_match_element>; ... }; // may occur multiple times
-        lmdb-mapsize <sizeval>; // non-operational
+        lmdb-mapsize <sizeval>;
         lock-file ( <quoted_string> | none );
         managed-keys-directory <quoted_string>;
         masterfile-format ( map | raw | text );
@@ -470,8 +471,9 @@ view <string> [ <class> ] {
         dnssec-accept-expired <boolean>;
         dnssec-dnskey-kskonly <boolean>;
         dnssec-keys { <string> ( static-key |
-            initial-key ) <integer> <integer>
+            initial-key | static-ds | initial-ds
-            <integer> <quoted_string>; ... }; // may occur multiple times
+            ) <integer> <integer> <integer>
+            <quoted_string>; ... }; // may occur multiple times
         dnssec-loadkeys-interval <integer>;
         dnssec-must-be-secure <string> <boolean>; // may occur multiple times
         dnssec-secure-to-insecure <boolean>;
@@ -506,9 +508,10 @@ view <string> [ <class> ] {
         }; // may occur multiple times
         key-directory <quoted_string>;
         lame-ttl <ttlval>;
-        lmdb-mapsize <sizeval>; // non-operational
+        lmdb-mapsize <sizeval>;
         managed-keys { <string> (
             static-key | initial-key
+            | static-ds | initial-ds
             ) <integer> <integer>
             <integer>
             <quoted_string>; ... }; // may occur multiple times, deprecated