diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index 0cc7831c3d..ba3df88dfd 100644
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -11087,33 +11087,89 @@ example.com CNAME rpz-tcp-only.
- dnssec-policy Statement Definition
- and Usage
+ dnssec-policy Statement Definition and Usage
The dnssec-policy statement defines a key and
signing policy (KASP) for zones.
- KASP is used to determine how one or more zones need to be signed
- with DNSSEC. For example, how often RRSIG records need to be
- refreshed, or what cryptographic algorithms to use.
+ A KASP determines how one or more zones will be signed
+ with DNSSEC. For example, it specifies how often keys should
+ roll, which cryptographic algorithms to use, and how often RRSIG
+ records need to be refreshed.
- You can configure multiple policies. To attach a policy to a zone
- simply add dnssec-policy "policy_name"
- option to the zone statement with a matching
- policy name.
+ Multiple key and signing policies can be configured. To
+ attach a policy to a zone, add a dnssec-policy
+ option to the zone statement, specifying he
+ name of the policy that should be used.
+
+
+ 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,
+ named 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.
+
+
+ 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.
+
+
+ There are two predefined dnssec-policy names:
+ none and default.
+ Setting a zone's policy to
+ none is the same as not setting
+ dnssec-policy at all; the zone will not
+ be signed. Policy default 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
+ doc/misc/dnssec-policy.default.conf.)
+
+ 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 dnssec-policy
+ rather than default.
+
+
+
+ If a dnssec-policy statement is modified
+ and the server restarted or reconfigured, named
+ 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.
+
+ Rolling to a new policy while another key rollover is
+ already in progress is not yet supported, and may result in
+ unexpected behavior.
+
+
+
+ The following options can be specified in a
+ dnssec-policy statement:
-
dnskey-ttl
- The TTL of the DNSKEY resource records.
- Default is 3600 seconds.
+ The TTL to use when generating DNSKEY resource records.
+ The default is 1 hour (3600 seconds).
@@ -11122,30 +11178,48 @@ example.com CNAME rpz-tcp-only.
keys
- A list of keys to use. Each line represents one key. Here is
- an example (for illustration purposes only) of some possible
- keys in a dnssec-policy:
+ A list specifying the algorithms and roles to use when
+ generating keys and signing the zone.
+ 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.
+
+
+ Here is an example (for illustration purposes only) of
+ some possible entries in a keys
+ list:
keys {
ksk key-directory lifetime unlimited algorithm rsasha1 2048;
- zsk key-directory lifetime P30D algorithm 8;
- csk key-directory lifetime P6MT12H3M15S algorithm ecdsa256;
+ zsk lifetime P30D algorithm 8;
+ csk lifetime P6MT12H3M15S algorithm ecdsa256;
};
- This example lists three keys. The first token determines
- what RRsets the key will sign. If set to
- ksk the key will sign the DNSKEY, CDS,
- and CDNSKEY RRsets, if set to zsk the
- key will sign the other RRsets, and if set to
- csk the key will sign all RRsets.
+ This example specifies that three keys should be used
+ in the zone. The first token determines which role the
+ key will play in signing RRsets. If set to
+ ksk, then this will be
+ a key-signing key; it will have the KSK flag set and
+ will only be used to sign DNSKEY, CDS, and CDNSKEY RRsets.
+ If set to zsk, this will be
+ a zone-signing key; the KSK flag will be unset, and
+ the key will sign all RRsets except
+ DNSKEY, CDS, and CDNSKEY. If set to
+ csk the key will have the KSK
+ flag set and will be used to sign all RRsets.
- The following part determines where the key will be stored.
- Currently keys can only be stored in the configured
- key-directory.
+ An optional second token determines where the key will
+ be stored. Currently, keys can only be stored in the
+ configured key-directory. This token
+ may be used in the future to store keys in hardware
+ service modules or separate directories.
The lifetime parameter specifies how
@@ -11158,18 +11232,19 @@ example.com CNAME rpz-tcp-only.
Note that the lifetime of a key may be extended if
- retiring it too soon would cause validation failures:
- for example, if the key were configured to roll more
- frequently than its TTL, its lifetime would
+ retiring it too soon would cause validation failures.
+ For example, if the key were configured to roll more
+ frequently than its own TTL, its lifetime would
automatically be extended to account for this.
- The algorithm parameter(s) are the key's
- algorithm, expressed either as a string ("rsasha256",
- "ecdsa384", etc) or as a decimal number, and the key's
- size in bits. The size may be omitted, as shown in
- the example for the second and third keys; in this case
- an appropriate default size will be used.
+ The algorithm parameter specifies
+ the key's algorithm, expressed either as a string
+ ("rsasha256", "ecdsa384", etc) or as a decimal number.
+ An optional second parameter specifies the key's size
+ in size in bits. If it is omitted, as shown in the
+ example for the second and third keys, an appropriate
+ default size for the algorithm will be used.
@@ -11178,10 +11253,11 @@ example.com CNAME rpz-tcp-only.
publish-safety
- A margin that is added to the publish interval in key
- timing equations to give some extra time to cover
- unforeseen events. Default is PT1H
- (1 hour).
+ A margin that is added to the pre-publication
+ interval in rollover timing calcuations to give some
+ extra time to cover unforeseen events. This increases
+ the time that keys are published before becoming active.
+ The default is PT1H (1 hour).
@@ -11190,10 +11266,11 @@ example.com CNAME rpz-tcp-only.
retire-safety
- A margin that is added to the retire interval in key
- timing equations to give some extra time to cover
- unforeseen events. Default is PT1H
- (1 hour).
+ A margin that is added to the post-publication interval
+ in rollover timing calculations to give some extra time
+ to cover unforeseen events. This increases the time a key
+ remains published after it is no longer active. The
+ default is PT1H (1 hour).
@@ -11202,13 +11279,12 @@ example.com CNAME rpz-tcp-only.
signatures-refresh
- This determines when a RRSIG record needs to be
- refreshed. The signatures is renewed when the time until
- the expiration time is closer than
- signatures-refresh.
- signatures-resign interval. Default
- is P5D (5 days), meaning a signature
- that will expire in 5 days or sooner will be refreshed.
+ This determines how frequently an RRSIG record needs to be
+ refreshed. The signature is renewed when the time until
+ the expiration time is closer than the specified interval.
+ The default is P5D (5 days), meaning
+ signatures that will expire in 5 days or sooner will be
+ refreshed.
@@ -11217,8 +11293,8 @@ example.com CNAME rpz-tcp-only.
signatures-validity
- The validity period of an RRSIG record (minus the
- inception offset and jitter). Default is
+ The validity period of an RRSIG record (subject to
+ inception offset and jitter). The default is
P2W (2 weeks).
@@ -11228,9 +11304,9 @@ example.com CNAME rpz-tcp-only.
signatures-validity-dnskey
- Like signatures-validity but for
- DNSKEY records. Default is P2W (2
- weeks).
+ Similar to signatures-validity but for
+ DNSKEY records. The default is P2W
+ (2 weeks).
@@ -11245,7 +11321,7 @@ example.com CNAME rpz-tcp-only.
a of
text or raw,
any record encountered with a TTL higher than
- will be capped to the
+ will be capped at the
maximum permissible TTL value.
@@ -11273,10 +11349,10 @@ example.com CNAME rpz-tcp-only.
zone-propagation-delay
- The expected propagation delay from when a zone is
- updated and when the new version of the zone is served by
- all its name servers. Default is
- PT5M (5 minutes).
+ The expected propagation delay from the time when a zone
+ is first updated to the time when the new version of the
+ zone will be served by all secondary servers. The default
+ is PT5M (5 minutes).
@@ -11285,8 +11361,8 @@ example.com CNAME rpz-tcp-only.
parent-ds-ttl
- The TTL of the DS RRset that the parent uses. Default is
- P1D (1 day).
+ The TTL of the DS RRset that the parent zone uses. The
+ default is P1D (1 day).
@@ -11295,10 +11371,10 @@ example.com CNAME rpz-tcp-only.
parent-propagation-delay
- The expected propagation delay from when the parent zone
- is updated and when the new version of the parent zone is
- served by all its name servers. Default is
- PT1H (1 hour).
+ The expected propagation delay from the time when the
+ parent zone is updated to the time when the new version
+ is served by all of the parent zone's name servers.
+ The default is PT1H (1 hour).
@@ -11307,9 +11383,9 @@ example.com CNAME rpz-tcp-only.
parent-registration-delay
- The expected registration delay from when a DS RRset
- change is requested and when the DS RRset has been
- updated in the parent zone. Default is
+ The expected registration delay from the time when a DS
+ RRset change is requested to the time when the DS RRset
+ will be updated in the parent zone. The default is
P1D (1 day).
@@ -12195,13 +12271,16 @@ view "external" {
dnssec-policy
- The key and signing policy for this zone. This is a string
- referring to a dnssec-policy statement.
+ Specifies which key and signing policy (KASP) should
+ be used for this zone. This is a string referring to
+ a dnssec-policy statement.
There are two built-in policies:
- "default" allows you to use the
- default policy, and "none" means
+ default allows you to use the
+ default policy, and none means
not to use any DNSSEC policy, keeping the zone unsigned.
- The default is "none".
+ The default is none.
+ See for
+ more details.
diff --git a/doc/misc/dnssec-policy.default.conf b/doc/misc/dnssec-policy.default.conf
index 1e12aec43e..5baa8b1d0a 100644
--- a/doc/misc/dnssec-policy.default.conf
+++ b/doc/misc/dnssec-policy.default.conf
@@ -1,5 +1,4 @@
dnssec-policy "default" {
-
// Keys
keys {
csk key-directory lifetime unlimited algorithm 13;
@@ -14,7 +13,7 @@ dnssec-policy "default" {
signatures-refresh 5d;
signatures-validity 14d;
signatures-validity-dnskey 14d;
-
+
// Zone parameters
max-zone-ttl 86400;
zone-propagation-delay 300;