Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_13_...
[ipreg/bind9.git] / bin / dnssec / dnssec-cds.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <!--
3 - Copyright (C) 2017-2019 Internet Systems Consortium, Inc. ("ISC")
4 -
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>
13 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
14 </head>
15 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
16 <a name="man.dnssec-cds"></a><div class="titlepage"></div>
17
18
19
20
21
22 <div class="refnamediv">
23 <h2>Name</h2>
24 <p>
25 <span class="application">dnssec-cds</span>
26 &#8212; change DS records for a child zone based on CDS/CDNSKEY
27 </p>
28 </div>
29
30
31
32 <div class="refsynopsisdiv">
33 <h2>Synopsis</h2>
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">
52 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
53
54 <p>
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
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.
63 </p>
64 <p>
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>
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>
84 <p>
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>
91 <p>
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>
97 <p>
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>
105 <p>
106 Warning: Be careful not to delete the DS records
107 when <span class="command"><strong>dnssec-cds</strong></span> fails!
108 </p>
109 <p>
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>
116
117 </div>
118
119 <div class="refsection">
120 <a name="id-1.8"></a><h2>OPTIONS</h2>
121
122 <div class="variablelist"><dl class="variablelist">
123 <dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
124 <dd>
125 <p>
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>
131 <p>
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,
135 the default is SHA-256.
136 </p>
137 </dd>
138 <dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
139 <dd>
140 <p>
141 Specifies the DNS class of the zones.
142 </p>
143 </dd>
144 <dt><span class="term">-D</span></dt>
145 <dd>
146 <p>
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.
150 </p>
151 </dd>
152 <dt><span class="term">-d <em class="replaceable"><code>path</code></em></span></dt>
153 <dd>
154 <p>
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>
162 <p>
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>
168 </dd>
169 <dt><span class="term">-f <em class="replaceable"><code>child-file</code></em></span></dt>
170 <dd>
171 <p>
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>
176 <p>
177 The EXAMPLES below describe how to generate this file.
178 </p>
179 </dd>
180 <dt><span class="term">-i[<em class="replaceable"><code>extension</code></em>]</span></dt>
181 <dd>
182 <p>
183 Update the <code class="filename">dsset-</code> file in place,
184 instead of writing DS records to the standard output.
185 </p>
186 <p>
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>
196 <p>
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>
203 </dd>
204 <dt><span class="term">-s <em class="replaceable"><code>start-time</code></em></span></dt>
205 <dd>
206 <p>
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>
216 <p>
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>
221 </dd>
222 <dt><span class="term">-T <em class="replaceable"><code>ttl</code></em></span></dt>
223 <dd>
224 <p>
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.
229 </p>
230 </dd>
231 <dt><span class="term">-u</span></dt>
232 <dd>
233 <p>
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>
238 <p>
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>
245 </dd>
246 <dt><span class="term">-V</span></dt>
247 <dd>
248 <p>
249 Print version information.
250 </p>
251 </dd>
252 <dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
253 <dd>
254 <p>
255 Sets the debugging level. Level 1 is intended to be
256 usefully verbose for general users; higher levels are
257 intended for developers.
258 </p>
259 </dd>
260 <dt><span class="term"><em class="replaceable"><code>domain</code></em></span></dt>
261 <dd>
262 <p>
263 The name of the delegation point / child zone apex.
264 </p>
265 </dd>
266 </dl></div>
267 </div>
268
269 <div class="refsection">
270 <a name="id-1.9"></a><h2>EXIT STATUS</h2>
271
272 <p>
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>
276 <p>
277 In the success case, the DS records might or might not need
278 to be changed.
279 </p>
280
281 </div>
282
283 <div class="refsection">
284 <a name="id-1.10"></a><h2>EXAMPLES</h2>
285
286 <p>
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>
291 <p>
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-*
298 do
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
302 done
303 </pre>
304
305 <p>
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">
314 dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
315 dnssec-cds -u -i -f /dev/stdin -d $f $d |
316 nsupdate -l
317 </pre>
318 </div>
319
320 <div class="refsection">
321 <a name="id-1.11"></a><h2>SEE ALSO</h2>
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>,
336 <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
337 <em class="citetitle">RFC 7344</em>.
338 </p>
339
340 </div>
341
342 </div></body>
343 </html>