Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-cds.docbook
1 <!--
2 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3 -
4 - This Source Code Form is subject to the terms of the Mozilla Public
5 - License, v. 2.0. If a copy of the MPL was not distributed with this
6 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 -
8 - See the COPYRIGHT file distributed with this work for additional
9 - information regarding copyright ownership.
10 -->
11
12 <refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.dnssec-cds">
13 <info>
14 <date>2017-10-02</date>
15 </info>
16 <refentryinfo>
17 <corpname>ISC</corpname>
18 <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
19 <author>
20 <personname>Tony Finch</personname>
21 <email>dot@dotat.at</email>
22 <email>fanf2@cam.ac.uk</email>
23 <affiliation>Cambridge University Information Services</affiliation>
24 <personblurb></personblurb>
25 </author>
26 </refentryinfo>
27
28 <refmeta>
29 <refentrytitle><application>dnssec-cds</application></refentrytitle>
30 <manvolnum>8</manvolnum>
31 <refmiscinfo>BIND9</refmiscinfo>
32 </refmeta>
33
34 <refnamediv>
35 <refname><application>dnssec-cds</application></refname>
36 <refpurpose>change DS records for a child zone based on CDS/CDNSKEY</refpurpose>
37 </refnamediv>
38
39 <docinfo>
40 <copyright>
41 <year>2017</year>
42 <year>2018</year>
43 <year>2019</year>
44 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
45 </copyright>
46 </docinfo>
47
48 <refsynopsisdiv>
49 <cmdsynopsis sepchar=" ">
50 <command>dnssec-cds</command>
51 <arg choice="opt" rep="repeat"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
52 <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
53 <arg choice="opt" rep="norepeat"><option>-D</option></arg>
54 <arg choice="req" rep="norepeat"><option>-d <replaceable class="parameter">dsset-file</replaceable></option></arg>
55 <arg choice="req" rep="norepeat"><option>-f <replaceable class="parameter">child-file</replaceable></option></arg>
56 <arg choice="opt" rep="norepeat"><option>-i</option><arg choice="opt" rep="norepeat"><replaceable class="parameter">extension</replaceable></arg></arg>
57 <arg choice="opt" rep="norepeat"><option>-s <replaceable class="parameter">start-time</replaceable></option></arg>
58 <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">ttl</replaceable></option></arg>
59 <arg choice="opt" rep="norepeat"><option>-u</option></arg>
60 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
61 <arg choice="opt" rep="norepeat"><option>-V</option></arg>
62 <arg choice="req" rep="norepeat">domain</arg>
63 </cmdsynopsis>
64 </refsynopsisdiv>
65
66 <refsection><info><title>DESCRIPTION</title></info>
67
68 <para>
69 The <command>dnssec-cds</command> command changes DS records at
70 a delegation point based on CDS or CDNSKEY records published in
71 the child zone. If both CDS and CDNSKEY records are present in
72 the child zone, the CDS is preferred. This enables a child zone
73 to inform its parent of upcoming changes to its key-signing keys;
74 by polling periodically with <command>dnssec-cds</command>, the
75 parent can keep the DS records up to date and enable automatic
76 rolling of KSKs.
77 </para>
78 <para>
79 Two input files are required. The
80 <option>-f <replaceable class="parameter">child-file</replaceable></option>
81 option specifies a file containing the child's CDS and/or CDNSKEY
82 records, plus RRSIG and DNSKEY records so that they can be
83 authenticated. The
84 <option>-d <replaceable class="parameter">path</replaceable></option>
85 option specifies the location of a file containing the current DS
86 records. For example, this could be a <filename>dsset-</filename>
87 file generated by <command>dnssec-signzone</command>, or the output of
88 <command>dnssec-dsfromkey</command>, or the output of a previous
89 run of <command>dnssec-cds</command>.
90 </para>
91 <para>
92 The <command>dnssec-cds</command> command uses special DNSSEC
93 validation logic specified by RFC 7344. It requires that the CDS
94 and/or CDNSKEY records are validly signed by a key represented in the
95 existing DS records. This will typicially be the pre-existing
96 key-signing key (KSK).
97 </para>
98 <para>
99 For protection against replay attacks, the signatures on the
100 child records must not be older than they were on a previous run
101 of <command>dnssec-cds</command>. This time is obtained from the
102 modification time of the <filename>dsset-</filename> file, or
103 from the <option>-s</option> option.
104 </para>
105 <para>
106 To protect against breaking the delegation,
107 <command>dnssec-cds</command> ensures that the DNSKEY RRset can be
108 verified by every key algorithm in the new DS RRset, and that the
109 same set of keys are covered by every DS digest type.
110 </para>
111 <para>
112 By default, replacement DS records are written to the standard
113 output; with the <option>-i</option> option the input file is
114 overwritten in place. The replacement DS records will be the
115 same as the existing records when no change is required. The
116 output can be empty if the CDS / CDNSKEY records specify that
117 the child zone wants to go insecure.
118 </para>
119 <para>
120 Warning: Be careful not to delete the DS records
121 when <command>dnssec-cds</command> fails!
122 </para>
123 <para>
124 Alternatively, <command>dnssec-cds -u</command> writes
125 an <command>nsupdate</command> script to the standard output.
126 You can use the <option>-u</option> and <option>-i</option>
127 options together to maintain a <filename>dsset-</filename> file
128 as well as emit an <command>nsupdate</command> script.
129 </para>
130
131 </refsection>
132
133 <refsection><info><title>OPTIONS</title></info>
134
135 <variablelist>
136
137 <varlistentry>
138 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
139 <listitem>
140 <para>
141 Specify a digest algorithm to use when converting CDNSKEY
142 records to DS records. This option can be repeated, so
143 that multiple DS records are created for each CDNSKEY
144 record. This option has no effect when using CDS records.
145 </para>
146 <para>
147 The <replaceable>algorithm</replaceable> must be one of
148 SHA-1, SHA-256, or SHA-384. These values are case insensitive,
149 and the hyphen may be omitted. If no algorithm is specified,
150 the default is SHA-256.
151 </para>
152 </listitem>
153 </varlistentry>
154
155 <varlistentry>
156 <term>-c <replaceable class="parameter">class</replaceable></term>
157 <listitem>
158 <para>
159 Specifies the DNS class of the zones.
160 </para>
161 </listitem>
162 </varlistentry>
163
164 <varlistentry>
165 <term>-D</term>
166 <listitem>
167 <para>
168 Generate DS records from CDNSKEY records if both CDS and
169 CDNSKEY records are present in the child zone. By default
170 CDS records are preferred.
171 </para>
172 </listitem>
173 </varlistentry>
174
175 <varlistentry>
176 <term>-d <replaceable class="parameter">path</replaceable></term>
177 <listitem>
178 <para>
179 Location of the parent DS records.
180 The <replaceable>path</replaceable> can be the name of a file
181 containing the DS records, or if it is a
182 directory, <command>dnssec-cds</command> looks for
183 a <filename>dsset-</filename> file for
184 the <replaceable>domain</replaceable> inside the directory.
185 </para>
186 <para>
187 To protect against replay attacks, child records are
188 rejected if they were signed earlier than the modification
189 time of the <filename>dsset-</filename> file. This can be
190 adjusted with the <option>-s</option> option.
191 </para>
192 </listitem>
193 </varlistentry>
194
195 <varlistentry>
196 <term>-f <replaceable class="parameter">child-file</replaceable></term>
197 <listitem>
198 <para>
199 File containing the child's CDS and/or CDNSKEY records,
200 plus its DNSKEY records and the covering RRSIG records so
201 that they can be authenticated.
202 </para>
203 <para>
204 The EXAMPLES below describe how to generate this file.
205 </para>
206 </listitem>
207 </varlistentry>
208
209 <varlistentry>
210 <term>-i<arg choice="opt" rep="norepeat"><replaceable class="parameter">extension</replaceable></arg></term>
211 <listitem>
212 <para>
213 Update the <filename>dsset-</filename> file in place,
214 instead of writing DS records to the standard output.
215 </para>
216 <para>
217 There must be no space between the <option>-i</option> and
218 the <replaceable>extension</replaceable>. If you provide
219 no <replaceable>extension</replaceable> then the
220 old <filename>dsset-</filename> is discarded. If
221 an <replaceable>extension</replaceable> is present, a
222 backup of the old <filename>dsset-</filename> file is kept
223 with the <replaceable>extension</replaceable> appended to
224 its filename.
225 </para>
226 <para>
227 To protect against replay attacks, the modification time
228 of the <filename>dsset-</filename> file is set to match
229 the signature inception time of the child records,
230 provided that is later than the file's current
231 modification time.
232 </para>
233 </listitem>
234 </varlistentry>
235
236 <varlistentry>
237 <term>-s <replaceable class="parameter">start-time</replaceable></term>
238 <listitem>
239 <para>
240 Specify the date and time after which RRSIG records become
241 acceptable. This can be either an absolute or relative
242 time. An absolute start time is indicated by a number in
243 YYYYMMDDHHMMSS notation; 20170827133700 denotes 13:37:00
244 UTC on August 27th, 2017. A time relative to
245 the <filename>dsset-</filename> file is indicated with -N,
246 which is N seconds before the file modification time. A
247 time relative to the current time is indicated with now+N.
248 </para>
249 <para>
250 If no <replaceable>start-time</replaceable> is specified, the
251 modification time of the <filename>dsset-</filename> file
252 is used.
253 </para>
254 </listitem>
255 </varlistentry>
256
257 <varlistentry>
258 <term>-T <replaceable class="parameter">ttl</replaceable></term>
259 <listitem>
260 <para>
261 Specifies a TTL to be used for new DS records. If not
262 specified, the default is the TTL of the old DS records.
263 If they had no explicit TTL then the new DS records also
264 have no explicit TTL.
265 </para>
266 </listitem>
267 </varlistentry>
268
269 <varlistentry>
270 <term>-u</term>
271 <listitem>
272 <para>
273 Write an <command>nsupdate</command> script to the
274 standard output, instead of printing the new DS reords.
275 The output will be empty if no change is needed.
276 </para>
277 <para>
278 Note: The TTL of new records needs to be specified, either
279 in the original <filename>dsset-</filename> file, or with
280 the <option>-T</option> option, or using
281 the <command>nsupdate</command> <command>ttl</command>
282 command.
283 </para>
284 </listitem>
285 </varlistentry>
286
287 <varlistentry>
288 <term>-V</term>
289 <listitem>
290 <para>
291 Print version information.
292 </para>
293 </listitem>
294 </varlistentry>
295
296 <varlistentry>
297 <term>-v <replaceable class="parameter">level</replaceable></term>
298 <listitem>
299 <para>
300 Sets the debugging level. Level 1 is intended to be
301 usefully verbose for general users; higher levels are
302 intended for developers.
303 </para>
304 </listitem>
305 </varlistentry>
306
307 <varlistentry>
308 <term><replaceable>domain</replaceable></term>
309 <listitem>
310 <para>
311 The name of the delegation point / child zone apex.
312 </para>
313 </listitem>
314 </varlistentry>
315
316 </variablelist>
317 </refsection>
318
319 <refsection><info><title>EXIT STATUS</title></info>
320
321 <para>
322 The <command>dnssec-cds</command> command exits 0 on success, or
323 non-zero if an error occurred.
324 </para>
325 <para>
326 In the success case, the DS records might or might not need
327 to be changed.
328 </para>
329
330 </refsection>
331
332 <refsection><info><title>EXAMPLES</title></info>
333
334 <para>
335 Before running <command>dnssec-signzone</command>, you can ensure
336 that the delegations are up-to-date by running
337 <command>dnssec-cds</command> on every <filename>dsset-</filename> file.
338 </para>
339 <para>
340 To fetch the child records required by <command>dnssec-cds</command>
341 you can invoke <command>dig</command> as in the script below. It's
342 okay if the <command>dig</command> fails since
343 <command>dnssec-cds</command> performs all the necessary checking.
344 </para>
345 <programlisting>for f in dsset-*
346 do
347 d=${f#dsset-}
348 dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
349 dnssec-cds -i -f /dev/stdin -d $f $d
350 done
351 </programlisting>
352
353 <para>
354 When the parent zone is automatically signed by
355 <command>named</command>, you can use <command>dnssec-cds</command>
356 with <command>nsupdate</command> to maintain a delegation as follows.
357 The <filename>dsset-</filename> file allows the script to avoid
358 having to fetch and validate the parent DS records, and it keeps the
359 replay attack protection time.
360 </para>
361 <programlisting>
362 dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
363 dnssec-cds -u -i -f /dev/stdin -d $f $d |
364 nsupdate -l
365 </programlisting>
366 </refsection>
367
368 <refsection><info><title>SEE ALSO</title></info>
369
370 <para>
371 <citerefentry>
372 <refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
373 </citerefentry>,
374 <citerefentry>
375 <refentrytitle>dnssec-settime</refentrytitle><manvolnum>8</manvolnum>
376 </citerefentry>,
377 <citerefentry>
378 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
379 </citerefentry>,
380 <citerefentry>
381 <refentrytitle>nsupdate</refentrytitle><manvolnum>1</manvolnum>
382 </citerefentry>,
383 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
384 <citetitle>RFC 7344</citetitle>.
385 </para>
386
387 </refsection>
388
389 </refentry>