diff options
Diffstat (limited to 'bin/dnssec/dnssec-cds.rst')
| -rw-r--r-- | bin/dnssec/dnssec-cds.rst | 221 |
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`. |