From e6b335c2ab6ae106718c18595afbe5945b1cc905 Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Thu, 10 Sep 2020 11:38:07 +0200 Subject: [PATCH 1/4] Remove leftover 'dnssec-keys' references The option 'dnssec-keys' was introduced in 9.15 and also renamed to 'trust-anchors'. Rename the leftover references to 'trust-anchors'. --- doc/arm/managed-keys.rst | 2 +- doc/arm/reference.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/arm/managed-keys.rst b/doc/arm/managed-keys.rst index cf0f1867f0..ac6424c689 100644 --- a/doc/arm/managed-keys.rst +++ b/doc/arm/managed-keys.rst @@ -22,7 +22,7 @@ Validating Resolver ~~~~~~~~~~~~~~~~~~~ To configure a validating resolver to use :rfc:`5011` to maintain a trust -anchor, configure the trust anchor using a ``dnssec-keys`` statement and +anchor, configure the trust anchor using a ``trust-anchors`` statement and the ``initial-key`` keyword. Information about this can be found in :ref:`trust-anchors`. diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 093abd607f..1b357120eb 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -1885,7 +1885,7 @@ Boolean Options ``trust-anchor-telemetry`` This causes ``named`` to send specially formed queries once per day to domains for which trust anchors have been configured via, e.g., - ``dnssec-keys`` or ``dnssec-validation auto``. + ``trust-anchors`` or ``dnssec-validation auto``. The query name used for these queries has the form ``_ta-xxxx(-xxxx)(...).``, where each "xxxx" is a group of four @@ -4654,7 +4654,7 @@ not used to validate answers; it is superseded by the key or keys stored in the managed-keys database. The next time ``named`` runs after an ``initial-key`` or ``initial-ds`` has been *removed* -from the ``dnssec-keys`` statement (or changed to a ``static-key`` or ``static-ds``), the +from the ``trust-anchors`` statement (or changed to a ``static-key`` or ``static-ds``), the corresponding zone is removed from the managed-keys database, and :rfc:`5011` key maintenance is no longer used for that domain. From 3a3ace0f412459c903190e08cad49e2cd5fff81c Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Thu, 10 Sep 2020 12:37:29 +0200 Subject: [PATCH 2/4] Add a note on DNSSEC sign metrics in the ARM This was added previously in commit 3a3f40e3729e1e3ab32f6c18eeecfd4749812ffb but was lost when the documentation was converted to RST files. --- doc/arm/reference.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 1b357120eb..fd76854f06 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -1533,8 +1533,10 @@ default is used. If ``full``, the server collects statistical data on all zones, unless specifically turned off on a per-zone basis by specifying ``zone-statistics terse`` or ``zone-statistics none`` in the ``zone`` - statement. The default is ``terse``, providing minimal statistics on - zones (including name and current serial number, but not query type + statement. These include, for example, DNSSEC signing operations + and the number of authoritative answers per query type. The + default is ``terse``, providing minimal statistics on zones + (including name and current serial number, but not query type counters). These statistics may be accessed via the ``statistics-channel`` or From 0b0320360fc652766739259f938a4bd6248ce676 Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Thu, 10 Sep 2020 13:48:04 +0200 Subject: [PATCH 3/4] Update DNSSEC documentation This was originally done in commit da0ae5299f51c0ffdd4edc3b880d105a64590cf6 but was lost when the documentation was converted to RST files. --- doc/arm/dnssec.rst | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/doc/arm/dnssec.rst b/doc/arm/dnssec.rst index 2fa816f4dd..4851cccbbd 100644 --- a/doc/arm/dnssec.rst +++ b/doc/arm/dnssec.rst @@ -16,13 +16,15 @@ DNSSEC, Dynamic Zones, and Automatic Signing Converting From Insecure to Secure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A zone can be changed from insecure to secure in two ways: using a -dynamic DNS update, or via the ``auto-dnssec`` zone option. +A zone can be changed from insecure to secure in three ways: using a +dynamic DNS update, or via the ``auto-dnssec`` zone option, or set a +DNSSEC policy for the zone with ``dnssec-policy``. For either method, ``named`` must be configured so that it can see the ``K*`` files which contain the public and private parts of the keys that are used to sign the zone. These files are generated -by ``dnssec-keygen``, and they should be placed in the +by ``dnssec-keygen`` (or created when needed by ``named`` if +``dnssec-policy`` is used). Keys should be placed in the key-directory, as specified in ``named.conf``: :: @@ -39,6 +41,18 @@ configuration causes all records in the zone to be signed with the ZSK, and the DNSKEY RRset to be signed with the KSK. An NSEC chain is generated as part of the initial signing process. +With ``dnssec-policy you specify what keys should be KSK and/or ZSK. +If you want a key to sign all records with a key you will need to +specify a CSK. For example: + +:: + + dnssec-policy csk { + keys { + csk lifetime unlimited algorithm 13; + }; + }; + Dynamic DNS Update Method ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -83,9 +97,9 @@ other updates are possible as well. Fully Automatic Zone Signing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable automatic signing, add the ``auto-dnssec`` option to the zone -statement in ``named.conf``. ``auto-dnssec`` has two possible arguments: -``allow`` or ``maintain``. +To enable automatic signing, you can set a ``dnssec-policy``, or add the +``auto-dnssec`` option to the zone statement in ``named.conf``. +``auto-dnssec`` has two possible arguments: ``allow`` or ``maintain``. With ``auto-dnssec allow``, ``named`` can search the key directory for keys matching the zone, insert them into the zone, and use them to sign @@ -97,6 +111,11 @@ automatically adjusts the zone's DNSKEY records on a schedule according to the keys' timing metadata. (See :ref:`man_dnssec-keygen` and :ref:`man_dnssec-settime` for more information.) +``dnssec-policy`` is like ``auto-dnssec maintain``, but will also automatically +create new keys when necessary. Also any configuration related to DNSSEC +signing is retrieved from the policy (ignoring existing DNSSEC ``named.conf`` +options). + ``named`` periodically searches the key directory for keys matching the zone; if the keys' metadata indicates that any change should be made to the zone - such as adding, removing, or revoking a key - then that @@ -224,6 +243,8 @@ conversion is complete, the NSEC chain is removed and the NSEC3PARAM record has a zero flag field. The NSEC3 chain is generated before the NSEC chain is destroyed. +NSEC3 is not supported yet with ``dnssec-policy``. + Converting From NSEC3 to NSEC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 49e76c15dd54c2710fe179e2821d9acbf45ba5be Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Mon, 21 Sep 2020 11:03:30 +0200 Subject: [PATCH 4/4] Improve language in documentation Various language specific improvements, from Suzanne Goldlust's review. --- doc/arm/dnssec.rst | 26 +++++++++++++------------- doc/arm/reference.rst | 4 ++-- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/arm/dnssec.rst b/doc/arm/dnssec.rst index 4851cccbbd..5e3119707e 100644 --- a/doc/arm/dnssec.rst +++ b/doc/arm/dnssec.rst @@ -17,14 +17,14 @@ Converting From Insecure to Secure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A zone can be changed from insecure to secure in three ways: using a -dynamic DNS update, or via the ``auto-dnssec`` zone option, or set a +dynamic DNS update, via the ``auto-dnssec`` zone option, or by setting a DNSSEC policy for the zone with ``dnssec-policy``. -For either method, ``named`` must be configured so that it can see +For any method, ``named`` must be configured so that it can see the ``K*`` files which contain the public and private parts of the keys that are used to sign the zone. These files are generated -by ``dnssec-keygen`` (or created when needed by ``named`` if -``dnssec-policy`` is used). Keys should be placed in the +by ``dnssec-keygen``, or created when needed by ``named`` if +``dnssec-policy`` is used. Keys should be placed in the key-directory, as specified in ``named.conf``: :: @@ -41,9 +41,9 @@ configuration causes all records in the zone to be signed with the ZSK, and the DNSKEY RRset to be signed with the KSK. An NSEC chain is generated as part of the initial signing process. -With ``dnssec-policy you specify what keys should be KSK and/or ZSK. -If you want a key to sign all records with a key you will need to -specify a CSK. For example: +With ``dnssec-policy``, it is possible to specify which keys should be +KSK and/or ZSK. To sign all records with a key, a CSK must be specified. +For example: :: @@ -97,7 +97,7 @@ other updates are possible as well. Fully Automatic Zone Signing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable automatic signing, you can set a ``dnssec-policy``, or add the +To enable automatic signing, set a ``dnssec-policy`` or add the ``auto-dnssec`` option to the zone statement in ``named.conf``. ``auto-dnssec`` has two possible arguments: ``allow`` or ``maintain``. @@ -111,10 +111,10 @@ automatically adjusts the zone's DNSKEY records on a schedule according to the keys' timing metadata. (See :ref:`man_dnssec-keygen` and :ref:`man_dnssec-settime` for more information.) -``dnssec-policy`` is like ``auto-dnssec maintain``, but will also automatically -create new keys when necessary. Also any configuration related to DNSSEC -signing is retrieved from the policy (ignoring existing DNSSEC ``named.conf`` -options). +``dnssec-policy`` is similar to ``auto-dnssec maintain``, but +``dnssec-policy`` also automatically creates new keys when necessary. In +addition, any configuration related to DNSSEC signing is retrieved from the +policy, ignoring existing DNSSEC ``named.conf`` options. ``named`` periodically searches the key directory for keys matching the zone; if the keys' metadata indicates that any change should be @@ -243,7 +243,7 @@ conversion is complete, the NSEC chain is removed and the NSEC3PARAM record has a zero flag field. The NSEC3 chain is generated before the NSEC chain is destroyed. -NSEC3 is not supported yet with ``dnssec-policy``. +NSEC3 is not yet supported with ``dnssec-policy``. Converting From NSEC3 to NSEC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index fd76854f06..f9bb269d3d 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -1533,8 +1533,8 @@ default is used. If ``full``, the server collects statistical data on all zones, unless specifically turned off on a per-zone basis by specifying ``zone-statistics terse`` or ``zone-statistics none`` in the ``zone`` - statement. These include, for example, DNSSEC signing operations - and the number of authoritative answers per query type. The + statement. The statistical data includes, for example, DNSSEC signing + operations and the number of authoritative answers per query type. The default is ``terse``, providing minimal statistics on zones (including name and current serial number, but not query type counters).