From: Evan Hunt Date: Wed, 3 Oct 2018 20:08:30 +0000 (-0700) Subject: update documentation X-Git-Tag: v9.15.1~9^2~1 X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=3853b3cf6d83cb144377963ee40ff51ffe5df667;p=thirdparty%2Fbind9.git update documentation - change references to trusted-keys to dnssec-keys with static-key - rebuild doc/misc/options and other generated grammar doc - add a "see MANAGED-KEYS" note when building named.conf.docbook --- diff --git a/bin/delv/delv.docbook b/bin/delv/delv.docbook index f8c4f79737c..d30bedd55ff 100644 --- a/bin/delv/delv.docbook +++ b/bin/delv/delv.docbook @@ -218,14 +218,17 @@ Note: When reading the trust anchor file, - delv treats - statements and statements - identically. That is, for a managed key, it is the - initial key that is trusted; RFC 5011 - key management is not supported. delv - will not consult the managed-keys database maintained by - named. This means that if either of the - keys in /etc/bind.keys is revoked + delv treats + and + entries identically. That is, even if a key is configured + with initial-key, indicating that it is + meant to be used only as an initializing key for RFC 5011 + key maintenance, it is still treated by delv + as if it had been configured as a static-key. + delv does not consult the managed keys + database maintained by named. This means + that if either of the keys in + /etc/bind.keys is revoked and rolled over, it will be necessary to update /etc/bind.keys to use DNSSEC validation in delv. diff --git a/bin/named/named.conf.docbook b/bin/named/named.conf.docbook index 0f7b74e7bc8..f86e418b744 100644 --- a/bin/named/named.conf.docbook +++ b/bin/named/named.conf.docbook @@ -13,7 +13,7 @@ - 2018-12-07 + 2019-05-10 ISC @@ -80,14 +80,12 @@ ACL - acl string { address_match_element; ... }; CONTROLS - controls { inet ( ipv4_address | ipv6_address | @@ -104,7 +102,6 @@ controls { DLZ - dlz string { database string; @@ -113,8 +110,15 @@ dlz string { - DYNDB + DNSSEC-KEYS + +dnssec-keys { string ( static-key | + initial-key ) integer integer integer + quoted_string; ... }; + + + DYNDB dyndb string quoted_string { unspecified-text }; @@ -122,7 +126,6 @@ dyndb string quoted_string KEY - key string { algorithm string; @@ -132,7 +135,6 @@ key string { LOGGING - logging { category string { string; ... }; @@ -154,15 +156,15 @@ logging { MANAGED-KEYS - + See DNSSEC-KEYS. -managed-keys { string string integer - integer integer quoted_string; ... }; +managed-keys { string ( static-key | + initial-key ) integer integer integer + quoted_string; ... }; MASTERS - masters string [ port integer ] [ dscp integer ] { ( masters | ipv4_address [ @@ -172,7 +174,6 @@ masters string [ port integer OPTIONS - options { allow-new-zones boolean; @@ -251,7 +252,6 @@ options { dnsrps-options { unspecified-text }; dnssec-accept-expired boolean; dnssec-dnskey-kskonly boolean; - dnssec-enable boolean; dnssec-loadkeys-interval integer; dnssec-lookaside ( string trust-anchor string | auto | no ); @@ -403,11 +403,12 @@ options { resolver-retry-interval integer; response-padding { address_match_element; ... } block-size integer; - response-policy { zone string [ log boolean ] [ max-policy-ttl - ttlval ] [ min-update-interval ttlval ] [ policy ( cname | - disabled | drop | given | no-op | nodata | nxdomain | passthru - | tcp-only quoted_string ) ] [ recursive-only boolean ] [ - nsip-enable boolean ] [ nsdname-enable boolean ]; ... } [ + response-policy { zone string [ add-soa boolean ] [ log + boolean ] [ max-policy-ttl ttlval ] [ min-update-interval + ttlval ] [ policy ( cname | disabled | drop | given | no-op | + nodata | nxdomain | passthru | tcp-only quoted_string ) ] [ + recursive-only boolean ] [ nsip-enable boolean ] [ + nsdname-enable boolean ]; ... } [ add-soa boolean ] [ break-dnssec boolean ] [ max-policy-ttl ttlval ] [ min-update-interval ttlval ] [ min-ns-dots integer ] [ nsip-wait-recurse boolean ] [ qname-wait-recurse boolean ] @@ -474,7 +475,6 @@ options { PLUGIN - plugin ( query ) string [ { unspecified-text } ]; @@ -482,7 +482,6 @@ plugin ( query ) string [ { unspecified- SERVER - server netprefix { bogus boolean; @@ -520,7 +519,6 @@ server netprefix { STATISTICS-CHANNELS - statistics-channels { inet ( ipv4_address | ipv6_address | @@ -532,15 +530,15 @@ statistics-channels { TRUSTED-KEYS - + Deprecated - see DNSSEC-KEYS. -trusted-keys { string integer integer - integer quoted_string; ... }; +trusted-keys { string integer + integer integer + quoted_string; ... };, deprecated VIEW - view string [ class ] { allow-new-zones boolean; @@ -612,7 +610,9 @@ view string [ class ] { dnsrps-options { unspecified-text }; dnssec-accept-expired boolean; dnssec-dnskey-kskonly boolean; - dnssec-enable boolean; + dnssec-keys { string ( static-key | + initial-key ) integer integer + integer quoted_string; ... }; dnssec-loadkeys-interval integer; dnssec-lookaside ( string trust-anchor string | auto | no ); @@ -650,9 +650,9 @@ view string [ class ] { key-directory quoted_string; lame-ttl ttlval; lmdb-mapsize sizeval; - managed-keys { string string - integer integer integer - quoted_string; ... }; + managed-keys { string ( static-key | + initial-key ) integer integer + integer quoted_string; ... }; masterfile-format ( map | raw | text ); masterfile-style ( full | relative ); match-clients { address_match_element; ... }; @@ -735,11 +735,12 @@ view string [ class ] { resolver-retry-interval integer; response-padding { address_match_element; ... } block-size integer; - response-policy { zone string [ log boolean ] [ max-policy-ttl - ttlval ] [ min-update-interval ttlval ] [ policy ( cname | - disabled | drop | given | no-op | nodata | nxdomain | passthru - | tcp-only quoted_string ) ] [ recursive-only boolean ] [ - nsip-enable boolean ] [ nsdname-enable boolean ]; ... } [ + response-policy { zone string [ add-soa boolean ] [ log + boolean ] [ max-policy-ttl ttlval ] [ min-update-interval + ttlval ] [ policy ( cname | disabled | drop | given | no-op | + nodata | nxdomain | passthru | tcp-only quoted_string ) ] [ + recursive-only boolean ] [ nsip-enable boolean ] [ + nsdname-enable boolean ]; ... } [ add-soa boolean ] [ break-dnssec boolean ] [ max-policy-ttl ttlval ] [ min-update-interval ttlval ] [ min-ns-dots integer ] [ nsip-wait-recurse boolean ] [ qname-wait-recurse boolean ] @@ -801,9 +802,10 @@ view string [ class ] { transfer-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ] [ dscp integer ]; trust-anchor-telemetry boolean; // experimental - trusted-keys { string integer - integer integer quoted_string; - ... }; + trusted-keys { string + integer integer + integer + quoted_string; ... };, deprecated try-tcp-refresh boolean; update-check-ksk boolean; use-alt-transfer-source boolean; @@ -915,7 +917,6 @@ view string [ class ] { ZONE - zone string [ class ] { allow-notify { address_match_element; ... }; diff --git a/bin/rndc/rndc.docbook b/bin/rndc/rndc.docbook index 7fda5916fb9..055683536e6 100644 --- a/bin/rndc/rndc.docbook +++ b/bin/rndc/rndc.docbook @@ -458,7 +458,7 @@ managed-keys (status | refresh | sync | destroy) class view - Inspect and control the "managed-keys" database which + Inspect and control the "managed keys" database which handles RFC 5011 DNSSEC trust anchor maintenance. If a view is specified, these commands are applied to that view; otherwise they are applied to all views. @@ -467,14 +467,14 @@ When run with the status keyword, prints - the current status of the managed-keys database. + the current status of the managed keys database. When run with the refresh keyword, forces an immediate refresh query to be sent for all - the managed keys, updating the managed-keys database + the managed keys, updating the managed keys database if any new keys are found, without waiting the normal refresh interval. @@ -482,7 +482,7 @@ When run with the sync keyword, forces an - immediate dump of the managed-keys database to disk + immediate dump of the managed keys database to disk (in the file managed-keys.bind or (viewname.mkeys). This synchronizes the database with its journal file, so @@ -493,7 +493,7 @@ When run with the destroy keyword, the - managed-keys database is shut down and deleted, and all key + managed keys database is shut down and deleted, and all key maintenance is terminated. This command should be used only with extreme caution. @@ -772,9 +772,10 @@ Dump the security roots (i.e., trust anchors - configured via trusted-keys, - managed-keys, or - dnssec-validation auto) and negative trust + configured via dnssec-keys statements, + or the synonymous managed-keys or + the deprecated trusted-keys statements, or + via dnssec-validation auto) and negative trust anchors for the specified views. If no view is specified, all views are dumped. Security roots will indicate whether they are configured as trusted keys, managed keys, or diff --git a/bin/tests/named.conf b/bin/tests/named.conf index edb9af2fb23..928dd9e96a2 100644 --- a/bin/tests/named.conf +++ b/bin/tests/named.conf @@ -259,8 +259,8 @@ key "non-viewkey" { secret "YWFh" ; algorithm "zzz" ; }; view "test-view" in { key "viewkey" { algorithm "xxx" ; secret "eXl5" ; }; also-notify { 10.2.2.3; }; - trusted-keys { - foo.com. 4 3 2 "abdefghijklmnopqrstuvwxyz"; + managed-keys { + foo.com. static 4 3 2 "abdefghijklmnopqrstuvwxyz"; }; sig-validity-interval 45; max-cache-size 100000; @@ -342,8 +342,8 @@ zone "." { // pubkey 257 255 1 "AQP2fHpZ4VMpKo/jc9Fod821uyfY5p8j5h/Am0V/KpBTMZjdXmp9QJe6yFRoIIzkaNCgTIftASdpXGgCwFB2j2KXP/rick6gvEer5VcDEkLR5Q=="; }; -trusted-keys { - "." 257 255 1 "AQP2fHpZ4VMpKo/jc9Fod821uyfY5p8j5h/Am0V/KpBTMZjdXmp9QJe6yFRoIIzkaNCgTIftASdpXGgCwFB2j2KXP/rick6gvEer5VcDEkLR5Q=="; +managed-keys { + "." static 257 255 1 "AQP2fHpZ4VMpKo/jc9Fod821uyfY5p8j5h/Am0V/KpBTMZjdXmp9QJe6yFRoIIzkaNCgTIftASdpXGgCwFB2j2KXP/rick6gvEer5VcDEkLR5Q=="; }; diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml index eef1263b578..cc9921bcfca 100644 --- a/doc/arm/Bv9ARM-book.xml +++ b/doc/arm/Bv9ARM-book.xml @@ -2087,7 +2087,7 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;}; zone key of another zone above this one in the DNS tree. -
Generating Keys +
Generating Keys The dnssec-keygen program is used to @@ -2212,8 +2212,9 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;}; yes, DNSSEC validation will only occur if at least one trust anchor has been explicitly configured in named.conf - using a trusted-keys or - managed-keys statement. + using a dnssec-keys statement (or the + synonymous managed-keys or the deprecated + trusted-keys statements). When dnssec-validation is set to @@ -2226,23 +2227,20 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;}; - trusted-keys are copies of DNSKEY RRs - for zones that are used to form the first link in the - cryptographic chain of trust. All keys listed in - trusted-keys (and corresponding zones) - are deemed to exist and only the listed keys will be used - to validated the DNSKEY RRset that they are from. + 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 + 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. - managed-keys are trusted keys which are - automatically kept up to date via RFC 5011 trust anchor - maintenance. - - - - trusted-keys and - managed-keys are described in more detail + dnssec-keys is described in more detail later in this document. @@ -2265,7 +2263,7 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;}; -managed-keys { +dnssec-keys { /* Root Key */ "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh @@ -2277,11 +2275,8 @@ managed-keys { 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ dgxbcDTClU0CRBdiieyLMNzXG3"; -}; - -trusted-keys { /* Key for our organization's forward zone */ - example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6 + example.com. static-key 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL @@ -2294,7 +2289,7 @@ trusted-keys { 1OTQ09A0="; /* Key for our reverse zone. */ - 2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc + 2.0.192.IN-ADDRPA.NET. static-key 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc xOdNax071L18QqZnQQQAVVr+i LhGTnNGp3HoWQLUIzKrJVZ3zg gy3WwNT6kZo6c0tszYqbtvchm @@ -3205,11 +3200,17 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. - trusted-keys + dnssec-keys - defines trusted DNSSEC keys. + 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. + Identical to managed-keys, + but has been added for improved clarity. @@ -3219,8 +3220,22 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. - lists DNSSEC keys to be kept up to date - using RFC 5011 trust anchor maintenance. + is identical to dnssec-keys, + and is retained for backward compatibility. + + + + + + trusted-keys + + + + defines permanent trusted DNSSEC keys; + this option is deprecated in favor + of dnssec-keys with + the static-key keyword, + and may be removed in a future release. @@ -4595,10 +4610,12 @@ badresp:1,adberr:0,findfail:0,valfail:0] Specifies the directory in which to store the files that - track managed DNSSEC keys. By default, this is the working - directory. The directory must - be writable by the effective user ID of the - named process. + track managed DNSSEC keys (i.e., those configured using + the initial-key keyword in a + dnssec-keys statement). By default, + this is the working directory. The directory + must be writable by the effective + user ID of the named process. If named is not configured to use views, @@ -5100,10 +5117,10 @@ options { then named will only accept answers if they are secure. If no, then normal DNSSEC validation applies allowing for insecure answers to - be accepted. The specified domain must be under a - trusted-keys or - managed-keys statement, or - dnssec-validation auto must be active. + be accepted. The specified domain must be defined as a + trust anchor, for instance in a dnssec-keys + statement, or dnssec-validation auto must + be active. @@ -6195,8 +6212,8 @@ options { Causes named to send specially-formed queries once per day to domains for which trust anchors - have been configured via trusted-keys, - managed-keys, or + have been configured via, e.g., + dnssec-keys or dnssec-validation auto. @@ -6411,10 +6428,11 @@ options { If set to yes, DNSSEC validation is enabled, but a trust anchor must be manually configured - using a trusted-keys - or managed-keys statement; if there - is no configured trust anchor, validation will not take - place. + using a dnssec-keys statement (or + the synonymous managed-keys, or the + deprecated trusted-keys statements). + If there is no configured trust anchor, validation will + not take place. If set to no, DNSSEC validation @@ -10709,246 +10727,236 @@ example.com CNAME rpz-tcp-only.
-
<command>statistics-channels</command> Statement Grammar - -
+
<command>statistics-channels</command> Statement Grammar + +
-
<command>statistics-channels</command> Statement Definition and - Usage +
<command>statistics-channels</command> Statement Definition and + Usage - - The statistics-channels statement - declares communication channels to be used by system - administrators to get access to statistics information of - the name server. - + + The statistics-channels statement + declares communication channels to be used by system + administrators to get access to statistics information of + the name server. + - - This statement intends to be flexible to support multiple - communication protocols in the future, but currently only - HTTP access is supported. - It requires that BIND 9 be compiled with libxml2 and/or - json-c (also known as libjson0); the - statistics-channels statement is - still accepted even if it is built without the library, - but any HTTP access will fail with an error. - + + This statement intends to be flexible to support multiple + communication protocols in the future, but currently only + HTTP access is supported. + It requires that BIND 9 be compiled with libxml2 and/or + json-c (also known as libjson0); the + statistics-channels statement is + still accepted even if it is built without the library, + but any HTTP access will fail with an error. + - - An inet control channel is a TCP socket - listening at the specified ip_port on the - specified ip_addr, which can be an IPv4 or IPv6 - address. An ip_addr of * - (asterisk) is - interpreted as the IPv4 wildcard address; connections will be - accepted on any of the system's IPv4 addresses. - To listen on the IPv6 wildcard address, - use an ip_addr of ::. - + + An inet control channel is a TCP socket + listening at the specified ip_port on the + specified ip_addr, which can be an IPv4 or IPv6 + address. An ip_addr of * + (asterisk) is + interpreted as the IPv4 wildcard address; connections will be + accepted on any of the system's IPv4 addresses. + To listen on the IPv6 wildcard address, + use an ip_addr of ::. + - - If no port is specified, port 80 is used for HTTP channels. - The asterisk "*" cannot be used for - ip_port. - + + If no port is specified, port 80 is used for HTTP channels. + The asterisk "*" cannot be used for + ip_port. + - - The attempt of opening a statistics channel is - restricted by the optional allow clause. - Connections to the statistics channel are permitted based on the - address_match_list. - If no allow clause is present, - named accepts connection - attempts from any address; since the statistics may - contain sensitive internal information, it is highly - recommended to restrict the source of connection requests - appropriately. - + + The attempt of opening a statistics channel is + restricted by the optional allow clause. + Connections to the statistics channel are permitted based on the + address_match_list. + If no allow clause is present, + named accepts connection + attempts from any address; since the statistics may + contain sensitive internal information, it is highly + recommended to restrict the source of connection requests + appropriately. + - - If no statistics-channels statement is present, - named will not open any communication channels. - + + If no statistics-channels statement is present, + named will not open any communication channels. + - - The statistics are available in various formats and views - depending on the URI used to access them. For example, if - the statistics channel is configured to listen on 127.0.0.1 - port 8888, then the statistics are accessible in XML format at - http://127.0.0.1:8888/ or - http://127.0.0.1:8888/xml. A CSS file is - included which can format the XML statistics into tables - when viewed with a stylesheet-capable browser, and into - charts and graphs using the Google Charts API when using a - javascript-capable browser. - + + The statistics are available in various formats and views + depending on the URI used to access them. For example, if + the statistics channel is configured to listen on 127.0.0.1 + port 8888, then the statistics are accessible in XML format at + http://127.0.0.1:8888/ or + http://127.0.0.1:8888/xml. A CSS file is + included which can format the XML statistics into tables + when viewed with a stylesheet-capable browser, and into + charts and graphs using the Google Charts API when using a + javascript-capable browser. + - - Broken-out subsets of the statistics can be viewed at - http://127.0.0.1:8888/xml/v3/status - (server uptime and last reconfiguration time), - http://127.0.0.1:8888/xml/v3/server - (server and resolver statistics), - http://127.0.0.1:8888/xml/v3/zones - (zone statistics), - http://127.0.0.1:8888/xml/v3/net - (network status and socket statistics), - http://127.0.0.1:8888/xml/v3/mem - (memory manager statistics), - http://127.0.0.1:8888/xml/v3/tasks - (task manager statistics), and - http://127.0.0.1:8888/xml/v3/traffic - (traffic sizes). - + + Broken-out subsets of the statistics can be viewed at + http://127.0.0.1:8888/xml/v3/status + (server uptime and last reconfiguration time), + http://127.0.0.1:8888/xml/v3/server + (server and resolver statistics), + http://127.0.0.1:8888/xml/v3/zones + (zone statistics), + http://127.0.0.1:8888/xml/v3/net + (network status and socket statistics), + http://127.0.0.1:8888/xml/v3/mem + (memory manager statistics), + http://127.0.0.1:8888/xml/v3/tasks + (task manager statistics), and + http://127.0.0.1:8888/xml/v3/traffic + (traffic sizes). + - - The full set of statistics can also be read in JSON format at - http://127.0.0.1:8888/json, - with the broken-out subsets at - http://127.0.0.1:8888/json/v1/status - (server uptime and last reconfiguration time), - http://127.0.0.1:8888/json/v1/server - (server and resolver statistics), - http://127.0.0.1:8888/json/v1/zones - (zone statistics), - http://127.0.0.1:8888/json/v1/net - (network status and socket statistics), - http://127.0.0.1:8888/json/v1/mem - (memory manager statistics), - http://127.0.0.1:8888/json/v1/tasks - (task manager statistics), and - http://127.0.0.1:8888/json/v1/traffic - (traffic sizes). - -
+ + The full set of statistics can also be read in JSON format at + http://127.0.0.1:8888/json, + with the broken-out subsets at + http://127.0.0.1:8888/json/v1/status + (server uptime and last reconfiguration time), + http://127.0.0.1:8888/json/v1/server + (server and resolver statistics), + http://127.0.0.1:8888/json/v1/zones + (zone statistics), + http://127.0.0.1:8888/json/v1/net + (network status and socket statistics), + http://127.0.0.1:8888/json/v1/mem + (memory manager statistics), + http://127.0.0.1:8888/json/v1/tasks + (task manager statistics), and + http://127.0.0.1:8888/json/v1/traffic + (traffic sizes). + +
-
<command>trusted-keys</command> Statement Grammar - +
<command>dnssec-keys</command> Statement Grammar +
-
<command>trusted-keys</command> Statement Definition + <section xml:id="dnssec-keys"><info><title><command>dnssec-keys</command> Statement Definition and Usage - The trusted-keys statement defines - DNSSEC security roots. DNSSEC is described in . A security root 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 trusted - key, it is treated as if it had been validated and - proven secure. The resolver attempts DNSSEC validation - on all DNS data in subdomains of a security root. + The dnssec-keys statement defines DNSSEC + trust anchors. DNSSEC is described in . - All keys (and corresponding zones) listed in - trusted-keys are deemed to exist regardless - of what parent zones say. Similarly for all keys listed in - trusted-keys only those keys are - used to validate the DNSKEY RRset. The parent's DS RRset - will not be used. + 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. - The trusted-keys statement can contain + The resolver attempts DNSSEC validation on all DNS data + in subdomains of configured trust anchors. (Validation below + specified names can be temporarily disabled by using + rndc nta, or permanently disabled with + the validate-except option). + + + 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 + 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, flags, protocol, algorithm, and the Base64 - representation of the key data. - Spaces, tabs, newlines and carriage returns are ignored + 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. - trusted-keys may be set at the top level + dnssec-keys may be set at the top level of named.conf or within a view. If it is - set in both places, they are additive: keys defined at the top - level are inherited by all views, but keys defined in a view - are only used within that view. + set in both places, the configurations are additive: keys + defined at the top level are inherited by all views, but keys + defined in a view are only used within that view. - Validation below specified names can be temporarily disabled - by using rndc nta. - -
- -
<command>managed-keys</command> Statement Grammar - -
-
<command>managed-keys</command> Statement Definition - and Usage - - - The managed-keys statement, like - trusted-keys, defines DNSSEC - security roots. The difference is that - managed-keys can be kept up to date - automatically, without intervention from the resolver - operator. + 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 + can be kept up to date automatically, without intervention + from the resolver operator. (static-key + keys are identical to keys configured using the deprecated + trusted-keys statement.) 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 old key in a - trusted-keys statement would be + 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 - trusted-keys statement with the new key. + dnssec-keys statement with the new key. - If, however, the zone were listed in a - managed-keys statement instead, then the - zone owner could add a "stand-by" key to the zone in advance. + 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. - - - A managed-keys statement contains a list of - the keys to be managed, along with information about how the - keys are to be initialized for the first time. The only - initialization method currently supported is - initial-key. - This means the managed-keys statement must - contain a copy of the initializing key. (Future releases may - allow keys to be initialized by other methods, eliminating this - requirement.) - - - Consequently, a managed-keys statement - appears similar to a trusted-keys, differing - in the presence of the second field, containing the keyword - initial-key. The difference is, whereas the - keys listed in a trusted-keys continue to be - trusted until they are removed from - named.conf, an initializing key listed - in a managed-keys statement is only trusted - once: for as long as it takes to load the - managed key database and start the RFC 5011 key maintenance - process. - - - The first time named runs with a managed key - configured in named.conf, it fetches the + 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 + named.conf, an + initial-key is only trusted + once: for as long as it + takes to load the managed key database and start the RFC 5011 + key maintenance process. + + + The first time named runs with an + initial-key configured in + named.conf, it fetches the DNSKEY RRset directly from the zone apex, and validates it - using the key specified in the managed-keys - statement. If the DNSKEY RRset is validly signed, then it is + 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. From that point on, whenever named runs, it - sees the managed-keys statement, checks to + sees the initial-key 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 - key specified in the managed-keys - statement is not used to validate answers; it has been - superseded by the key or keys stored in the managed keys database. + key specified in the dnssec-keys + statement is not used to validate answers; it is + superseded by the key or keys stored in the managed keys + database. - The next time named runs after a name - has been removed from the - managed-keys statement, the corresponding + The next time named runs after an + initial-key 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. @@ -10983,8 +10991,8 @@ example.com CNAME rpz-tcp-only. If the dnssec-validation option is set to auto, named - will automatically initialize a managed key for the - root zone. The key that is used to initialize the key + will automatically initialize an initial-key + for the root zone. The key that is used to initialize the key maintenance process is stored in bind.keys; the location of this file can be overridden with the bindkeys-file option. As a fallback @@ -10994,6 +11002,32 @@ example.com CNAME rpz-tcp-only.
+
<command>managed-keys</command> Statement Grammar + +
+
<command>managed-keys</command> Statement Definition + and Usage + + + The managed-keys statement is + identical to the dnssec-keys, and is + retained for backward compatibility. + +
+ +
<command>trusted-keys</command> Statement Grammar + +
+
<command>trusted-keys</command> Statement Definition + and Usage + + + The trusted-keys statement has been + deprecated in favor of + with the static keyword. + +
+
<command>view</command> Statement Grammar view view_name [ class ] { diff --git a/doc/arm/dnssec-keys.grammar.xml b/doc/arm/dnssec-keys.grammar.xml new file mode 100644 index 00000000000..4f5d238a99a --- /dev/null +++ b/doc/arm/dnssec-keys.grammar.xml @@ -0,0 +1,18 @@ + + + + + +dnssec-keys { string ( static-key | + initial-key ) integer integer integer + quoted_string; ... }; + diff --git a/doc/arm/libdns.xml b/doc/arm/libdns.xml index 4562f6a7c9e..19230552fb9 100644 --- a/doc/arm/libdns.xml +++ b/doc/arm/libdns.xml @@ -132,10 +132,14 @@ $ make parameters. By default the path to this configuration file is /etc/dns.conf. This module is very experimental and the configuration syntax or library interfaces may change in - future versions. Currently, only the trusted-keys - statement is supported, whose syntax is the same as the same - statement in named.conf. (See - for details.) + future versions. Currently, only static key configuration is supported. + managed-keys and trusted-keys + statements are parsed exactly as they are in + 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. + (See for syntax details.)
diff --git a/doc/arm/managed-keys.grammar.xml b/doc/arm/managed-keys.grammar.xml index d79f27fe063..d1aaee3c37c 100644 --- a/doc/arm/managed-keys.grammar.xml +++ b/doc/arm/managed-keys.grammar.xml @@ -12,6 +12,7 @@ -managed-keys { string string integer - integer integer quoted_string; ... }; +managed-keys { string ( static-key | + initial-key ) integer integer integer + quoted_string; ... }; diff --git a/doc/arm/managed-keys.xml b/doc/arm/managed-keys.xml index ba45a6c1c00..e4ba67ab6c7 100644 --- a/doc/arm/managed-keys.xml +++ b/doc/arm/managed-keys.xml @@ -24,11 +24,10 @@ To configure a validating resolver to use RFC 5011 to maintain a trust anchor, configure the trust anchor using a - managed-keys statement. Information about + dnssec-keys statement and the + initial-key keyword. Information about this can be found in - . - + .
Authoritative Server diff --git a/doc/arm/options.grammar.xml b/doc/arm/options.grammar.xml index 7439ee3e4fd..850bde3d5c0 100644 --- a/doc/arm/options.grammar.xml +++ b/doc/arm/options.grammar.xml @@ -89,7 +89,6 @@ dnsrps-options { unspecified-text }; dnssec-accept-expired boolean; dnssec-dnskey-kskonly boolean; - dnssec-enable boolean; dnssec-loadkeys-interval integer; dnssec-lookaside ( string trust-anchor string | auto | no ); @@ -241,11 +240,12 @@ resolver-retry-interval integer; response-padding { address_match_element; ... } block-size integer; - response-policy { zone string [ log boolean ] [ max-policy-ttl - ttlval ] [ min-update-interval ttlval ] [ policy ( cname | - disabled | drop | given | no-op | nodata | nxdomain | passthru - | tcp-only quoted_string ) ] [ recursive-only boolean ] [ - nsip-enable boolean ] [ nsdname-enable boolean ]; ... } [ + response-policy { zone string [ add-soa boolean ] [ log + boolean ] [ max-policy-ttl ttlval ] [ min-update-interval + ttlval ] [ policy ( cname | disabled | drop | given | no-op | + nodata | nxdomain | passthru | tcp-only quoted_string ) ] [ + recursive-only boolean ] [ nsip-enable boolean ] [ + nsdname-enable boolean ]; ... } [ add-soa boolean ] [ break-dnssec boolean ] [ max-policy-ttl ttlval ] [ min-update-interval ttlval ] [ min-ns-dots integer ] [ nsip-wait-recurse boolean ] [ qname-wait-recurse boolean ] diff --git a/doc/arm/trusted-keys.grammar.xml b/doc/arm/trusted-keys.grammar.xml index b0bd3d79f8c..2a0b6e9454f 100644 --- a/doc/arm/trusted-keys.grammar.xml +++ b/doc/arm/trusted-keys.grammar.xml @@ -12,6 +12,7 @@ -trusted-keys { string integer integer - integer quoted_string; ... }; +trusted-keys { string integer + integer integer + quoted_string; ... };, deprecated diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 21084d55917..0483f587b8a 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -71,5 +71,6 @@ docbook: options ${PERL} docbook-grammars.pl options options > ${top_srcdir}/doc/arm/options.grammar.xml ${PERL} docbook-grammars.pl options server > ${top_srcdir}/doc/arm/server.grammar.xml ${PERL} docbook-grammars.pl options statistics-channels > ${top_srcdir}/doc/arm/statistics-channels.grammar.xml - ${PERL} docbook-grammars.pl options trusted-keys > ${top_srcdir}/doc/arm/trusted-keys.grammar.xml + ${PERL} docbook-grammars.pl options dnssec-keys > ${top_srcdir}/doc/arm/dnssec-keys.grammar.xml ${PERL} docbook-grammars.pl options managed-keys > ${top_srcdir}/doc/arm/managed-keys.grammar.xml + ${PERL} docbook-grammars.pl options trusted-keys > ${top_srcdir}/doc/arm/trusted-keys.grammar.xml diff --git a/doc/misc/docbook-options.pl b/doc/misc/docbook-options.pl index 25a6d9927f0..fdb9c39c144 100644 --- a/doc/misc/docbook-options.pl +++ b/doc/misc/docbook-options.pl @@ -128,8 +128,9 @@ while () { s{ // not configured}{}; s{ // non-operational}{}; - s{ // may occur multiple times}{}; + s{ (// )*may occur multiple times}{}; s{<([a-z0-9_-]+)>}{$1}g; + s{ // deprecated,*}{// deprecated}; s{[[]}{[}g; s{[]]}{]}g; s{ }{\t}g; @@ -137,10 +138,24 @@ while () { my $HEADING = uc $1; print <$HEADING +END + + if ($1 eq "trusted-keys") { + print <Deprecated - see DNSSEC-KEYS. +END + } + if ($1 eq "managed-keys") { + print <See DNSSEC-KEYS. +END + } + + print < END - } + } if (m{^\s*$} && !$blank) { $blank = 1; diff --git a/doc/misc/options b/doc/misc/options index f9774d06403..216d85af790 100644 --- a/doc/misc/options +++ b/doc/misc/options @@ -21,6 +21,10 @@ dlz { search ; }; // may occur multiple times +dnssec-keys { ( static-key | + initial-key ) + ; ... }; // may occur multiple times + dyndb { }; // may occur multiple times @@ -47,8 +51,9 @@ logging { lwres { }; // obsolete, may occur multiple times -managed-keys { - ; ... }; // may occur multiple times +managed-keys { ( static-key | + initial-key ) + ; ... }; // may occur multiple times masters [ port ] [ dscp ] { ( | [ @@ -207,7 +212,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 ; @@ -434,8 +439,9 @@ statistics-channels { } ]; // may occur multiple times }; // may occur multiple times -trusted-keys { - ; ... }; // may occur multiple times +trusted-keys { + + ; ... }; // may occur multiple times, deprecated view [ ] { acache-cleaning-interval ; // obsolete @@ -513,6 +519,9 @@ view [ ] { dnssec-accept-expired ; dnssec-dnskey-kskonly ; dnssec-enable ; // obsolete + dnssec-keys { ( static-key | + initial-key ) + ; ... }; // may occur multiple times dnssec-loadkeys-interval ; dnssec-lookaside ( trust-anchor | auto | no ); // may occur multiple times @@ -553,11 +562,11 @@ view [ ] { }; // may occur multiple times key-directory ; lame-ttl ; - lmdb-mapsize ; // non-operational + lmdb-mapsize ; maintain-ixfr-base ; // ancient - managed-keys { - - ; ... }; // may occur multiple times + managed-keys { ( static-key | + initial-key ) + ; ... }; // may occur multiple times masterfile-format ( map | raw | text ); masterfile-style ( full | relative ); match-clients { ; ... }; @@ -720,9 +729,10 @@ view [ ] { transfer-source-v6 ( | * ) [ port ( | * ) ] [ dscp ]; trust-anchor-telemetry ; // experimental - trusted-keys { - ; - ... }; // may occur multiple times + trusted-keys { + + + ; ... }; // may occur multiple times, deprecated try-tcp-refresh ; update-check-ksk ; use-alt-transfer-source ; diff --git a/lib/dns/zone.c b/lib/dns/zone.c index 97c0c40985a..6681446a7a5 100644 --- a/lib/dns/zone.c +++ b/lib/dns/zone.c @@ -4365,10 +4365,10 @@ sync_keyzone(dns_zone_t *zone, dns_db_t *db) { /* * Walk the zone DB. If we find any keys whose names are no longer - * in managed-keys (or *are* in trusted-keys, meaning they are - * permanent and not RFC5011-maintained), delete them from the - * zone. Otherwise call load_secroots(), which loads keys into - * secroots as appropriate. + * in managed-keys as initial-keys (or which are now configured as + * static keys, meaning they are permanent and not RFC5011-maintained), + * delete them from the zone. Otherwise call load_secroots(), which + * loads keys into secroots as appropriate. */ dns_rriterator_init(&rrit, db, ver, 0); for (result = dns_rriterator_first(&rrit); diff --git a/util/copyrights b/util/copyrights index ff2bd91ac1c..67c539cbfdb 100644 --- a/util/copyrights +++ b/util/copyrights @@ -1427,6 +1427,7 @@ ./doc/arm/controls.grammar.xml SGML 2018,2019 ./doc/arm/delegation-only.zoneopt.xml SGML 2018,2019 ./doc/arm/dlz.xml SGML 2012,2013,2014,2015,2016,2018,2019 +./doc/arm/dnssec-keys.grammar.xml SGML 2019 ./doc/arm/dnssec.xml SGML 2010,2011,2015,2016,2017,2018,2019 ./doc/arm/dyndb.xml SGML 2015,2016,2018,2019 ./doc/arm/forward.zoneopt.xml SGML 2018,2019