252 lines
9 KiB
Text
252 lines
9 KiB
Text
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.TH "DNSSEC-CDS" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9"
|
|
.SH NAME
|
|
dnssec-cds \- change DS records for a child zone based on CDS/CDNSKEY
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fBdnssec\-cds\fP [\fB\-a\fP alg...] [\fB\-c\fP class] [\fB\-D\fP] {\fB\-d\fP dsset\-file} {\fB\-f\fP child\-file} [\fB\-i**[extension]] [\fP\-s** start\-time] [\fB\-T\fP ttl] [\fB\-u\fP] [\fB\-v\fP level] [\fB\-V\fP] {domain}
|
|
.SH DESCRIPTION
|
|
.sp
|
|
The \fBdnssec\-cds\fP 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 \fBdnssec\-cds\fP, the
|
|
parent can keep the DS records up\-to\-date and enable automatic rolling
|
|
of KSKs.
|
|
.sp
|
|
Two input files are required. The \fI\%\-f child\-file\fP option specifies a
|
|
file containing the child\(aqs CDS and/or CDNSKEY records, plus RRSIG and
|
|
DNSKEY records so that they can be authenticated. The \fI\%\-d path\fP option
|
|
specifies the location of a file containing the current DS records. For
|
|
example, this could be a \fBdsset\-\fP file generated by
|
|
\fI\%dnssec\-signzone\fP, or the output of \fI\%dnssec\-dsfromkey\fP, or the
|
|
output of a previous run of \fBdnssec\-cds\fP\&.
|
|
.sp
|
|
The \fBdnssec\-cds\fP command uses special DNSSEC validation logic
|
|
specified by \X'tty: link https://datatracker.ietf.org/doc/html/rfc7344.html'\fI\%RFC 7344\fP\X'tty: link'\&. 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.
|
|
.sp
|
|
For protection against replay attacks, the signatures on the child
|
|
records must not be older than they were on a previous run of
|
|
\fBdnssec\-cds\fP\&. Their age is obtained from the modification time of the
|
|
\fBdsset\-\fP file, or from the \fI\%\-s\fP option.
|
|
.sp
|
|
To protect against breaking the delegation, \fBdnssec\-cds\fP 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.
|
|
.sp
|
|
By default, replacement DS records are written to the standard output;
|
|
with the \fI\%\-i\fP 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.
|
|
.sp
|
|
\fBWARNING:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Be careful not to delete the DS records when \fBdnssec\-cds\fP fails!
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Alternatively, :option\(gadnssec\-cds \-u\(ga writes an \fI\%nsupdate\fP script to the
|
|
standard output. The \fI\%\-u\fP and \fI\%\-i\fP options can be used together to
|
|
maintain a \fBdsset\-\fP file as well as emit an \fI\%nsupdate\fP script.
|
|
.SH OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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, \fBdnssec\-cds\fP will try to use CDNSKEY
|
|
records instead; if there are no CDNSKEY records, it reports an error.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-c class
|
|
This option specifies the DNS class of the zones.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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, \fBdnssec\-cds\fP
|
|
looks for a \fBdsset\-\fP file for the domain inside the directory.
|
|
.sp
|
|
To protect against replay attacks, child records are rejected if they
|
|
were signed earlier than the modification time of the \fBdsset\-\fP
|
|
file. This can be adjusted with the \fI\%\-s\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-f child\-file
|
|
This option specifies the file containing the child\(aqs CDS and/or CDNSKEY records, plus its
|
|
DNSKEY records and the covering RRSIG records, so that they can be
|
|
authenticated.
|
|
.sp
|
|
The examples below describe how to generate this file.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-i extension
|
|
This option updates the \fBdsset\-\fP file in place, instead of writing DS records to
|
|
the standard output.
|
|
.sp
|
|
There must be no space between the \fI\%\-i\fP and the extension. If
|
|
no extension is provided, the old \fBdsset\-\fP is discarded. If an
|
|
extension is present, a backup of the old \fBdsset\-\fP file is kept
|
|
with the extension appended to its filename.
|
|
.sp
|
|
To protect against replay attacks, the modification time of the
|
|
\fBdsset\-\fP file is set to match the signature inception time of the
|
|
child records, provided that it is later than the file\(aqs current
|
|
modification time.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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 \fBdsset\-\fP file is indicated with \fB\-N\fP, which is N
|
|
seconds before the file modification time. A time relative to the
|
|
current time is indicated with \fBnow+N\fP\&.
|
|
.sp
|
|
If no start\-time is specified, the modification time of the
|
|
\fBdsset\-\fP file is used.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-u
|
|
This option writes an \fI\%nsupdate\fP script to the standard output, instead of
|
|
printing the new DS reords. The output is empty if no change is
|
|
needed.
|
|
.sp
|
|
Note: The TTL of new records needs to be specified: it can be done in the
|
|
original \fBdsset\-\fP file, with the \fI\%\-T\fP option, or using the
|
|
\fI\%nsupdate\fP \fBttl\fP command.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-V
|
|
This option prints version information.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \fBdomain\fP
|
|
This indicates the name of the delegation point/child zone apex.
|
|
.UNINDENT
|
|
.SH EXIT STATUS
|
|
.sp
|
|
The \fBdnssec\-cds\fP command exits 0 on success, or non\-zero if an error
|
|
occurred.
|
|
.sp
|
|
If successful, the DS records may or may not need to be
|
|
changed.
|
|
.SH EXAMPLES
|
|
.sp
|
|
Before running \fI\%dnssec\-signzone\fP, ensure that the delegations
|
|
are up\-to\-date by running \fBdnssec\-cds\fP on every \fBdsset\-\fP file.
|
|
.sp
|
|
To fetch the child records required by \fBdnssec\-cds\fP, invoke
|
|
\fI\%dig\fP as in the script below. It is acceptable if the \fI\%dig\fP fails, since
|
|
\fBdnssec\-cds\fP performs all the necessary checking.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.EX
|
|
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
|
|
.EE
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
When the parent zone is automatically signed by \fI\%named\fP,
|
|
\fBdnssec\-cds\fP can be used with \fI\%nsupdate\fP to maintain a delegation as follows.
|
|
The \fBdsset\-\fP file allows the script to avoid having to fetch and
|
|
validate the parent DS records, and it maintains the replay attack
|
|
protection time.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.EX
|
|
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
|
|
dnssec\-cds \-u \-i \-f /dev/stdin \-d $f $d |
|
|
nsupdate \-l
|
|
.EE
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fI\%dig(1)\fP, \fI\%dnssec\-settime(8)\fP, \fI\%dnssec\-signzone(8)\fP, \fI\%nsupdate(1)\fP, BIND 9 Administrator
|
|
Reference Manual, \X'tty: link https://datatracker.ietf.org/doc/html/rfc7344.html'\fI\%RFC 7344\fP\X'tty: link'\&.
|
|
.SH AUTHOR
|
|
Internet Systems Consortium
|
|
.SH COPYRIGHT
|
|
2025, Internet Systems Consortium
|
|
.\" Generated by docutils manpage writer.
|
|
.
|