4419606c9d
Move BIND binaries which are neither daemons nor administrative programs to $bindir. This results in only the following binaries being left in $sbindir: - ddns-confgen - named - rndc - rndc-confgen - tsig-confgen
226 lines
8.1 KiB
Plaintext
226 lines
8.1 KiB
Plaintext
.\" Man page generated from reStructuredText.
|
|
.
|
|
.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
|
|
.
|
|
.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
|
|
..
|
|
.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\fP [extension]] [\fB\-s\fP 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; 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 \fB\-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 \fB\-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
|
|
\fBdnssec\-signzone\fP, or the output of \fBdnssec\-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 \fI\%RFC 7344\fP\&. It requires that the CDS and/or CDNSKEY records
|
|
are validly signed by a key represented in the existing DS records. This
|
|
will typically be the pre\-existing key\-signing key (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\&. This time is obtained from the modification time of the
|
|
\fBdsset\-\fP file, or from the \fB\-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 \fB\-i\fP option the input file is overwritten in place. The
|
|
replacement DS records will be 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 go insecure.
|
|
.sp
|
|
Warning: Be careful not to delete the DS records when \fBdnssec\-cds\fP
|
|
fails!
|
|
.sp
|
|
Alternatively, \fBdnssec\-cds \-u\fP writes an \fBnsupdate\fP script to the
|
|
standard output. You can use the \fB\-u\fP and \fB\-i\fP options together to
|
|
maintain a \fBdsset\-\fP file as well as emit an \fBnsupdate\fP script.
|
|
.SH OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
\fB\-a\fP algorithm
|
|
Specify a digest algorithm to use when converting CDNSKEY records to
|
|
DS records. This option can be repeated, so that multiple DS records
|
|
are created for each CDNSKEY record. This option has no effect when
|
|
using CDS 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.
|
|
.TP
|
|
\fB\-c\fP class
|
|
Specifies the DNS class of the zones.
|
|
.TP
|
|
\fB\-D\fP
|
|
Generate DS records from CDNSKEY records if both CDS and CDNSKEY
|
|
records are present in the child zone. By default CDS records are
|
|
preferred.
|
|
.TP
|
|
\fB\-d\fP path
|
|
Location of the parent DS records. The path can be the name of a file
|
|
containing the DS records, or 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 \fB\-s\fP option.
|
|
.TP
|
|
\fB\-f\fP child\-file
|
|
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.
|
|
.TP
|
|
\fB\-iextension\fP
|
|
Update the \fBdsset\-\fP file in place, instead of writing DS records to
|
|
the standard output.
|
|
.sp
|
|
There must be no space between the \fB\-i\fP and the extension. If you
|
|
provide no extension then 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 is later than the file\(aqs current
|
|
modification time.
|
|
.TP
|
|
\fB\-s\fP start\-time
|
|
Specify the date and time after which RRSIG records become
|
|
acceptable. This can be either an absolute or 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 \-N, which is N
|
|
seconds before the file modification time. A time relative to the
|
|
current time is indicated with now+N.
|
|
.sp
|
|
If no start\-time is specified, the modification time of the
|
|
\fBdsset\-\fP file is used.
|
|
.TP
|
|
\fB\-T\fP ttl
|
|
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
|
|
then the new DS records also have no explicit TTL.
|
|
.TP
|
|
\fB\-u\fP
|
|
Write an \fBnsupdate\fP script to the standard output, instead of
|
|
printing the new DS reords. The output will be empty if no change is
|
|
needed.
|
|
.sp
|
|
Note: The TTL of new records needs to be specified, either in the
|
|
original \fBdsset\-\fP file, or with the \fB\-T\fP option, or using the
|
|
\fBnsupdate\fP \fBttl\fP command.
|
|
.TP
|
|
\fB\-V\fP
|
|
Print version information.
|
|
.TP
|
|
\fB\-v\fP level
|
|
Sets the debugging level. Level 1 is intended to be usefully verbose
|
|
for general users; higher levels are intended for developers.
|
|
.TP
|
|
.B domain
|
|
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
|
|
In the success case, the DS records might or might not need to be
|
|
changed.
|
|
.SH EXAMPLES
|
|
.sp
|
|
Before running \fBdnssec\-signzone\fP, you can 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 you can invoke
|
|
\fBdig\fP as in the script below. It\(aqs okay if the \fBdig\fP fails since
|
|
\fBdnssec\-cds\fP performs all the necessary checking.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
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
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
When the parent zone is automatically signed by \fBnamed\fP, you can use
|
|
\fBdnssec\-cds\fP with \fBnsupdate\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 keeps the replay attack
|
|
protection time.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
|
|
dnssec\-cds \-u \-i \-f /dev/stdin \-d $f $d |
|
|
nsupdate \-l
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fBdig(1)\fP, \fBdnssec\-settime(8)\fP, \fBdnssec\-signzone(8)\fP, \fBnsupdate(1)\fP, BIND 9 Administrator
|
|
Reference Manual, \fI\%RFC 7344\fP\&.
|
|
.SH AUTHOR
|
|
Internet Systems Consortium
|
|
.SH COPYRIGHT
|
|
2020, Internet Systems Consortium
|
|
.\" Generated by docutils manpage writer.
|
|
.
|