From c7866acbf7805763f74c960bb1ba04a3581a9451 Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Fri, 7 Feb 2020 23:41:18 -0800 Subject: [PATCH] revise dnssec-policy documentation --- doc/arm/Bv9ARM-book.xml | 227 +++++++++++++++++++--------- doc/misc/dnssec-policy.default.conf | 3 +- 2 files changed, 154 insertions(+), 76 deletions(-) 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. -
<command>dnssec-policy</command> Statement Definition - and Usage +
<command>dnssec-policy</command> 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;