From: Petr Špaček <pspacek@isc.org>
Date: Thu, 16 Jun 2022 12:03:45 +0000 (+0200)
Subject: Deduplicate Manual Signing between DNSSEC chapter and DNSSEC Guide
X-Git-Tag: v9.16.31~3^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4caaff0afa5b1912ae90fb937fd5f9d7612e580b;p=thirdparty%2Fbind9.git

Deduplicate Manual Signing between DNSSEC chapter and DNSSEC Guide

The two procedures were essentially the same, but each instance was
missing some details from the other. They are now combined into one text
in the DNSSEC Guide and linked from DNSSEC chapter.

(cherry picked from commit 7d2502789891e69c2475140d4d14370401759594)
---

diff --git a/doc/dnssec-guide/signing.rst b/doc/dnssec-guide/signing.rst
index 534b35e857e..17eee3ab4b2 100644
--- a/doc/dnssec-guide/signing.rst
+++ b/doc/dnssec-guide/signing.rst
@@ -1153,6 +1153,10 @@ about the contents. See chapter :ref:`zone_keys` for more details.
 Make sure that these files are readable by ``named`` and that the
 ``.private`` files are not readable by anyone else.
 
+Alternativelly, the ``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 ``dnssec-keygen``.
+
 Setting Key Timing Information
 ++++++++++++++++++++++++++++++
 
@@ -1544,12 +1548,31 @@ including interaction with the parent. A user certainly can do all this,
 but why not use one of the automated methods? Nevertheless, it may
 be useful for test purposes, so we cover it briefly here.
 
+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 first step is to create the keys as described in :ref:`generate_keys`.
-Then, edit the zone file to make sure
-the proper DNSKEY entries are included in your zone file. Finally, use the
-command ``dnssec-signzone``:
 
-::
+Then, edit the zone file to make sure the proper DNSKEY entries are included.
+The public keys should be inserted into the zone file by
+including the ``.key`` files using ``$INCLUDE`` statements.
+
+Finally, use the command ``dnssec-signzone``.
+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
+``-g`` is specified. If
+``-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``, using manually specified keys:
+
+.. code-block:: console
 
    # cd /etc/bind/keys/example.com/
    # dnssec-signzone -A -t -N INCREMENT -o example.com -f /etc/bind/db/example.com.signed.db \
@@ -1573,12 +1596,16 @@ this case), while the -f switch specifies the output file name. The second line
 has three parameters: the unsigned zone name
 (``/etc/bind/db/example.com.db``), the ZSK file name, and the KSK file name. This
 also generates a plain text file ``/etc/bind/db/example.com.signed.db``,
-which you can verify for correctness.
+which can be manually verified for correctness.
+
+``dnssec-signzone`` also produces keyset and dsset files. These are used
+to provide the parent zone administrators with the ``DNSKEY`` records (or their
+corresponding ``DS`` records) that are the secure entry point to the zone.
 
-Finally, ``named.conf`` needs to be updated to load the signed version
+Finally, you'll need to update ``named.conf`` to load the signed version
 of the zone, which looks something like this:
 
-::
+.. code-block:: none
 
    zone "example.com" IN {
        type primary;