221 lines
8.3 KiB
ReStructuredText
221 lines
8.3 KiB
ReStructuredText
.. 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`.
|