mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-09-01 15:05:23 +00:00
Code Issues Releases Wiki Activity

Fix formatting of "dnssec-policy" documentation

Browse Source
This commit is contained in:
Michał Kępień
2020-12-04 11:07:22 +01:00
parent ae05e5b691
commit 2ecff5dc43
1 changed files with 146 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files

327
doc/arm/reference.rst
View File

@@ -4764,235 +4764,200 @@ can be found, the initializing key is also compiled directly into
.. _dnssec_policy_grammar: .. _dnssec_policy_grammar:
``dnssec-policy`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: ../misc/dnssec-policy.grammar.rst .. include:: ../misc/dnssec-policy.grammar.rst
.. _dnssec_policy: .. _dnssec_policy:
The ``dnssec-policy`` statement defines a key and ``dnssec-policy`` Statement Definition and Usage
signing policy (KASP) for zones. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A KASP determines how one or more zones are signed The ``dnssec-policy`` statement defines a key and signing policy (KASP)
with DNSSEC. For example, it specifies how often keys should for zones.
roll, which cryptographic algorithms to use, and how often RRSIG
records need to be refreshed.
Keys are not shared among zones, which means that one set of keys A KASP determines how one or more zones are signed with DNSSEC. For
per zone is generated even if they have the same policy. example, it specifies how often keys should roll, which cryptographic
If multiple views are configured with different versions of the algorithms to use, and how often RRSIG records need to be refreshed.
same zone, each separate version uses the same set of signing
keys.
Multiple key and signing policies can be configured. To Keys are not shared among zones, which means that one set of keys per
attach a policy to a zone, add a ``dnssec-policy`` zone is generated even if they have the same policy. If multiple views
option to the ``zone`` statement, specifying the are configured with different versions of the same zone, each separate
name of the policy that should be used. version uses the same set of signing keys.
Key rollover timing is computed for each key according to Multiple key and signing policies can be configured. To attach a policy
the key lifetime defined in the KASP. The lifetime may be to a zone, add a ``dnssec-policy`` option to the ``zone`` statement,
modified by zone TTLs and propagation delays, to specifying the name of the policy that should be used.
prevent validation failures. When a key reaches the end of its
lifetime,
``named`` generates and publishes a new key
automatically, then deactivates the old key and activates the
new one; finally, the old key is retired according to a computed
schedule.
Zone-signing key (ZSK) rollovers require no operator input. Key rollover timing is computed for each key according to the key
Key-signing key (KSK) and combined-signing key (CSK) rollovers lifetime defined in the KASP. The lifetime may be modified by zone TTLs
require action to be taken to submit a DS record to the parent. and propagation delays, to prevent validation failures. When a key
Rollover timing for KSKs and CSKs is adjusted to take into account reaches the end of its lifetime, ``named`` generates and publishes a new
delays in processing and propagating DS updates. key automatically, then deactivates the old key and activates the new
one; finally, the old key is retired according to a computed schedule.
There are two predefined ``dnssec-policy`` names: Zone-signing key (ZSK) rollovers require no operator input. Key-signing
``none`` and ``default``. key (KSK) and combined-signing key (CSK) rollovers require action to be
Setting a zone's policy to taken to submit a DS record to the parent. Rollover timing for KSKs and
``none`` is the same as not setting CSKs is adjusted to take into account delays in processing and
``dnssec-policy`` at all; the zone is not propagating DS updates.
signed. Policy ``default`` causes the
zone to be signed with a single combined-signing key (CSK)
using algorithm ECDSAP256SHA256; this key has 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``.)
.. note:: 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 is not signed. Policy
``default`` causes the zone to be signed with a single combined-signing
key (CSK) using algorithm ECDSAP256SHA256; this key has 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. .. note:: The default signing policy may change in future releases.
This could require changes to a signing policy This could require changes to a signing policy when upgrading to a
when upgrading to a new version of BIND. Check new version of BIND. Check the release notes carefully when
the release notes carefully when upgrading to be informed upgrading to be informed of such changes. To prevent policy changes
of such changes. To prevent policy changes on upgrade, on upgrade, use an explicitly defined ``dnssec-policy``, rather than
use an explicitly defined ``dnssec-policy``, ``default``.
rather than ``default``.
If a ``dnssec-policy`` statement is modified If a ``dnssec-policy`` statement is modified and the server restarted or
and the server restarted or reconfigured, ``named`` reconfigured, ``named`` attempts to change the policy smoothly from the
attempts to change the policy smoothly from the old one to old one to the new. For example, if the key algorithm is changed, then
the new. For example, if the key algorithm is changed, then a new key is generated with the new algorithm, and the old algorithm is
a new key is generated with the new algorithm, and the old retired when the existing key's lifetime ends.
algorithm is retired when the existing key's lifetime ends.
.. note:: .. note:: Rolling to a new policy while another key rollover is already
in progress is not yet supported, and may result in unexpected
Rolling to a new policy while another key rollover is behavior.
already in progress is not yet supported, and may result in
unexpected behavior.
The following options can be specified in a ``dnssec-policy`` statement: The following options can be specified in a ``dnssec-policy`` statement:
``dnskey-ttl`` ``dnskey-ttl``
This indicates the TTL to use when generating DNSKEY resource records. The default is 1 This indicates the TTL to use when generating DNSKEY resource
hour (3600 seconds). records. The default is 1 hour (3600 seconds).
``keys`` ``keys``
This is a list specifying the algorithms and roles to use when This is a list specifying the algorithms and roles to use when
generating keys and signing the zone. generating keys and signing the zone. Entries in this list do not
Entries in this list do not represent specific represent specific DNSSEC keys, which may be changed on a regular
DNSSEC keys, which may be changed on a regular basis, basis, but the roles that keys play in the signing policy. For
but the roles that keys play in the signing policy. example, configuring a KSK of algorithm RSASHA256 ensures that the
For example, configuring a KSK of algorithm RSASHA256 ensures DNSKEY RRset always includes a key-signing key for that algorithm.
that the DNSKEY RRset always includes a key-signing key
for that algorithm.
Here is an example (for illustration purposes only) of Here is an example (for illustration purposes only) of some possible
some possible entries in a ``keys`` entries in a ``keys`` list:
list:
:: ::
keys { keys {
ksk key-directory lifetime unlimited algorithm rsasha1 2048; ksk key-directory lifetime unlimited algorithm rsasha1 2048;
zsk lifetime P30D algorithm 8; zsk lifetime P30D algorithm 8;
csk lifetime P6MT12H3M15S algorithm ecdsa256; csk lifetime P6MT12H3M15S algorithm ecdsa256;
}; };
This example specifies that three keys should be used This example specifies that three keys should be used in the zone.
in the zone. The first token determines which role the The first token determines which role the key plays in signing
key plays in signing RRsets. If set to RRsets. If set to ``ksk``, then this is a key-signing key; it has
``ksk``, then this is the KSK flag set and is only used to sign DNSKEY, CDS, and CDNSKEY
a key-signing key; it has the KSK flag set and RRsets. If set to ``zsk``, this is a zone-signing key; the KSK flag
is only used to sign DNSKEY, CDS, and CDNSKEY RRsets. is unset, and the key signs all RRsets *except* DNSKEY, CDS, and
If set to ``zsk``, this is CDNSKEY. If set to ``csk``, the key has the KSK flag set and is
a zone-signing key; the KSK flag is unset, and used to sign all RRsets.
the key signs all RRsets *except*
DNSKEY, CDS, and CDNSKEY. If set to
``csk``, the key has the KSK
flag set and is used to sign all RRsets.
An optional second token determines where the key is An optional second token determines where the key is stored.
stored. Currently, keys can only be stored in the Currently, keys can only be stored in the configured
configured ``key-directory``. This token ``key-directory``. This token may be used in the future to store
may be used in the future to store keys in hardware keys in hardware service modules or separate directories.
service modules or separate directories.
The ``lifetime`` parameter specifies how The ``lifetime`` parameter specifies how long a key may be used
long a key may be used before rolling over. In the before rolling over. In the example above, the first key has an
example above, the first key has an unlimited unlimited lifetime, the second key may be used for 30 days, and the
lifetime, the second key may be used for 30 days, and the third key has a rather peculiar lifetime of 6 months, 12 hours, 3
third key has a rather peculiar lifetime of 6 months, minutes, and 15 seconds. A lifetime of 0 seconds is the same as
12 hours, 3 minutes, and 15 seconds. A lifetime of 0 ``unlimited``.
seconds is the same as ``unlimited``.
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
retiring it too soon would cause validation failures. soon would cause validation failures. For example, if the key were
For example, if the key were configured to roll more configured to roll more frequently than its own TTL, its lifetime
frequently than its own TTL, its lifetime would would automatically be extended to account for this.
automatically be extended to account for this.
The ``algorithm`` parameter specifies The ``algorithm`` parameter specifies the key's algorithm, expressed
the key's algorithm, expressed either as a string either as a string ("rsasha256", "ecdsa384", etc.) or as a decimal
("rsasha256", "ecdsa384", etc.) or as a decimal number. number. An optional second parameter specifies the key's size in
An optional second parameter specifies the key's size bits. If it is omitted, as shown in the example for the second and
in bits. If it is omitted, as shown in the third keys, an appropriate default size for the algorithm is used.
example for the second and third keys, an appropriate
default size for the algorithm is used.
``publish-safety`` ``publish-safety``
This is a margin that is added to the pre-publication This is a margin that is added to the pre-publication interval in
interval in rollover timing calculations, to give some rollover timing calculations, to give some extra time to cover
extra time to cover unforeseen events. This increases unforeseen events. This increases the time between when keys are
the time between when keys are published and when they become active. published and when they become active. The default is ``PT1H`` (1
The default is ``PT1H`` (1 hour). hour).
``retire-safety`` ``retire-safety``
This is a margin that is added to the post-publication interval This is a margin that is added to the post-publication interval in
in rollover timing calculations, to give some extra time rollover timing calculations, to give some extra time to cover
to cover unforeseen events. This increases the time a key unforeseen events. This increases the time a key remains published
remains published after it is no longer active. The after it is no longer active. The default is ``PT1H`` (1 hour).
default is ``PT1H`` (1 hour).
``signatures-refresh`` ``signatures-refresh``
This determines how frequently an RRSIG record needs to be This determines how frequently an RRSIG record needs to be
refreshed. The signature is renewed when the time until refreshed. The signature is renewed when the time until the
the expiration time is less than the specified interval. expiration time is less than the specified interval. The default is
The default is ``P5D`` (5 days), meaning ``P5D`` (5 days), meaning signatures that expire in 5 days or sooner
signatures that expire in 5 days or sooner are are refreshed.
refreshed.
``signatures-validity`` ``signatures-validity``
This indicates the validity period of an RRSIG record (subject to This indicates the validity period of an RRSIG record (subject to
inception offset and jitter). The default is inception offset and jitter). The default is ``P2W`` (2 weeks).
``P2W`` (2 weeks).
``signatures-validity-dnskey`` ``signatures-validity-dnskey``
This is similar to ``signatures-validity``, but for This is similar to ``signatures-validity``, but for DNSKEY records.
DNSKEY records. The default is ``P2W`` The default is ``P2W`` (2 weeks).
(2 weeks).
``max-zone-ttl`` ``max-zone-ttl``
Like the ``max-zone-ttl`` zone option, Like the ``max-zone-ttl`` zone option, this specifies the maximum
this specifies the maximum permissible TTL value, in permissible TTL value, in seconds, for the zone. When loading a
seconds, for the zone. When loading a zone file using zone file using a ``masterfile-format`` of ``text`` or ``raw``, any
a ``masterfile-format`` of record encountered with a TTL higher than ``max-zone-ttl`` is capped
``text`` or ``raw``, at the maximum permissible TTL value.
any record encountered with a TTL higher than
``max-zone-ttl`` is capped at the
maximum permissible TTL value.
This is needed in DNSSEC-maintained zones because when This is needed in DNSSEC-maintained zones because when rolling to a
rolling to a new DNSKEY, the old key needs to remain new DNSKEY, the old key needs to remain available until RRSIG
available until RRSIG records have expired from caches. records have expired from caches. The ``max-zone-ttl`` option
The ``max-zone-ttl`` option guarantees that guarantees that the largest TTL in the zone is no higher than the
the largest TTL in the zone is no higher than the set value.
set value.
.. note:: .. note:: Because ``map``-format files load directly into memory,
Because ``map``-format files this option cannot be used with them.
load directly into memory, this option cannot be
used with them.
The default value is ``PT24H`` (24 hours). The default value is ``PT24H`` (24 hours). A ``max-zone-ttl`` of
A ``max-zone-ttl`` of zero is treated as if zero is treated as if the default value were in use.
the default value were in use.
``nsec3param`` ``nsec3param``
Use NSEC3 instead of NSEC, and optionally set the NSEC3 parameters. Use NSEC3 instead of NSEC, and optionally set the NSEC3 parameters.
Here is an example of an ``nsec3`` configuration: Here is an example of an ``nsec3`` configuration:
:: ::
nsec3param iterations 5 optout no salt-length 8; nsec3param iterations 5 optout no salt-length 8;
The default is to use NSEC. The ``iterations``, ``optout`` The default is to use NSEC. The ``iterations``, ``optout`` and
and ``salt-length`` parts are optional, but if not set, the ``salt-length`` parts are optional, but if not set, the values in
values in the example above are the default NSEC3 parameters. the example above are the default NSEC3 parameters.
``zone-propagation-delay`` ``zone-propagation-delay``
This is the expected propagation delay from the time when a zone This is the expected propagation delay from the time when a zone is
is first updated to the time when the new version of the first updated to the time when the new version of the zone is served
zone is served by all secondary servers. The default by all secondary servers. The default is ``PT5M`` (5 minutes).
is ``PT5M`` (5 minutes).
``parent-ds-ttl`` ``parent-ds-ttl``
This is the TTL of the DS RRset that the parent zone uses. The This is the TTL of the DS RRset that the parent zone uses. The
default is ``P1D`` (1 day). default is ``P1D`` (1 day).
``parent-propagation-delay`` ``parent-propagation-delay``
This is the expected propagation delay from the time when the This is the expected propagation delay from the time when the parent
parent zone is updated to the time when the new version zone is updated to the time when the new version is served by all of
is served by all of the parent zone's name servers. the parent zone's name servers. The default is ``PT1H`` (1 hour).
The default is ``PT1H`` (1 hour).
.. _managed-keys: .. _managed-keys: