From c29ccae2a6f70237f96db2c3beb70a0f30899acd Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Thu, 19 Sep 2019 14:52:49 -0700 Subject: [PATCH] Document initial-ds and static-ds keywords --- bin/named/named.conf.docbook | 17 ++-- doc/arm/Bv9ARM-book.xml | 167 +++++++++++++++++-------------- doc/arm/dnssec-keys.grammar.xml | 3 +- doc/arm/libdns.xml | 3 +- doc/arm/managed-keys.grammar.xml | 6 +- doc/arm/managed-keys.xml | 4 +- doc/misc/options | 21 ++-- doc/misc/options.active | 21 ++-- 8 files changed, 135 insertions(+), 107 deletions(-) diff --git a/bin/named/named.conf.docbook b/bin/named/named.conf.docbook index 61016b6094..8bdfd30075 100644 --- a/bin/named/named.conf.docbook +++ b/bin/named/named.conf.docbook @@ -13,7 +13,7 @@ - 2019-08-07 + 2019-08-12 ISC @@ -113,7 +113,8 @@ dlz string { DNSSEC-KEYS dnssec-keys { string ( static-key | - initial-key ) integer integer integer + initial-key | static-ds | initial-ds ) + integer integer integer quoted_string; ... }; @@ -158,9 +159,9 @@ logging { Deprecated - see DNSSEC-KEYS. managed-keys { string ( static-key - | initial-key ) integer - integer integer - quoted_string; ... }; deprecated + | initial-key | static-ds | + initial-ds ) integer integer + integer quoted_string; ... }; deprecated @@ -607,8 +608,9 @@ view string [ class ] { dnssec-accept-expired boolean; dnssec-dnskey-kskonly boolean; dnssec-keys { string ( static-key | - initial-key ) integer integer - integer quoted_string; ... }; + initial-key | static-ds | initial-ds + ) integer integer integer + quoted_string; ... }; dnssec-loadkeys-interval integer; dnssec-must-be-secure string boolean; dnssec-secure-to-insecure boolean; @@ -646,6 +648,7 @@ view string [ class ] { lmdb-mapsize sizeval; managed-keys { string ( static-key | initial-key + | static-ds | initial-ds ) integer integer integer quoted_string; ... }; deprecated diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml index a7092fb8c0..cb0de373a3 100644 --- a/doc/arm/Bv9ARM-book.xml +++ b/doc/arm/Bv9ARM-book.xml @@ -2230,13 +2230,14 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;}; The keys specified in dnssec-keys 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 static-key are loaded directly + with the keyword static-key or + static-ds are loaded directly into the table of trust anchors, and can only be changed by altering the configuration. Keys configured with - initial-key are used to initialize - RFC 5011 trust anchor maintenance, and will be kept up to - date automatically after the first time named - runs. + initial-key or initial-ds + are used to initialize RFC 5011 trust anchor maintenance, and + will be kept up to date automatically after the first time + named runs. @@ -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 - 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z - GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb - 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL - kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O - g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S - TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq - FxmAVZP20igTixin/1LcrgX/KMEGd/biuv - F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm - /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o - 1OTQ09A0="; + example.com. static-ds 54135 5 2 "8EF922C97F1D07B23134440F19682E7519ADDAE180E20B1B1EC52E7F58B2831D" /* 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. - defines DNSSEC keys: if used with the - initial-key keyword, - keys are kept up to date using RFC 5011 - trust anchor maintenance, and if used with - static-key, keys are permanent. + defines DNSSEC trust anchors: if used with + the initial-key or + initial-ds keyword, + trust anchors are kept up to date using RFC + 5011 trust anchor maintenance, and if used with + static-key or + static-ds, trust anchors + are permanent. @@ -4628,7 +4622,8 @@ badresp:1,adberr:0,findfail:0,valfail:0] Specifies the directory in which to store the files that track managed DNSSEC keys (i.e., those configured using - the initial-key keyword in a + the initial-key or + initial-ds keywords in a dnssec-keys statement). By default, this is the working directory. The directory must be writable by the effective @@ -10864,12 +10859,12 @@ example.com CNAME rpz-tcp-only. trust anchors. DNSSEC is described in . - A trust anchor is defined when the public key for - a non-authoritative zone is known, but cannot be securely - obtained through DNS, either because it is the DNS root zone - or because its parent zone is unsigned. Once a key has been - configured as a trust anchor, it is treated as if it had - been validated and proven secure. + A trust anchor is defined when the public key or public key + digest for a non-authoritative zone is known, but cannot be + securely obtained through DNS, either because it is the DNS + root zone or because its parent zone is unsigned. Once a key + or digest has been configured as a trust anchor, it is treated + as if it had been validated and proven secure. The resolver attempts DNSSEC validation on all DNS data @@ -10881,19 +10876,9 @@ example.com CNAME rpz-tcp-only. All keys listed in dnssec-keys, 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. - - - The dnssec-keys statement can contain - multiple key entries, each consisting of the key's - domain name, followed by the static-key or - initial-key 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. + name. The parent's DS RRset will not be used. dnssec-keys 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. - dnssec-keys entries can be configured with - two keywords: static-key or - initial-key. Keys configured with - static-key are immutable, - while keys configured with initial-key + The dnssec-keys statement can contain + multiple trust anchor entries, each consisting of a + domain name, followed by an "anchor type" keyword indicating + the trust anchor's format, followed by the key or digest data. + + + If the anchor type is static-key or + initial-key, 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. + + + If the anchor type is static-ds or + initial-ds, 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. + + + Trust anchors configured with the + static-key or static-ds + anchor types are immutable, while keys configured with + initial-key or initial-ds can be kept up to date automatically, without intervention from the resolver operator. (static-key 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 static-key would be - unable to validate this zone any longer; it would - reply with a SERVFAIL response code. This would - continue until the resolver operator had updated the - dnssec-keys statement with the new key. + configured using static-key or + static-ds would be unable to validate + this zone any longer; it would reply with a SERVFAIL response + code. This would continue until the resolver operator had + updated the dnssec-keys statement with + the new key. If, however, the trust anchor had been configured with - initial-key instead, then the - zone owner could add a "stand-by" key to their zone in advance. - named would store the stand-by key, and - when the original key was revoked, named - would be able to transition smoothly to the new key. It would - also recognize that the old key had been revoked, and cease - using that key to validate answers, minimizing the damage that - the compromised key could do. This is the process used to - keep the ICANN root DNSSEC key up to date. + initial-key or initial-ds + instead, then the zone owner could add a "stand-by" key to + their zone in advance. named would store + the stand-by key, and when the original key was revoked, + named would be able to transition smoothly + to the new key. It would also recognize that the old key had + been revoked, and cease using that key to validate answers, + minimizing the damage that the compromised key could do. + This is the process used to keep the ICANN root DNSSEC key + up to date. - Whereas static-key - keys continue to be trusted until they are removed from + Whereas static-key and + static-ds trust anchors continue + to be trusted until they are removed from named.conf, an - initial-key is only trusted - once: for as long as it + initial-key or initial-ds + is only trusted once: for as long as it takes to load the managed key database and start the RFC 5011 key maintenance process. + + It is not possible to mix static with initial trust anchors + for the same domain name. It is also not possible to mix + key with ds trust anchors. + The first time named runs with an - initial-key configured in - named.conf, it fetches the + initial-key or initial-ds + configured in named.conf, it fetches the DNSKEY RRset directly from the zone apex, and validates it - using the key specified in dnssec-keys. - If the DNSKEY RRset is validly signed, then it is - used as the basis for a new managed keys database. + using the trust anchor specified in dnssec-keys. + If the DNSKEY RRset is validly signed by a key matching + the trust anchor, then it is used as the basis for a new + managed keys database. From that point on, whenever named runs, it - sees the initial-key listed in + sees the initial-key or + initial-ds listed in dnssec-keys, 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. The next time named runs after an - initial-key has been - removed from the + initial-key or initial-ds + trust anchor has been removed from the dnssec-keys statement (or changed to - a static-key), the corresponding - zone will be removed from the managed keys database, - and RFC 5011 key maintenance will no longer be used for that - domain. + a static-key or static-ds), + the corresponding keys will be removed from the managed keys + database, and RFC 5011 key maintenance will no longer be used + for that domain. In the current implementation, the managed keys database diff --git a/doc/arm/dnssec-keys.grammar.xml b/doc/arm/dnssec-keys.grammar.xml index 4f5d238a99..6c602292b5 100644 --- a/doc/arm/dnssec-keys.grammar.xml +++ b/doc/arm/dnssec-keys.grammar.xml @@ -13,6 +13,7 @@ dnssec-keys { string ( static-key | - initial-key ) integer integer integer + initial-key | static-ds | initial-ds ) + integer integer integer quoted_string; ... }; diff --git a/doc/arm/libdns.xml b/doc/arm/libdns.xml index 19230552fb..f4758429db 100644 --- a/doc/arm/libdns.xml +++ b/doc/arm/libdns.xml @@ -138,7 +138,8 @@ $ make named.conf, except that all managed-keys entries will be treated as if they were configured with the static-key - keyword, even if they are configured with initial-key. + or static-ds keywords, even if they are configured + with initial-key or iniital-ds. (See for syntax details.) diff --git a/doc/arm/managed-keys.grammar.xml b/doc/arm/managed-keys.grammar.xml index beb0f96725..2e1e7219f5 100644 --- a/doc/arm/managed-keys.grammar.xml +++ b/doc/arm/managed-keys.grammar.xml @@ -13,7 +13,7 @@ managed-keys { string ( static-key - | initial-key ) integer - integer integer - quoted_string; ... }; deprecated + | initial-key | static-ds | + initial-ds ) integer integer + integer quoted_string; ... }; deprecated diff --git a/doc/arm/managed-keys.xml b/doc/arm/managed-keys.xml index e4ba67ab6c..da6c170a35 100644 --- a/doc/arm/managed-keys.xml +++ b/doc/arm/managed-keys.xml @@ -25,8 +25,8 @@ To configure a validating resolver to use RFC 5011 to maintain a trust anchor, configure the trust anchor using a dnssec-keys statement and the - initial-key keyword. Information about - this can be found in + initial-key or initial-ds + keyword. Information about this can be found in .
Authoritative Server diff --git a/doc/misc/options b/doc/misc/options index 61dad9bbba..38881ac0c9 100644 --- a/doc/misc/options +++ b/doc/misc/options @@ -22,7 +22,8 @@ dlz { }; // may occur multiple times dnssec-keys { ( static-key | - initial-key ) + initial-key | static-ds | initial-ds ) + ; ... }; // may occur multiple times dnssec-policy { @@ -68,9 +69,9 @@ logging { lwres { }; // obsolete, may occur multiple times managed-keys { ( static-key - | initial-key ) - - ; ... }; // may occur multiple times, deprecated + | initial-key | static-ds | + initial-ds ) + ; ... }; // may occur multiple times, deprecated masters [ port ] [ dscp ] { ( | [ @@ -209,7 +210,7 @@ options { fstrm-set-output-queue-model ( mpsc | spsc ); // not configured fstrm-set-output-queue-size ; // not configured fstrm-set-reopen-interval ; // not configured - geoip-directory ( | none ); // not configured + geoip-directory ( | none ); geoip-use-ecs ; // obsolete glue-cache ; has-old-clients ; // ancient @@ -230,7 +231,7 @@ options { listen-on-v6 [ port ] [ dscp ] { ; ... }; // may occur multiple times - lmdb-mapsize ; // non-operational + lmdb-mapsize ; lock-file ( | none ); maintain-ixfr-base ; // ancient managed-keys-directory ; @@ -538,8 +539,9 @@ view [ ] { dnssec-dnskey-kskonly ; dnssec-enable ; // obsolete dnssec-keys { ( static-key | - initial-key ) - ; ... }; // may occur multiple times + initial-key | static-ds | initial-ds + ) + ; ... }; // may occur multiple times dnssec-loadkeys-interval ; dnssec-lookaside ( trust-anchor | @@ -581,10 +583,11 @@ view [ ] { }; // may occur multiple times key-directory ; lame-ttl ; - lmdb-mapsize ; // non-operational + lmdb-mapsize ; maintain-ixfr-base ; // ancient managed-keys { ( static-key | initial-key + | static-ds | initial-ds ) ; ... }; // may occur multiple times, deprecated diff --git a/doc/misc/options.active b/doc/misc/options.active index 21e47dc152..e4123c69c5 100644 --- a/doc/misc/options.active +++ b/doc/misc/options.active @@ -22,7 +22,8 @@ dlz { }; // may occur multiple times dnssec-keys { ( static-key | - initial-key ) + initial-key | static-ds | initial-ds ) + ; ... }; // may occur multiple times dyndb { @@ -50,9 +51,9 @@ logging { }; managed-keys { ( static-key - | initial-key ) - - ; ... }; // may occur multiple times, deprecated + | initial-key | static-ds | + initial-ds ) + ; ... }; // may occur multiple times, deprecated masters [ port ] [ dscp ] { ( | [ @@ -175,7 +176,7 @@ options { fstrm-set-output-queue-model ( mpsc | spsc ); // not configured fstrm-set-output-queue-size ; // not configured fstrm-set-reopen-interval ; // not configured - geoip-directory ( | none ); // not configured + geoip-directory ( | none ); glue-cache ; heartbeat-interval ; hostname ( | none ); @@ -192,7 +193,7 @@ options { listen-on-v6 [ port ] [ dscp ] { ; ... }; // may occur multiple times - lmdb-mapsize ; // non-operational + lmdb-mapsize ; lock-file ( | none ); managed-keys-directory ; masterfile-format ( map | raw | text ); @@ -470,8 +471,9 @@ view [ ] { dnssec-accept-expired ; dnssec-dnskey-kskonly ; dnssec-keys { ( static-key | - initial-key ) - ; ... }; // may occur multiple times + initial-key | static-ds | initial-ds + ) + ; ... }; // may occur multiple times dnssec-loadkeys-interval ; dnssec-must-be-secure ; // may occur multiple times dnssec-secure-to-insecure ; @@ -506,9 +508,10 @@ view [ ] { }; // may occur multiple times key-directory ; lame-ttl ; - lmdb-mapsize ; // non-operational + lmdb-mapsize ; managed-keys { ( static-key | initial-key + | static-ds | initial-ds ) ; ... }; // may occur multiple times, deprecated