mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-30 14:07:59 +00:00
Code Issues Releases Wiki Activity

revise dnssec-policy documentation

Browse Source
This commit is contained in:
Evan Hunt 2020-02-07 23:41:18 -08:00
parent c72d37f3d5
commit c7866acbf7
2 changed files with 154 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
doc/arm/Bv9ARM-book.xml
View File

@ -11087,33 +11087,89 @@ example.com CNAME rpz-tcp-only.
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dnssec-policy.grammar.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dnssec-policy.grammar.xml"/>
</section> </section>
<section xml:id="dnssec_policy"><info><title><command>dnssec-policy</command> Statement Definition <section xml:id="dnssec_policy"><info><title><command>dnssec-policy</command> Statement Definition and Usage</title></info>
and Usage</title></info>
<para> <para>
The <command>dnssec-policy</command> statement defines a key and The <command>dnssec-policy</command> statement defines a key and
signing policy (KASP) for zones. signing policy (KASP) for zones.
</para> </para>
<para> <para>
KASP is used to determine how one or more zones need to be signed A KASP determines how one or more zones will be signed
with DNSSEC. For example, how often RRSIG records need to be with DNSSEC. For example, it specifies how often keys should
refreshed, or what cryptographic algorithms to use. roll, which cryptographic algorithms to use, and how often RRSIG
records need to be refreshed.
</para> </para>
<para> <para>
You can configure multiple policies. To attach a policy to a zone Multiple key and signing policies can be configured. To
simply add <userinput>dnssec-policy "policy_name"</userinput> attach a policy to a zone, add a <command>dnssec-policy</command>
option to the <command>zone</command> statement with a matching option to the <command>zone</command> statement, specifying he
policy name. name of the policy that should be used.
</para>
<para>
Key rollover timing is computed for each key according to
the key lifetime defined in the KASP. The lifetime may be
modified by zone TTLs and propagation delays, in order to
prevent validation failures. When a key reaches the end of its
lifetime,
<command>named</command> will generate and publish a new key
automatically, then deactivate the old key and activate the
new one, and finally retire the old key according to a computed
schedule.
</para>
<para>
Zone-signing key (ZSK) rollovers require no operator input.
Key-signing key (KSK) and combined signing key (CSK) rollovers
require action to be taken to submit a DS record to the parent.
Rollover timing for KSKs and CSKs is adjusted to take into account
delays in processing and propagating DS updates.
</para>
<para>
There are two predefined <command>dnssec-policy</command> names:
<command>none</command> and <command>default</command>.
Setting a zone's policy to
<command>none</command> is the same as not setting
<command>dnssec-policy</command> at all; the zone will not
be signed. Policy <command>default</command> causes the
zone to be signed with a single combined signing key (CSK)
using algorithm ECDSAP256SHA256; this key will have an
unlimited lifetime. (A verbose copy of this policy
may be found in the source tree, in the file
<filename>doc/misc/dnssec-policy.default.conf</filename>.)
<note>
The default signing policy may change in future releases.
This could result in changes to your signing policy
occurring when you upgrade to a new version of BIND. Check
the release notes carefully when upgrading to be informed
of such changes. To prevent policy changes on upgrade,
use an explicitly defined <command>dnssec-policy</command>
rather than <command>default</command>.
</note>
</para>
<para>
If a <command>dnssec-policy</command> statement is modified
and the server restarted or reconfigured, <command>named</command>
will attempt to change the policy smoothly from the old one to
the new. For example, if the key algorithm is changed, then
a new key will be generated with the new algorithm, and the old
algorithm will be retired when the existing key's lifetime ends.
<note>
Rolling to a new policy while another key rollover is
already in progress is not yet supported, and may result in
unexpected behavior.
</note>
</para>
<para>
The following options can be specified in a
<command>dnssec-policy</command> statement:
</para> </para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><command>dnskey-ttl</command></term> <term><command>dnskey-ttl</command></term>
<listitem> <listitem>
<para> <para>
The TTL of the DNSKEY resource records. The TTL to use when generating DNSKEY resource records.
Default is <constant>3600</constant> seconds. The default is 1 hour (3600 seconds).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11122,30 +11178,48 @@ example.com CNAME rpz-tcp-only.
<term><command>keys</command></term> <term><command>keys</command></term>
<listitem> <listitem>
<para> <para>
A list of keys to use. Each line represents one key. Here is A list specifying the algorithms and roles to use when
an example (for illustration purposes only) of some possible generating keys and signing the zone.
keys in a <command>dnssec-policy</command>: Entries in this list do not represent specific
DNSSEC keys, which may be changed on a regular basis,
but the roles that keys will play in the signing policy.
For example, configuring a KSK of algorithm RSASHA256 ensures
that the DNSKEY RRset will always include a key-signing key
for that algorithm.
</para>
<para>
Here is an example (for illustration purposes only) of
some possible entries in a <command>keys</command>
list:
</para> </para>
<programlisting>keys { <programlisting>keys {
ksk key-directory lifetime unlimited algorithm rsasha1 2048; ksk key-directory lifetime unlimited algorithm rsasha1 2048;
zsk key-directory lifetime P30D algorithm 8; zsk lifetime P30D algorithm 8;
csk key-directory lifetime P6MT12H3M15S algorithm ecdsa256; csk lifetime P6MT12H3M15S algorithm ecdsa256;
}; };
</programlisting> </programlisting>
<para> <para>
This example lists three keys. The first token determines This example specifies that three keys should be used
what RRsets the key will sign. If set to in the zone. The first token determines which role the
<userinput>ksk</userinput> the key will sign the DNSKEY, CDS, key will play in signing RRsets. If set to
and CDNSKEY RRsets, if set to <userinput>zsk</userinput> the <userinput>ksk</userinput>, then this will be
key will sign the other RRsets, and if set to a key-signing key; it will have the KSK flag set and
<userinput>csk</userinput> the key will sign all RRsets. will only be used to sign DNSKEY, CDS, and CDNSKEY RRsets.
If set to <userinput>zsk</userinput>, this will be
a zone-signing key; the KSK flag will be unset, and
the key will sign all RRsets <emphasis>except</emphasis>
DNSKEY, CDS, and CDNSKEY. If set to
<userinput>csk</userinput> the key will have the KSK
flag set and will be used to sign all RRsets.
</para> </para>
<para> <para>
The following part determines where the key will be stored. An optional second token determines where the key will
Currently keys can only be stored in the configured be stored. Currently, keys can only be stored in the
<command>key-directory</command>. configured <command>key-directory</command>. This token
may be used in the future to store keys in hardware
service modules or separate directories.
</para> </para>
<para> <para>
The <command>lifetime</command> parameter specifies how The <command>lifetime</command> parameter specifies how
@ -11158,18 +11232,19 @@ example.com CNAME rpz-tcp-only.
</para> </para>
<para> <para>
Note that the lifetime of a key may be extended if Note that the lifetime of a key may be extended if
retiring it too soon would cause validation failures: retiring it too soon would cause validation failures.
for example, if the key were configured to roll more For example, if the key were configured to roll more
frequently than its TTL, its lifetime would frequently than its own TTL, its lifetime would
automatically be extended to account for this. automatically be extended to account for this.
</para> </para>
<para> <para>
The <command>algorithm</command> parameter(s) are the key's The <command>algorithm</command> parameter specifies
algorithm, expressed either as a string ("rsasha256", the key's algorithm, expressed either as a string
"ecdsa384", etc) or as a decimal number, and the key's ("rsasha256", "ecdsa384", etc) or as a decimal number.
size in bits. The size may be omitted, as shown in An optional second parameter specifies the key's size
the example for the second and third keys; in this case in size in bits. If it is omitted, as shown in the
an appropriate default size will be used. example for the second and third keys, an appropriate
default size for the algorithm will be used.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11178,10 +11253,11 @@ example.com CNAME rpz-tcp-only.
<term><command>publish-safety</command></term> <term><command>publish-safety</command></term>
<listitem> <listitem>
<para> <para>
A margin that is added to the publish interval in key A margin that is added to the pre-publication
timing equations to give some extra time to cover interval in rollover timing calcuations to give some
unforeseen events. Default is <constant>PT1H</constant> extra time to cover unforeseen events. This increases
(1 hour). the time that keys are published before becoming active.
The default is <constant>PT1H</constant> (1 hour).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11190,10 +11266,11 @@ example.com CNAME rpz-tcp-only.
<term><command>retire-safety</command></term> <term><command>retire-safety</command></term>
<listitem> <listitem>
<para> <para>
A margin that is added to the retire interval in key A margin that is added to the post-publication interval
timing equations to give some extra time to cover in rollover timing calculations to give some extra time
unforeseen events. Default is <constant>PT1H</constant> to cover unforeseen events. This increases the time a key
(1 hour). remains published after it is no longer active. The
default is <constant>PT1H</constant> (1 hour).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11202,13 +11279,12 @@ example.com CNAME rpz-tcp-only.
<term><command>signatures-refresh</command></term> <term><command>signatures-refresh</command></term>
<listitem> <listitem>
<para> <para>
This determines when a RRSIG record needs to be This determines how frequently an RRSIG record needs to be
refreshed. The signatures is renewed when the time until refreshed. The signature is renewed when the time until
the expiration time is closer than the expiration time is closer than the specified interval.
<command>signatures-refresh</command>. The default is <constant>P5D</constant> (5 days), meaning
<command>signatures-resign</command> interval. Default signatures that will expire in 5 days or sooner will be
is <constant>P5D</constant> (5 days), meaning a signature refreshed.
that will expire in 5 days or sooner will be refreshed.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11217,8 +11293,8 @@ example.com CNAME rpz-tcp-only.
<term><command>signatures-validity</command></term> <term><command>signatures-validity</command></term>
<listitem> <listitem>
<para> <para>
The validity period of an RRSIG record (minus the The validity period of an RRSIG record (subject to
inception offset and jitter). Default is inception offset and jitter). The default is
<constant>P2W</constant> (2 weeks). <constant>P2W</constant> (2 weeks).
</para> </para>
</listitem> </listitem>
@ -11228,9 +11304,9 @@ example.com CNAME rpz-tcp-only.
<term><command>signatures-validity-dnskey</command></term> <term><command>signatures-validity-dnskey</command></term>
<listitem> <listitem>
<para> <para>
Like <command>signatures-validity</command> but for Similar to <command>signatures-validity</command> but for
DNSKEY records. Default is <constant>P2W</constant> (2 DNSKEY records. The default is <constant>P2W</constant>
weeks). (2 weeks).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11245,7 +11321,7 @@ example.com CNAME rpz-tcp-only.
a <option>masterfile-format</option> of a <option>masterfile-format</option> of
<constant>text</constant> or <constant>raw</constant>, <constant>text</constant> or <constant>raw</constant>,
any record encountered with a TTL higher than any record encountered with a TTL higher than
<option>max-zone-ttl</option> will be capped to the <option>max-zone-ttl</option> will be capped at the
maximum permissible TTL value. maximum permissible TTL value.
</para> </para>
<para> <para>
@ -11273,10 +11349,10 @@ example.com CNAME rpz-tcp-only.
<term><command>zone-propagation-delay</command></term> <term><command>zone-propagation-delay</command></term>
<listitem> <listitem>
<para> <para>
The expected propagation delay from when a zone is The expected propagation delay from the time when a zone
updated and when the new version of the zone is served by is first updated to the time when the new version of the
all its name servers. Default is zone will be served by all secondary servers. The default
<constant>PT5M</constant> (5 minutes). is <constant>PT5M</constant> (5 minutes).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11285,8 +11361,8 @@ example.com CNAME rpz-tcp-only.
<term><command>parent-ds-ttl</command></term> <term><command>parent-ds-ttl</command></term>
<listitem> <listitem>
<para> <para>
The TTL of the DS RRset that the parent uses. Default is The TTL of the DS RRset that the parent zone uses. The
<constant>P1D</constant> (1 day). default is <constant>P1D</constant> (1 day).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11295,10 +11371,10 @@ example.com CNAME rpz-tcp-only.
<term><command>parent-propagation-delay</command></term> <term><command>parent-propagation-delay</command></term>
<listitem> <listitem>
<para> <para>
The expected propagation delay from when the parent zone The expected propagation delay from the time when the
is updated and when the new version of the parent zone is parent zone is updated to the time when the new version
served by all its name servers. Default is is served by all of the parent zone's name servers.
<constant>PT1H</constant> (1 hour). The default is <constant>PT1H</constant> (1 hour).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -11307,9 +11383,9 @@ example.com CNAME rpz-tcp-only.
<term><command>parent-registration-delay</command></term> <term><command>parent-registration-delay</command></term>
<listitem> <listitem>
<para> <para>
The expected registration delay from when a DS RRset The expected registration delay from the time when a DS
change is requested and when the DS RRset has been RRset change is requested to the time when the DS RRset
updated in the parent zone. Default is will be updated in the parent zone. The default is
<constant>P1D</constant> (1 day). <constant>P1D</constant> (1 day).
</para> </para>
</listitem> </listitem>
@ -12195,13 +12271,16 @@ view "external" {
<term><command>dnssec-policy</command></term> <term><command>dnssec-policy</command></term>
<listitem> <listitem>
<para> <para>
The key and signing policy for this zone. This is a string Specifies which key and signing policy (KASP) should
referring to a <command>dnssec-policy</command> statement. be used for this zone. This is a string referring to
a <command>dnssec-policy</command> statement.
There are two built-in policies: There are two built-in policies:
<userinput>"default"</userinput> allows you to use the <userinput>default</userinput> allows you to use the
default policy, and <userinput>"none"</userinput> means default policy, and <userinput>none</userinput> means
not to use any DNSSEC policy, keeping the zone unsigned. not to use any DNSSEC policy, keeping the zone unsigned.
The default is <userinput>"none"</userinput>. The default is <userinput>none</userinput>.
See <xref linkend="dnssec_policy_grammar"/> for
more details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>

3
doc/misc/dnssec-policy.default.conf
View File

@ -1,5 +1,4 @@
dnssec-policy "default" { dnssec-policy "default" {
// Keys // Keys
keys { keys {
csk key-directory lifetime unlimited algorithm 13; csk key-directory lifetime unlimited algorithm 13;
@ -14,7 +13,7 @@ dnssec-policy "default" {
signatures-refresh 5d; signatures-refresh 5d;
signatures-validity 14d; signatures-validity 14d;
signatures-validity-dnskey 14d; signatures-validity-dnskey 14d;
// Zone parameters // Zone parameters
max-zone-ttl 86400; max-zone-ttl 86400;
zone-propagation-delay 300; zone-propagation-delay 300;