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