Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-cds.8
CommitLineData
b4d3f782 1.\" Copyright (C) 2017-2019 Internet Systems Consortium, Inc. ("ISC")
26cde05d 2.\"
ba37674d
EH
3.\" This Source Code Form is subject to the terms of the Mozilla Public
4.\" License, v. 2.0. If a copy of the MPL was not distributed with this
5.\" file, You can obtain one at http://mozilla.org/MPL/2.0/.
6.\"
7.hy 0
8.ad l
9'\" t
10.\" Title: dnssec-cds
26cde05d
TU
11.\" Author:
12.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
ba37674d
EH
13.\" Date: 2017-10-02
14.\" Manual: BIND9
15.\" Source: ISC
16.\" Language: English
17.\"
18.TH "DNSSEC\-CDS" "8" "2017\-10\-02" "ISC" "BIND9"
19.\" -----------------------------------------------------------------
20.\" * Define some portability stuff
21.\" -----------------------------------------------------------------
22.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23.\" http://bugs.debian.org/507673
24.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
25.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26.ie \n(.g .ds Aq \(aq
27.el .ds Aq '
28.\" -----------------------------------------------------------------
29.\" * set default formatting
30.\" -----------------------------------------------------------------
31.\" disable hyphenation
32.nh
33.\" disable justification (adjust text to left margin only)
34.ad l
35.\" -----------------------------------------------------------------
36.\" * MAIN CONTENT STARTS HERE *
37.\" -----------------------------------------------------------------
38.SH "NAME"
39dnssec-cds \- change DS records for a child zone based on CDS/CDNSKEY
40.SH "SYNOPSIS"
26cde05d 41.HP \w'\fBdnssec\-cds\fR\ 'u
ba37674d
EH
42\fBdnssec\-cds\fR [\fB\-a\ \fR\fB\fIalg\fR\fR...] [\fB\-c\ \fR\fB\fIclass\fR\fR] [\fB\-D\fR] {\fB\-d\ \fR\fB\fIdsset\-file\fR\fR} {\fB\-f\ \fR\fB\fIchild\-file\fR\fR} [\fB\-i\fR\ [\fIextension\fR]] [\fB\-s\ \fR\fB\fIstart\-time\fR\fR] [\fB\-T\ \fR\fB\fIttl\fR\fR] [\fB\-u\fR] [\fB\-v\ \fR\fB\fIlevel\fR\fR] [\fB\-V\fR] {domain}
43.SH "DESCRIPTION"
44.PP
45The
46\fBdnssec\-cds\fR
a7bc00e4
TU
47command 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
48\fBdnssec\-cds\fR, the parent can keep the DS records up to date and enable automatic rolling of KSKs\&.
ba37674d
EH
49.PP
50Two input files are required\&. The
51\fB\-f \fR\fB\fIchild\-file\fR\fR
52option specifies a file containing the child\*(Aqs CDS and/or CDNSKEY records, plus RRSIG and DNSKEY records so that they can be authenticated\&. The
53\fB\-d \fR\fB\fIpath\fR\fR
54option specifies the location of a file containing the current DS records\&. For example, this could be a
55dsset\-
56file generated by
57\fBdnssec\-signzone\fR, or the output of
58\fBdnssec\-dsfromkey\fR, or the output of a previous run of
59\fBdnssec\-cds\fR\&.
60.PP
a7bc00e4
TU
61The
62\fBdnssec\-cds\fR
63command uses special DNSSEC validation logic specified by RFC 7344\&. It requires that the CDS and/or CDNSKEY records are validly signed by a key represented in the existing DS records\&. This will typicially be the pre\-existing key\-signing key (KSK)\&.
64.PP
ba37674d
EH
65For protection against replay attacks, the signatures on the child records must not be older than they were on a previous run of
66\fBdnssec\-cds\fR\&. This time is obtained from the modification time of the
67dsset\-
68file, or from the
69\fB\-s\fR
70option\&.
71.PP
72To protect against breaking the delegation,
73\fBdnssec\-cds\fR
74ensures 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\&.
75.PP
76By default, replacement DS records are written to the standard output; with the
77\fB\-i\fR
78option 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\&.
79.PP
80Warning: Be careful not to delete the DS records when
81\fBdnssec\-cds\fR
82fails!
83.PP
84Alternatively,
85\fBdnssec\-cds \-u\fR
86writes an
87\fBnsupdate\fR
88script to the standard output\&. You can use the
89\fB\-u\fR
90and
91\fB\-i\fR
92options together to maintain a
93dsset\-
94file as well as emit an
95\fBnsupdate\fR
96script\&.
97.SH "OPTIONS"
98.PP
99\-a \fIalgorithm\fR
100.RS 4
101Specify 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\&.
102.sp
103The
104\fIalgorithm\fR
b4d3f782 105must 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\&.
ba37674d
EH
106.RE
107.PP
108\-c \fIclass\fR
109.RS 4
110Specifies the DNS class of the zones\&.
111.RE
112.PP
113\-D
114.RS 4
115Generate DS records from CDNSKEY records if both CDS and CDNSKEY records are present in the child zone\&. By default CDS records are preferred\&.
116.RE
117.PP
118\-d \fIpath\fR
119.RS 4
120Location of the parent DS records\&. The
121\fIpath\fR
122can be the name of a file containing the DS records, or if it is a directory,
123\fBdnssec\-cds\fR
124looks for a
125dsset\-
126file for the
127\fIdomain\fR
128inside the directory\&.
129.sp
130To protect against replay attacks, child records are rejected if they were signed earlier than the modification time of the
131dsset\-
132file\&. This can be adjusted with the
133\fB\-s\fR
134option\&.
135.RE
136.PP
137\-f \fIchild\-file\fR
138.RS 4
139File containing the child\*(Aqs CDS and/or CDNSKEY records, plus its DNSKEY records and the covering RRSIG records so that they can be authenticated\&.
140.sp
141The EXAMPLES below describe how to generate this file\&.
142.RE
143.PP
144\-i [\fIextension\fR]
145.RS 4
146Update the
147dsset\-
148file in place, instead of writing DS records to the standard output\&.
149.sp
150There must be no space between the
151\fB\-i\fR
152and the
153\fIextension\fR\&. If you provide no
154\fIextension\fR
155then the old
156dsset\-
157is discarded\&. If an
158\fIextension\fR
159is present, a backup of the old
160dsset\-
161file is kept with the
162\fIextension\fR
163appended to its filename\&.
164.sp
165To protect against replay attacks, the modification time of the
166dsset\-
167file is set to match the signature inception time of the child records, provided that is later than the file\*(Aqs current modification time\&.
168.RE
169.PP
170\-s \fIstart\-time\fR
171.RS 4
172Specify 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
173dsset\-
174file 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\&.
175.sp
176If no
177\fIstart\-time\fR
178is specified, the modification time of the
179dsset\-
180file is used\&.
181.RE
182.PP
183\-T \fIttl\fR
184.RS 4
185Specifies 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\&.
186.RE
187.PP
188\-u
189.RS 4
190Write an
191\fBnsupdate\fR
192script to the standard output, instead of printing the new DS reords\&. The output will be empty if no change is needed\&.
193.sp
194Note: The TTL of new records needs to be specified, either in the original
195dsset\-
196file, or with the
197\fB\-T\fR
198option, or using the
26cde05d 199\fBnsupdate\fR\fBttl\fR
ba37674d
EH
200command\&.
201.RE
202.PP
203\-V
204.RS 4
205Print version information\&.
206.RE
207.PP
208\-v \fIlevel\fR
209.RS 4
210Sets the debugging level\&. Level 1 is intended to be usefully verbose for general users; higher levels are intended for developers\&.
211.RE
212.PP
213\fIdomain\fR
214.RS 4
215The name of the delegation point / child zone apex\&.
216.RE
217.SH "EXIT STATUS"
218.PP
219The
220\fBdnssec\-cds\fR
221command exits 0 on success, or non\-zero if an error occurred\&.
222.PP
223In the success case, the DS records might or might not need to be changed\&.
224.SH "EXAMPLES"
225.PP
226Before running
227\fBdnssec\-signzone\fR, you can ensure that the delegations are up\-to\-date by running
228\fBdnssec\-cds\fR
229on every
230dsset\-
231file\&.
232.PP
233To fetch the child records required by
234\fBdnssec\-cds\fR
235you can invoke
236\fBdig\fR
237as in the script below\&. It\*(Aqs okay if the
238\fBdig\fR
239fails since
240\fBdnssec\-cds\fR
241performs all the necessary checking\&.
242.sp
243.if n \{\
244.RS 4
245.\}
246.nf
247for f in dsset\-*
248do
249 d=${f#dsset\-}
250 dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
251 dnssec\-cds \-i \-f /dev/stdin \-d $f $d
252done
253.fi
254.if n \{\
255.RE
256.\}
257.PP
258When the parent zone is automatically signed by
259\fBnamed\fR, you can use
260\fBdnssec\-cds\fR
261with
262\fBnsupdate\fR
263to maintain a delegation as follows\&. The
264dsset\-
265file allows the script to avoid having to fetch and validate the parent DS records, and it keeps the replay attack protection time\&.
266.sp
267.if n \{\
268.RS 4
269.\}
270.nf
271dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
272dnssec\-cds \-u \-i \-f /dev/stdin \-d $f $d |
273nsupdate \-l
274.fi
275.if n \{\
276.RE
277.\}
278.SH "SEE ALSO"
279.PP
280\fBdig\fR(1),
281\fBdnssec-settime\fR(8),
282\fBdnssec-signzone\fR(8),
283\fBnsupdate\fR(1),
284BIND 9 Administrator Reference Manual,
285RFC 7344\&.
286.SH "AUTHORS"
287.PP
288\fBInternet Systems Consortium, Inc\&.\fR
289.PP
290\fBTony Finch\fR <\&dot@dotat\&.at\&>, <\&fanf2@cam\&.ac\&.uk\&>
291.br
292.RS 4
293.RE
294.SH "COPYRIGHT"
295.br
b4d3f782 296Copyright \(co 2017-2019 Internet Systems Consortium, Inc. ("ISC")
ba37674d 297.br