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, 256 insertions, 0 deletions

diff --git a/doc/man/dnssec-cds.1in b/doc/man/dnssec-cds.1in
new file mode 100644
index 0000000..143253f
--- /dev/null
+++ b/doc/man/dnssec-cds.1in
@@ -0,0 +1,256 @@
+.\" 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 \fI\%RFC 7344\fP\&. 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
+.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 \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
+.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
+\fI\%dig(1)\fP, \fI\%dnssec\-settime(8)\fP, \fI\%dnssec\-signzone(8)\fP, \fI\%nsupdate(1)\fP, BIND 9 Administrator
+Reference Manual, \fI\%RFC 7344\fP\&.
+.SH AUTHOR
+Internet Systems Consortium
+.SH COPYRIGHT
+2023, Internet Systems Consortium
+.\" Generated by docutils manpage writer.
+.