From: Petr Špaček Date: Wed, 8 Jun 2022 16:05:56 +0000 (+0200) Subject: Reorder chapters about Zone Signing in the DNSSEC chapter of ARM X-Git-Tag: v9.19.3~30^2~11 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=28a533322b25b018a86dc986a6de05db8ae39841;p=thirdparty%2Fbind9.git Reorder chapters about Zone Signing in the DNSSEC chapter of ARM Let's make more automated methods more prominent: - KASP first - dynamic updates second - command-line tools only as last resort --- diff --git a/doc/arm/dnssec.inc.rst b/doc/arm/dnssec.inc.rst index 44ba51a6867..a7110b302e9 100644 --- a/doc/arm/dnssec.inc.rst +++ b/doc/arm/dnssec.inc.rst @@ -106,6 +106,14 @@ that are about to expire and managing :ref:`key_rollovers`. **TODO:** The original zone file :file:`dnssec.example.db` remains untouched and the signed version of the zone is stored on disk in :file:`dnssec.example.db.signed`. +When setting a ``dnssec-policy`` for a zone, it typically creates a new file +with a ``.signed`` extension on disk, while the original zone file stays +untouched. This is called inline signing. + +DNSSEC configuration works slightly differently for dynamic zones. DNSSEC-related +records are applied directly to zones with an update ACL or update +policy, similarly to non-DNSSEC records, instead of storing them in a file with a +``.signed`` extension. The default policy creates one key that is used to sign the complete zone, and uses ``NSEC`` to enable authenticated denial of existence (a secure way @@ -148,83 +156,21 @@ For more information about KASP configuration see :ref:`dnssec_policy_grammar`. The :ref:`dnssec_advanced_discussions` in the DNSSEC Guide discusses the various policy settings and may help you determining values for your special needs. -.. _dnssec_tools: - -DNSSEC Tools -^^^^^^^^^^^^ - -There are several tools available if you want to sign your zone manually. - -.. warning:: - - Please note manual procedures are available mainly for backwards - compatibility and should be used only by expert users with specific needs. - -The :iscman:`dnssec-keygen` program is used to generate keys. - -The following command generates an ECDSAP256SHA256 key for the -``child.example`` zone: - -``dnssec-keygen -a ECDSAP256SHA256 -n ZONE child.example.`` - -Two output files are produced: ``Kchild.example.+013+12345.key`` and -``Kchild.example.+013+12345.private`` (where 12345 is an example of a -key tag). The key filenames contain the key name (``child.example.``), -the algorithm (5 is RSASHA1, 8 is RSASHA256, 13 is ECDSAP256SHA256, 15 is -ED25519, etc.), and the key tag (12345 in this case). The private key (in -the ``.private`` file) is used to generate signatures, and the public -key (in the ``.key`` file) is used for signature verification. - -To generate another key with the same properties but with a different -key tag, repeat the above command. - -The :iscman:`dnssec-keyfromlabel` program is used to get a key pair from a -crypto hardware device and build the key files. Its usage is similar to -:iscman:`dnssec-keygen`. - -The public keys should be inserted into the zone file by including the -``.key`` files using ``$INCLUDE`` statements. - -The :iscman:`dnssec-signzone` program is used to sign a zone. - -Any ``keyset`` files corresponding to secure sub-zones should be -present. The zone signer generates ``NSEC``, ``NSEC3``, and ``RRSIG`` -records for the zone, as well as ``DS`` for the child zones if -:option:`-g ` is specified. If -:option:`-g ` is not specified, then DS RRsets for the -secure child zones need to be added manually. - -By default, all zone keys which have an available private key are used -to generate signatures. The following command signs the zone, assuming -it is in a file called ``zone.child.example``: - -``dnssec-signzone -o child.example zone.child.example`` - -One output file is produced: ``zone.child.example.signed``. This file -should be referenced by :iscman:`named.conf` as the input file for the zone. - -:iscman:`dnssec-signzone` also produces keyset and dsset files. These are used -to provide the parent zone administrators with the ``DNSKEYs`` (or their -corresponding ``DS`` records) that are the secure entry point to the zone. - .. _dnssec_dynamic_zones: -Dynamic Zones -~~~~~~~~~~~~~ +Manual Key Management +^^^^^^^^^^^^^^^^^^^^^ -When setting a ``dnssec-policy`` for a zone, it typically creates a new file -with a ``.signed`` extension on disk, while the original zone file stays -untouched. This is called inline signing. +.. warning:: + The method described here allows full control over the keys used to sign + the zone. This is required only for very special cases and is generally + discouraged. Under normal circumstances, please use :ref:`dnssec_kasp`. -This works a bit different for dynamic zones. Zones with an update ACL or update -policy will have the DNSSEC related records applied directly to the zone, -similar to the non-DNSSEC records, instead of storing them in a file with -``.signed`` extension. .. _dnssec_dynamic_zones_multisigner_model: Multi-Signer Model -^^^^^^^^^^^^^^^^^^ +================== Dynamic zones provide the ability to sign a zone by multiple providers, meaning each provider signs and serves the same zone independently. Such a setup requires @@ -246,7 +192,7 @@ various DNSSEC operations. .. _dnssec_dynamic_zones_enabling_dnssec: Enabling DNSSEC Manually -^^^^^^^^^^^^^^^^^^^^^^^^ +======================== As an alternative to fully automated zone signing using :ref:`dnssec-policy `, a zone can be changed from insecure to secure using a dynamic DNS update. :iscman:`named` must be configured so that it can see the ``K*`` @@ -276,7 +222,7 @@ than all at once. .. _dnssec_dynamic_zones_publishing_dnskey_records: Publishing DNSKEY Records -^^^^^^^^^^^^^^^^^^^^^^^^^ +========================= To insert the keys via dynamic update: @@ -294,7 +240,7 @@ placed in the ``key-directory``. .. _dnssec_dynamic_zones_nsec3: NSEC3 -^^^^^ +===== To sign using :ref:`NSEC3 ` instead of :ref:`NSEC `, add an NSEC3PARAM record to the initial update @@ -340,7 +286,7 @@ records. The ``NSEC`` chain is generated before the ``NSEC3`` chain is removed. .. _dnssec_dynamic_zones_private_type_records: Private Type Records -^^^^^^^^^^^^^^^^^^^^ +==================== The state of the signing process is signaled by private type records (with a default type value of 65534). When signing is complete, those records with a @@ -379,7 +325,7 @@ based on the flag bits: .. _dnssec_dynamic_zones_dnskey_rollovers: DNSKEY Rollovers -^^^^^^^^^^^^^^^^ +================ To perform key rollovers via a dynamic update, the ``K*`` files for the new keys must be added so that :iscman:`named` can find them. The new ``DNSKEY`` RRs can @@ -402,7 +348,7 @@ key after the update completes. .. _dnssec_dynamic_zones_going_insecure: Going Insecure -^^^^^^^^^^^^^^ +============== To convert a signed zone to unsigned using dynamic DNS, delete all the ``DNSKEY`` records from the zone apex using :iscman:`nsupdate`. All signatures, @@ -415,6 +361,72 @@ This requires the ``dnssec-secure-to-insecure`` option to be set to ``yes`` in In addition, if the ``auto-dnssec maintain`` or a ``dnssec-policy`` is used, it should be removed or changed to ``allow`` instead; otherwise it will re-sign. +.. _dnssec_tools: + +Manual Signing +^^^^^^^^^^^^^^ + +There are several tools available to manually sign a zone. + +.. warning:: + + Please note manual procedures are available mainly for backwards + compatibility and should be used only by expert users with specific needs. + +To set up a DNSSEC secure zone manually, a series of steps +must be followed. BIND 9 ships with several tools that are used in +this process, which are explained in more detail below. In all cases, +the ``-h`` option prints a full list of parameters. Note that the DNSSEC +tools require the keyset files to be in the working directory or the +directory specified by the ``-d`` option. + +The :iscman:`dnssec-keygen` program is used to generate keys. + +The following command generates an ECDSAP256SHA256 key for the +``child.example`` zone: + +``dnssec-keygen -a ECDSAP256SHA256 -n ZONE child.example.`` + +Two output files are produced: ``Kchild.example.+013+12345.key`` and +``Kchild.example.+013+12345.private`` (where 12345 is an example of a +key tag). The key filenames contain the key name (``child.example.``), +the algorithm (5 is RSASHA1, 8 is RSASHA256, 13 is ECDSAP256SHA256, 15 is +ED25519, etc.), and the key tag (12345 in this case). The private key (in +the ``.private`` file) is used to generate signatures, and the public +key (in the ``.key`` file) is used for signature verification. + +To generate another key with the same properties but with a different +key tag, repeat the above command. + +The :iscman:`dnssec-keyfromlabel` program is used to get a key pair from a +crypto hardware device and build the key files. Its usage is similar to +:iscman:`dnssec-keygen`. + +The public keys should be inserted into the zone file by including the +``.key`` files using ``$INCLUDE`` statements. + +The :iscman:`dnssec-signzone` program is used to sign a zone. + +Any ``keyset`` files corresponding to secure sub-zones should be +present. The zone signer generates ``NSEC``, ``NSEC3``, and ``RRSIG`` +records for the zone, as well as ``DS`` for the child zones if +:option:`-g ` is specified. If +:option:`-g ` is not specified, then DS RRsets for the +secure child zones need to be added manually. + +By default, all zone keys which have an available private key are used +to generate signatures. The following command signs the zone, assuming +it is in a file called ``zone.child.example``: + +``dnssec-signzone -o child.example zone.child.example`` + +One output file is produced: ``zone.child.example.signed``. This file +should be referenced by :iscman:`named.conf` as the input file for the zone. + +:iscman:`dnssec-signzone` also produces keyset and dsset files. These are used +to provide the parent zone administrators with the ``DNSKEYs`` (or their +corresponding ``DS`` records) that are the secure entry point to the zone. + DNSSEC Validation ~~~~~~~~~~~~~~~~~