Commit 3853b3cf authored by Evan Hunt's avatar Evan Hunt

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
parent d07053c8
......@@ -218,14 +218,17 @@
</para>
<para>
Note: When reading the trust anchor file,
<command>delv</command> treats <option>managed-keys</option>
statements and <option>trusted-keys</option> statements
identically. That is, for a managed key, it is the
<emphasis>initial</emphasis> key that is trusted; RFC 5011
key management is not supported. <command>delv</command>
will not consult the managed-keys database maintained by
<command>named</command>. This means that if either of the
keys in <filename>/etc/bind.keys</filename> is revoked
<command>delv</command> treats <option>dnssec-keys</option>
<option>initial-key</option> and <option>static-key</option>
entries identically. That is, even if a key is configured
with <command>initial-key</command>, indicating that it is
meant to be used only as an initializing key for RFC 5011
key maintenance, it is still treated by <command>delv</command>
as if it had been configured as a <command>static-key</command>.
<command>delv</command> does not consult the managed keys
database maintained by <command>named</command>. This means
that if either of the keys in
<filename>/etc/bind.keys</filename> is revoked
and rolled over, it will be necessary to update
<filename>/etc/bind.keys</filename> to use DNSSEC
validation in <command>delv</command>.
......
......@@ -13,7 +13,7 @@
<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.named.conf">
<info>
<date>2018-12-07</date>
<date>2019-05-10</date>
</info>
<refentryinfo>
<corpname>ISC</corpname>
......@@ -80,14 +80,12 @@
</refsection>
<refsection><info><title>ACL</title></info>
<literallayout class="normal">
acl <replaceable>string</replaceable> { <replaceable>address_match_element</replaceable>; ... };
</literallayout>
</refsection>
<refsection><info><title>CONTROLS</title></info>
<literallayout class="normal">
controls {
inet ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> |
......@@ -104,7 +102,6 @@ controls {
</refsection>
<refsection><info><title>DLZ</title></info>
<literallayout class="normal">
dlz <replaceable>string</replaceable> {
database <replaceable>string</replaceable>;
......@@ -113,8 +110,15 @@ dlz <replaceable>string</replaceable> {
</literallayout>
</refsection>
<refsection><info><title>DYNDB</title></info>
<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>
<replaceable>quoted_string</replaceable>; ... };
</literallayout>
</refsection>
<refsection><info><title>DYNDB</title></info>
<literallayout class="normal">
dyndb <replaceable>string</replaceable> <replaceable>quoted_string</replaceable> {
<replaceable>unspecified-text</replaceable> };
......@@ -122,7 +126,6 @@ dyndb <replaceable>string</replaceable> <replaceable>quoted_string</replaceable>
</refsection>
<refsection><info><title>KEY</title></info>
<literallayout class="normal">
key <replaceable>string</replaceable> {
algorithm <replaceable>string</replaceable>;
......@@ -132,7 +135,6 @@ key <replaceable>string</replaceable> {
</refsection>
<refsection><info><title>LOGGING</title></info>
<literallayout class="normal">
logging {
category <replaceable>string</replaceable> { <replaceable>string</replaceable>; ... };
......@@ -154,15 +156,15 @@ logging {
<refsection><info><title>MANAGED-KEYS</title></info>
<para>See DNSSEC-KEYS.</para>
<literallayout class="normal">
managed-keys { <replaceable>string</replaceable> <replaceable>string</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
managed-keys { <replaceable>string</replaceable> ( static-key |
initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };
</literallayout>
</refsection>
<refsection><info><title>MASTERS</title></info>
<literallayout class="normal">
masters <replaceable>string</replaceable> [ port <replaceable>integer</replaceable> ] [ dscp
<replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [
......@@ -172,7 +174,6 @@ masters <replaceable>string</replaceable> [ port <replaceable>integer</replaceab
</refsection>
<refsection><info><title>OPTIONS</title></info>
<literallayout class="normal">
options {
allow-new-zones <replaceable>boolean</replaceable>;
......@@ -251,7 +252,6 @@ options {
dnsrps-options { <replaceable>unspecified-text</replaceable> };
dnssec-accept-expired <replaceable>boolean</replaceable>;
dnssec-dnskey-kskonly <replaceable>boolean</replaceable>;
dnssec-enable <replaceable>boolean</replaceable>;
dnssec-loadkeys-interval <replaceable>integer</replaceable>;
dnssec-lookaside ( <replaceable>string</replaceable> trust-anchor
<replaceable>string</replaceable> | auto | no );
......@@ -403,11 +403,12 @@ options {
resolver-retry-interval <replaceable>integer</replaceable>;
response-padding { <replaceable>address_match_element</replaceable>; ... } block-size
<replaceable>integer</replaceable>;
response-policy { zone <replaceable>string</replaceable> [ log <replaceable>boolean</replaceable> ] [ max-policy-ttl
<replaceable>ttlval</replaceable> ] [ min-update-interval <replaceable>ttlval</replaceable> ] [ policy ( cname |
disabled | drop | given | no-op | nodata | nxdomain | passthru
| tcp-only <replaceable>quoted_string</replaceable> ) ] [ recursive-only <replaceable>boolean</replaceable> ] [
nsip-enable <replaceable>boolean</replaceable> ] [ nsdname-enable <replaceable>boolean</replaceable> ]; ... } [
response-policy { zone <replaceable>string</replaceable> [ add-soa <replaceable>boolean</replaceable> ] [ log
<replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>ttlval</replaceable> ] [ min-update-interval
<replaceable>ttlval</replaceable> ] [ policy ( cname | disabled | drop | given | no-op |
nodata | nxdomain | passthru | tcp-only <replaceable>quoted_string</replaceable> ) ] [
recursive-only <replaceable>boolean</replaceable> ] [ nsip-enable <replaceable>boolean</replaceable> ] [
nsdname-enable <replaceable>boolean</replaceable> ]; ... } [ add-soa <replaceable>boolean</replaceable> ] [
break-dnssec <replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>ttlval</replaceable> ] [
min-update-interval <replaceable>ttlval</replaceable> ] [ min-ns-dots <replaceable>integer</replaceable> ] [
nsip-wait-recurse <replaceable>boolean</replaceable> ] [ qname-wait-recurse <replaceable>boolean</replaceable> ]
......@@ -474,7 +475,6 @@ options {
</refsection>
<refsection><info><title>PLUGIN</title></info>
<literallayout class="normal">
plugin ( query ) <replaceable>string</replaceable> [ { <replaceable>unspecified-text</replaceable>
} ];
......@@ -482,7 +482,6 @@ plugin ( query ) <replaceable>string</replaceable> [ { <replaceable>unspecified-
</refsection>
<refsection><info><title>SERVER</title></info>
<literallayout class="normal">
server <replaceable>netprefix</replaceable> {
bogus <replaceable>boolean</replaceable>;
......@@ -520,7 +519,6 @@ server <replaceable>netprefix</replaceable> {
</refsection>
<refsection><info><title>STATISTICS-CHANNELS</title></info>
<literallayout class="normal">
statistics-channels {
inet ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> |
......@@ -532,15 +530,15 @@ statistics-channels {
</refsection>
<refsection><info><title>TRUSTED-KEYS</title></info>
<para>Deprecated - see DNSSEC-KEYS.</para>
<literallayout class="normal">
trusted-keys { <replaceable>string</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
trusted-keys { <replaceable>string</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };, deprecated
</literallayout>
</refsection>
<refsection><info><title>VIEW</title></info>
<literallayout class="normal">
view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
allow-new-zones <replaceable>boolean</replaceable>;
......@@ -612,7 +610,9 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
dnsrps-options { <replaceable>unspecified-text</replaceable> };
dnssec-accept-expired <replaceable>boolean</replaceable>;
dnssec-dnskey-kskonly <replaceable>boolean</replaceable>;
dnssec-enable <replaceable>boolean</replaceable>;
dnssec-keys { <replaceable>string</replaceable> ( static-key |
initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
dnssec-loadkeys-interval <replaceable>integer</replaceable>;
dnssec-lookaside ( <replaceable>string</replaceable> trust-anchor
<replaceable>string</replaceable> | auto | no );
......@@ -650,9 +650,9 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
key-directory <replaceable>quoted_string</replaceable>;
lame-ttl <replaceable>ttlval</replaceable>;
lmdb-mapsize <replaceable>sizeval</replaceable>;
managed-keys { <replaceable>string</replaceable> <replaceable>string</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };
managed-keys { <replaceable>string</replaceable> ( static-key |
initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
masterfile-format ( map | raw | text );
masterfile-style ( full | relative );
match-clients { <replaceable>address_match_element</replaceable>; ... };
......@@ -735,11 +735,12 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
resolver-retry-interval <replaceable>integer</replaceable>;
response-padding { <replaceable>address_match_element</replaceable>; ... } block-size
<replaceable>integer</replaceable>;
response-policy { zone <replaceable>string</replaceable> [ log <replaceable>boolean</replaceable> ] [ max-policy-ttl
<replaceable>ttlval</replaceable> ] [ min-update-interval <replaceable>ttlval</replaceable> ] [ policy ( cname |
disabled | drop | given | no-op | nodata | nxdomain | passthru
| tcp-only <replaceable>quoted_string</replaceable> ) ] [ recursive-only <replaceable>boolean</replaceable> ] [
nsip-enable <replaceable>boolean</replaceable> ] [ nsdname-enable <replaceable>boolean</replaceable> ]; ... } [
response-policy { zone <replaceable>string</replaceable> [ add-soa <replaceable>boolean</replaceable> ] [ log
<replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>ttlval</replaceable> ] [ min-update-interval
<replaceable>ttlval</replaceable> ] [ policy ( cname | disabled | drop | given | no-op |
nodata | nxdomain | passthru | tcp-only <replaceable>quoted_string</replaceable> ) ] [
recursive-only <replaceable>boolean</replaceable> ] [ nsip-enable <replaceable>boolean</replaceable> ] [
nsdname-enable <replaceable>boolean</replaceable> ]; ... } [ add-soa <replaceable>boolean</replaceable> ] [
break-dnssec <replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>ttlval</replaceable> ] [
min-update-interval <replaceable>ttlval</replaceable> ] [ min-ns-dots <replaceable>integer</replaceable> ] [
nsip-wait-recurse <replaceable>boolean</replaceable> ] [ qname-wait-recurse <replaceable>boolean</replaceable> ]
......@@ -801,9 +802,10 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
transfer-source-v6 ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * )
] [ dscp <replaceable>integer</replaceable> ];
trust-anchor-telemetry <replaceable>boolean</replaceable>; // experimental
trusted-keys { <replaceable>string</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>;
... };
trusted-keys { <replaceable>string</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };, deprecated
try-tcp-refresh <replaceable>boolean</replaceable>;
update-check-ksk <replaceable>boolean</replaceable>;
use-alt-transfer-source <replaceable>boolean</replaceable>;
......@@ -915,7 +917,6 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
</refsection>
<refsection><info><title>ZONE</title></info>
<literallayout class="normal">
zone <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
allow-notify { <replaceable>address_match_element</replaceable>; ... };
......
......@@ -458,7 +458,7 @@
<term><userinput>managed-keys <replaceable>(status | refresh | sync | destroy)</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
<listitem>
<para>
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 @@
<listitem>
<para>
When run with the <literal>status</literal> keyword, prints
the current status of the managed-keys database.
the current status of the managed keys database.
</para>
</listitem>
<listitem>
<para>
When run with the <literal>refresh</literal> 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.
</para>
......@@ -482,7 +482,7 @@
<listitem>
<para>
When run with the <literal>sync</literal> keyword, forces an
immediate dump of the managed-keys database to disk
immediate dump of the managed keys database to disk
(in the file <filename>managed-keys.bind</filename> or
(<filename><replaceable>viewname</replaceable>.mkeys</filename>).
This synchronizes the database with its journal file, so
......@@ -493,7 +493,7 @@
<listitem>
<para>
When run with the <literal>destroy</literal> 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.
</para>
......@@ -772,9 +772,10 @@
<listitem>
<para>
Dump the security roots (i.e., trust anchors
configured via <command>trusted-keys</command>,
<command>managed-keys</command>, or
<command>dnssec-validation auto</command>) and negative trust
configured via <command>dnssec-keys</command> statements,
or the synonymous <command>managed-keys</command> or
the deprecated <command>trusted-keys</command> statements, or
via <command>dnssec-validation auto</command>) 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
......
......@@ -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==";
};
......
......@@ -2087,7 +2087,7 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
zone key of another zone above this one in the DNS tree.
</para>
<section xml:id="dnssec_keys"><info><title>Generating Keys</title></info>
<section xml:id="generating_dnssec_keys"><info><title>Generating Keys</title></info>
<para>
The <command>dnssec-keygen</command> program is used to
......@@ -2212,8 +2212,9 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
<userinput>yes</userinput>, DNSSEC validation will only occur
if at least one trust anchor has been explicitly configured
in <filename>named.conf</filename>
using a <command>trusted-keys</command> or
<command>managed-keys</command> statement.
using a <command>dnssec-keys</command> statement (or the
synonymous <command>managed-keys</command> or the deprecated
<command>trusted-keys</command> statements).
</para>
<para>
When <command>dnssec-validation</command> is set to
......@@ -2226,23 +2227,20 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
</para>
<para>
<command>trusted-keys</command> 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
<command>trusted-keys</command> (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 <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
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
RFC 5011 trust anchor maintenance, and will be kept up to
date automatically after the first time <command>named</command>
runs.
</para>
<para>
<command>managed-keys</command> are trusted keys which are
automatically kept up to date via RFC 5011 trust anchor
maintenance.
</para>
<para>
<command>trusted-keys</command> and
<command>managed-keys</command> are described in more detail
<command>dnssec-keys</command> is described in more detail
later in this document.
</para>
......@@ -2265,7 +2263,7 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
</para>
<programlisting>
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.
</row>
<row rowsep="0">
<entry colname="1">
<para><command>trusted-keys</command></para>
<para><command>dnssec-keys</command></para>
</entry>
<entry colname="2">
<para>
defines trusted DNSSEC keys.
defines DNSSEC keys: if used with the
<command>initial-key</command> keyword,
keys are kept up to date using RFC 5011
trust anchor maintenance, and if used with
<command>static-key</command>, keys are permanent.
Identical to <command>managed-keys</command>,
but has been added for improved clarity.
</para>
</entry>
</row>
......@@ -3219,8 +3220,22 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
</entry>
<entry colname="2">
<para>
lists DNSSEC keys to be kept up to date
using RFC 5011 trust anchor maintenance.
is identical to <command>dnssec-keys</command>,
and is retained for backward compatibility.
</para>
</entry>
</row>
<row rowsep="0">
<entry colname="1">
<para><command>trusted-keys</command></para>
</entry>
<entry colname="2">
<para>
defines permanent trusted DNSSEC keys;
this option is deprecated in favor
of <command>dnssec-keys</command> with
the <command>static-key</command> keyword,
and may be removed in a future release.
</para>
</entry>
</row>
......@@ -4595,10 +4610,12 @@ badresp:1,adberr:0,findfail:0,valfail:0]
<listitem>
<para>
Specifies the directory in which to store the files that
track managed DNSSEC keys. By default, this is the working
directory. The directory <emphasis>must</emphasis>
be writable by the effective user ID of the
<command>named</command> process.
track managed DNSSEC keys (i.e., those configured using
the <command>initial-key</command> keyword in a
<command>dnssec-keys</command> statement). By default,
this is the working directory. The directory
<emphasis>must</emphasis> be writable by the effective
user ID of the <command>named</command> process.
</para>
<para>
If <command>named</command> is not configured to use views,
......@@ -5100,10 +5117,10 @@ options {
then <command>named</command> will only accept answers if
they are secure. If <userinput>no</userinput>, then normal
DNSSEC validation applies allowing for insecure answers to
be accepted. The specified domain must be under a
<command>trusted-keys</command> or
<command>managed-keys</command> statement, or
<command>dnssec-validation auto</command> must be active.
be accepted. The specified domain must be defined as a
trust anchor, for instance in a <command>dnssec-keys</command>
statement, or <command>dnssec-validation auto</command> must
be active.
</para>
</listitem>
</varlistentry>
......@@ -6195,8 +6212,8 @@ options {
<para>
Causes <command>named</command> to send specially-formed
queries once per day to domains for which trust anchors
have been configured via <command>trusted-keys</command>,
<command>managed-keys</command>, or
have been configured via, e.g.,
<command>dnssec-keys</command> or
<command>dnssec-validation auto</command>.
</para>
<para>
......@@ -6411,10 +6428,11 @@ options {
<para>
If set to <userinput>yes</userinput>, DNSSEC validation is
enabled, but a trust anchor must be manually configured
using a <command>trusted-keys</command>
or <command>managed-keys</command> statement; if there
is no configured trust anchor, validation will not take
place.
using a <command>dnssec-keys</command> statement (or
the synonymous <command>managed-keys</command>, or the
deprecated <command>trusted-keys</command> statements).
If there is no configured trust anchor, validation will
not take place.
</para>
<para>
If set to <userinput>no</userinput>, DNSSEC validation
......@@ -10822,133 +10840,123 @@ example.com CNAME rpz-tcp-only.
</para>
</section>
<section xml:id="trusted-keys"><info><title><command>trusted-keys</command> Statement Grammar</title></info>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="trusted-keys.grammar.xml"/>
<section xml:id="dnssec_keys"><info><title><command>dnssec-keys</command> Statement Grammar</title></info>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dnssec-keys.grammar.xml"/>
</section>
<section xml:id="trusted_keys"><info><title><command>trusted-keys</command> Statement Definition
<section xml:id="dnssec-keys"><info><title><command>dnssec-keys</command> Statement Definition
and Usage</title></info>
<para>
The <command>trusted-keys</command> statement defines
DNSSEC security roots. DNSSEC is described in <xref linkend="DNSSEC"/>. 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 <command>dnssec-keys</command> statement defines DNSSEC
trust anchors. DNSSEC is described in <xref linkend="DNSSEC"/>.
</para>
<para>
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.
</para>
<para>
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
<command>rndc nta</command>, or permanently disabled with
the <command>validate-except</command> option).
</para>
<para>
All keys (and corresponding zones) listed in
<command>trusted-keys</command> are deemed to exist regardless
of what parent zones say. Similarly for all keys listed in
<command>trusted-keys</command> only those keys are
used to validate the DNSKEY RRset. The parent's DS RRset
will not be used.
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
are used to validate the DNSKEY RRset for the corresponding
name. The parent's DS RRset will not be used.
</para>
<para>
The <command>trusted-keys</command> statement can contain
The <command>dnssec-keys</command> 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 <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>trusted-keys</command> may be set at the top level
<command>dnssec-keys</command> may be set at the top level
of <filename>named.conf</filename> 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.
</para>
<para>
Validation below specified names can be temporarily disabled
by using <command>rndc nta</command>.
</para>
</section>
<section xml:id="managed_keys"><info><title><command>managed-keys</command> Statement Grammar</title></info>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="managed-keys.grammar.xml"/>
</section>
<section xml:id="managed-keys"><info><title><command>managed-keys</command> Statement Definition
and Usage</title></info>
<para>
The <command>managed-keys</command> statement, like
<command>trusted-keys</command>, defines DNSSEC
security roots. The difference is that
<command>managed-keys</command> can be kept up to date
automatically, without intervention from the resolver
operator.
<command>dnssec-keys</command> entries can be configured with
two keywords: <command>static-key</command> or
<command>initial-key</command>. Keys configured with
<command>static-key</command> are immutable,
while keys configured with <command>initial-key</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
<command>trusted-keys</command> statement.)
</para>
<para>
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
<command>trusted-keys</command> statement would be
replace the key. A resolver which had the original key
configured as a <command>static-key</command> 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
<command>trusted-keys</command> statement with the new key.
<command>dnssec-keys</command> statement with the new key.
</para>
<para>
If, however, the zone were listed in a
<command>managed-keys</command> 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
<command>initial-key</command> instead, then the
zone owner could add a "stand-by" key to their zone in advance.
<command>named</command> would store the stand-by key, and
when the original key was revoked, <command>named</command>
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.
</para>
<para>
A <command>managed-keys</command> 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
<literal>initial-key</literal>.
This means the <command>managed-keys</command> statement must
contain a copy of the initializing key. (Future releases may
allow keys to be initialized by other methods, eliminating this
requirement.)
</para>
<para>
Consequently, a <command>managed-keys</command> statement
appears similar to a <command>trusted-keys</command>, differing
in the presence of the second field, containing the keyword
<literal>initial-key</literal>. The difference is, whereas the
keys listed in a <command>trusted-keys</command> continue to be
trusted until they are removed from
<filename>named.conf</filename>, an initializing key listed
in a <command>managed-keys</command> statement 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>
The first time <command>named</command> runs with a managed key
configured in <filename>named.conf</filename>, it fetches the
the compromised key could do. This is the process used to
keep the ICANN root DNSSEC key up to date.
</para>