Adding upstream version 1:9.18.19.upstream/1%9.18.19upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 221 insertions, 0 deletions

diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst
new file mode 100644
index 0000000..09960e9
--- /dev/null
+++ b/bin/dnssec/dnssec-cds.rst
@@ -0,0 +1,221 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0.  If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. highlight: console
+
+.. iscman:: dnssec-cds
+.. program:: dnssec-cds
+.. _man_dnssec-cds:
+
+dnssec-cds - change DS records for a child zone based on CDS/CDNSKEY
+--------------------------------------------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`dnssec-cds` [**-a** alg...] [**-c** class] [**-D**] {**-d** dsset-file} {**-f** child-file} [**-i**[extension]] [**-s** start-time] [**-T** ttl] [**-u**] [**-v** level] [**-V**] {domain}
+
+Description
+~~~~~~~~~~~
+
+The :program:`dnssec-cds` command changes DS records at a delegation point
+based on CDS or CDNSKEY records published in the child zone. If both CDS
+and CDNSKEY records are present in the child zone, the CDS is preferred.
+This enables a child zone to inform its parent of upcoming changes to
+its key-signing keys (KSKs); by polling periodically with :program:`dnssec-cds`, the
+parent can keep the DS records up-to-date and enable automatic rolling
+of KSKs.
+
+Two input files are required. The :option:`-f child-file <-f>` option specifies a
+file containing the child's CDS and/or CDNSKEY records, plus RRSIG and
+DNSKEY records so that they can be authenticated. The :option:`-d path <-d>` option
+specifies the location of a file containing the current DS records. For
+example, this could be a ``dsset-`` file generated by
+:iscman:`dnssec-signzone`, or the output of :iscman:`dnssec-dsfromkey`, or the
+output of a previous run of :program:`dnssec-cds`.
+
+The :program:`dnssec-cds` command uses special DNSSEC validation logic
+specified by :rfc:`7344`. It requires that the CDS and/or CDNSKEY records
+be validly signed by a key represented in the existing DS records. This
+is typically the pre-existing KSK.
+
+For protection against replay attacks, the signatures on the child
+records must not be older than they were on a previous run of
+:program:`dnssec-cds`. Their age is obtained from the modification time of the
+``dsset-`` file, or from the :option:`-s` option.
+
+To protect against breaking the delegation, :program:`dnssec-cds` ensures that
+the DNSKEY RRset can be verified by every key algorithm in the new DS
+RRset, and that the same set of keys are covered by every DS digest
+type.
+
+By default, replacement DS records are written to the standard output;
+with the :option:`-i` option the input file is overwritten in place. The
+replacement DS records are the same as the existing records, when no
+change is required. The output can be empty if the CDS/CDNSKEY records
+specify that the child zone wants to be insecure.
+
+.. warning::
+
+   Be careful not to delete the DS records when :program:`dnssec-cds` fails!
+
+Alternatively, :option`dnssec-cds -u` writes an :iscman:`nsupdate` script to the
+standard output. The :option:`-u` and :option:`-i` options can be used together to
+maintain a ``dsset-`` file as well as emit an :iscman:`nsupdate` script.
+
+Options
+~~~~~~~
+
+.. option:: -a algorithm
+
+   When converting CDS records to DS records, this option specifies
+   the acceptable digest algorithms. This option can be repeated, so
+   that multiple digest types are allowed. If none of the CDS records
+   use an acceptable digest type, :program:`dnssec-cds` will try to use CDNSKEY
+   records instead; if there are no CDNSKEY records, it reports an error.
+
+   When converting CDNSKEY records to DS records, this option specifies the
+   digest algorithm to use. It can be repeated, so that multiple DS records
+   are created for each CDNSKEY records.
+
+   The algorithm must be one of SHA-1, SHA-256, or SHA-384. These values
+   are case-insensitive, and the hyphen may be omitted. If no algorithm
+   is specified, the default is SHA-256 only.
+
+.. option:: -c class
+
+   This option specifies the DNS class of the zones.
+
+.. option:: -D
+
+   This option generates DS records from CDNSKEY records if both CDS and CDNSKEY
+   records are present in the child zone. By default CDS records are
+   preferred.
+
+.. option:: -d path
+
+   This specifies the location of the parent DS records. The path can be the name of a file
+   containing the DS records; if it is a directory, :program:`dnssec-cds`
+   looks for a ``dsset-`` file for the domain inside the directory.
+
+   To protect against replay attacks, child records are rejected if they
+   were signed earlier than the modification time of the ``dsset-``
+   file. This can be adjusted with the :option:`-s` option.
+
+.. option:: -f child-file
+
+   This option specifies the file containing the child's CDS and/or CDNSKEY records, plus its
+   DNSKEY records and the covering RRSIG records, so that they can be
+   authenticated.
+
+   The examples below describe how to generate this file.
+
+.. option:: -i extension
+
+   This option updates the ``dsset-`` file in place, instead of writing DS records to
+   the standard output.
+
+   There must be no space between the :option:`-i` and the extension. If
+   no extension is provided, the old ``dsset-`` is discarded. If an
+   extension is present, a backup of the old ``dsset-`` file is kept
+   with the extension appended to its filename.
+
+   To protect against replay attacks, the modification time of the
+   ``dsset-`` file is set to match the signature inception time of the
+   child records, provided that it is later than the file's current
+   modification time.
+
+.. option:: -s start-time
+
+   This option specifies the date and time after which RRSIG records become
+   acceptable. This can be either an absolute or a relative time. An
+   absolute start time is indicated by a number in YYYYMMDDHHMMSS
+   notation; 20170827133700 denotes 13:37:00 UTC on August 27th, 2017. A
+   time relative to the ``dsset-`` file is indicated with ``-N``, which is N
+   seconds before the file modification time. A time relative to the
+   current time is indicated with ``now+N``.
+
+   If no start-time is specified, the modification time of the
+   ``dsset-`` file is used.
+
+.. option:: -T ttl
+
+   This option specifies a TTL to be used for new DS records. If not specified, the
+   default is the TTL of the old DS records. If they had no explicit TTL,
+   the new DS records also have no explicit TTL.
+
+.. option:: -u
+
+   This option writes an :iscman:`nsupdate` script to the standard output, instead of
+   printing the new DS reords. The output is empty if no change is
+   needed.
+
+   Note: The TTL of new records needs to be specified: it can be done in the
+   original ``dsset-`` file, with the :option:`-T` option, or using the
+   :iscman:`nsupdate` ``ttl`` command.
+
+.. option:: -V
+
+   This option prints version information.
+
+.. option:: -v level
+
+   This option sets the debugging level. Level 1 is intended to be usefully verbose
+   for general users; higher levels are intended for developers.
+
+``domain``
+   This indicates the name of the delegation point/child zone apex.
+
+Exit Status
+~~~~~~~~~~~
+
+The :program:`dnssec-cds` command exits 0 on success, or non-zero if an error
+occurred.
+
+If successful, the DS records may or may not need to be
+changed.
+
+Examples
+~~~~~~~~
+
+Before running :iscman:`dnssec-signzone`, ensure that the delegations
+are up-to-date by running :program:`dnssec-cds` on every ``dsset-`` file.
+
+To fetch the child records required by :program:`dnssec-cds`, invoke
+:iscman:`dig` as in the script below. It is acceptable if the :iscman:`dig` fails, since
+:program:`dnssec-cds` performs all the necessary checking.
+
+::
+
+   for f in dsset-*
+   do
+       d=${f#dsset-}
+       dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
+       dnssec-cds -i -f /dev/stdin -d $f $d
+   done
+
+When the parent zone is automatically signed by :iscman:`named`,
+:program:`dnssec-cds` can be used with :iscman:`nsupdate` to maintain a delegation as follows.
+The ``dsset-`` file allows the script to avoid having to fetch and
+validate the parent DS records, and it maintains the replay attack
+protection time.
+
+::
+
+   dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
+   dnssec-cds -u -i -f /dev/stdin -d $f $d |
+   nsupdate -l
+
+See Also
+~~~~~~~~
+
+:iscman:`dig(1) <dig>`, :iscman:`dnssec-settime(8) <dnssec-settime>`, :iscman:`dnssec-signzone(8) <dnssec-signzone>`, :iscman:`nsupdate(1) <nsupdate>`, BIND 9 Administrator
+Reference Manual, :rfc:`7344`.