diff options
Diffstat (limited to 'doc/man/dnssec-cds.1in')
| -rw-r--r-- | doc/man/dnssec-cds.1in | 256 |
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. +. |