man.dnssec-cds.html 15.2 KB
Newer Older
1 2
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--
Tinderbox User's avatar
Tinderbox User committed
3
 - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC")
4 5 6 7 8 9 10 11 12
 - 
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>dnssec-cds</title>
Tinderbox User's avatar
Tinderbox User committed
13
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
14
<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
15
<link rel="up" href="Bv9ARM.ch12.html" title="Manual pages">
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
<link rel="prev" href="man.dig.html" title="dig">
<link rel="next" href="man.dnssec-checkds.html" title="dnssec-checkds">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center"><span class="application">dnssec-cds</span></th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="man.dig.html">Prev</a> </td>
<th width="60%" align="center">Manual pages</th>
<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-checkds.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="refentry">
<a name="man.dnssec-cds"></a><div class="titlepage"></div>
Tinderbox User's avatar
Tinderbox User committed
35 36 37 38 39 40
  
  

  

  <div class="refnamediv">
41
<h2>Name</h2>
Tinderbox User's avatar
Tinderbox User committed
42 43 44 45
<p>
    <span class="application">dnssec-cds</span>
     &#8212; change DS records for a child zone based on CDS/CDNSKEY
  </p>
46
</div>
Tinderbox User's avatar
Tinderbox User committed
47 48 49 50

  

  <div class="refsynopsisdiv">
51
<h2>Synopsis</h2>
Tinderbox User's avatar
Tinderbox User committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
    <div class="cmdsynopsis"><p>
      <code class="command">dnssec-cds</code> 
       [<code class="option">-a <em class="replaceable"><code>alg</code></em></code>...]
       [<code class="option">-c <em class="replaceable"><code>class</code></em></code>]
       [<code class="option">-D</code>]
       {<code class="option">-d <em class="replaceable"><code>dsset-file</code></em></code>}
       {<code class="option">-f <em class="replaceable"><code>child-file</code></em></code>}
       [<code class="option">-i</code> [<em class="replaceable"><code>extension</code></em>]]
       [<code class="option">-s <em class="replaceable"><code>start-time</code></em></code>]
       [<code class="option">-T <em class="replaceable"><code>ttl</code></em></code>]
       [<code class="option">-u</code>]
       [<code class="option">-v <em class="replaceable"><code>level</code></em></code>]
       [<code class="option">-V</code>]
       {domain}
    </p></div>
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
70
<a name="id-1.13.6.7"></a><h2>DESCRIPTION</h2>
Tinderbox User's avatar
Tinderbox User committed
71 72

    <p>
73 74 75
      The <span class="command"><strong>dnssec-cds</strong></span> 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
Tinderbox User's avatar
Tinderbox User committed
76 77 78 79 80
      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 <span class="command"><strong>dnssec-cds</strong></span>, the
      parent can keep the DS records up to date and enable automatic
      rolling of KSKs.
81
    </p>
Tinderbox User's avatar
Tinderbox User committed
82
    <p>
83 84 85 86 87 88 89 90 91 92 93 94
      Two input files are required.  The
      <code class="option">-f <em class="replaceable"><code>child-file</code></em></code>
      option specifies a file containing the child's CDS and/or CDNSKEY
      records, plus RRSIG and DNSKEY records so that they can be
      authenticated.  The
      <code class="option">-d <em class="replaceable"><code>path</code></em></code>
      option specifies the location of a file containing the current DS
      records. For example, this could be a <code class="filename">dsset-</code>
      file generated by <span class="command"><strong>dnssec-signzone</strong></span>, or the output of
      <span class="command"><strong>dnssec-dsfromkey</strong></span>, or the output of a previous
      run of <span class="command"><strong>dnssec-cds</strong></span>.
    </p>
Tinderbox User's avatar
Tinderbox User committed
95
    <p>
Tinderbox User's avatar
Tinderbox User committed
96 97 98 99 100 101
      The <span class="command"><strong>dnssec-cds</strong></span> command 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).
    </p>
Tinderbox User's avatar
Tinderbox User committed
102
    <p>
103 104 105 106 107 108
      For protection against replay attacks, the signatures on the
      child records must not be older than they were on a previous run
      of <span class="command"><strong>dnssec-cds</strong></span>. This time is obtained from the
      modification time of the <code class="filename">dsset-</code> file, or
      from the <code class="option">-s</code> option.
    </p>
Tinderbox User's avatar
Tinderbox User committed
109
    <p>
110 111 112 113 114
      To protect against breaking the delegation,
      <span class="command"><strong>dnssec-cds</strong></span> 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.
    </p>
Tinderbox User's avatar
Tinderbox User committed
115
    <p>
116 117 118 119 120 121 122
      By default, replacement DS records are written to the standard
      output; with the <code class="option">-i</code> option 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.
    </p>
Tinderbox User's avatar
Tinderbox User committed
123
    <p>
124 125 126
      Warning: Be careful not to delete the DS records
      when <span class="command"><strong>dnssec-cds</strong></span> fails!
    </p>
Tinderbox User's avatar
Tinderbox User committed
127
    <p>
128 129 130 131 132 133
      Alternatively, <span class="command"><strong>dnssec-cds -u</strong></span> writes
      an <span class="command"><strong>nsupdate</strong></span> script to the standard output.
      You can use the <code class="option">-u</code> and <code class="option">-i</code>
      options together to maintain a <code class="filename">dsset-</code> file
      as well as emit an <span class="command"><strong>nsupdate</strong></span> script.
    </p>
Tinderbox User's avatar
Tinderbox User committed
134 135 136 137

  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
138
<a name="id-1.13.6.8"></a><h2>OPTIONS</h2>
Tinderbox User's avatar
Tinderbox User committed
139 140

    <div class="variablelist"><dl class="variablelist">
141 142
<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
143
          <p>
144 145 146 147 148
	    Specify 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.
          </p>
Tinderbox User's avatar
Tinderbox User committed
149
          <p>
Tinderbox User's avatar
Tinderbox User committed
150 151 152
	    The <em class="replaceable"><code>algorithm</code></em> 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,
153 154
	    the default is SHA-256.
          </p>
Tinderbox User's avatar
Tinderbox User committed
155
        </dd>
156
<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
157 158
<dd>
          <p>
159
            Specifies the DNS class of the zones.
Tinderbox User's avatar
Tinderbox User committed
160 161
          </p>
        </dd>
162
<dt><span class="term">-D</span></dt>
Tinderbox User's avatar
Tinderbox User committed
163 164
<dd>
          <p>
165 166 167
	    Generate DS records from CDNSKEY records if both CDS and
	    CDNSKEY records are present in the child zone. By default
	    CDS records are preferred.
Tinderbox User's avatar
Tinderbox User committed
168 169
          </p>
        </dd>
170 171
<dt><span class="term">-d <em class="replaceable"><code>path</code></em></span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
172
          <p>
173 174 175 176 177 178 179
            Location of the parent DS records.
	    The <em class="replaceable"><code>path</code></em> can be the name of a file
	    containing the DS records, or if it is a
	    directory, <span class="command"><strong>dnssec-cds</strong></span> looks for
	    a <code class="filename">dsset-</code> file for
	    the <em class="replaceable"><code>domain</code></em> inside the directory.
          </p>
Tinderbox User's avatar
Tinderbox User committed
180
          <p>
181 182 183 184 185
            To protect against replay attacks, child records are
            rejected if they were signed earlier than the modification
            time of the <code class="filename">dsset-</code> file. This can be
            adjusted with the <code class="option">-s</code> option.
          </p>
Tinderbox User's avatar
Tinderbox User committed
186
        </dd>
187 188
<dt><span class="term">-f <em class="replaceable"><code>child-file</code></em></span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
189
          <p>
190 191 192 193
	    File containing the child's CDS and/or CDNSKEY records,
	    plus its DNSKEY records and the covering RRSIG records so
	    that they can be authenticated.
          </p>
Tinderbox User's avatar
Tinderbox User committed
194
	  <p>
195 196
	    The EXAMPLES below describe how to generate this file.
	  </p>
Tinderbox User's avatar
Tinderbox User committed
197
        </dd>
198 199
<dt><span class="term">-i[<em class="replaceable"><code>extension</code></em>]</span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
200
          <p>
201 202 203
            Update the <code class="filename">dsset-</code> file in place,
            instead of writing DS records to the standard output.
          </p>
Tinderbox User's avatar
Tinderbox User committed
204
	  <p>
205 206 207 208 209 210 211 212 213
	    There must be no space between the <code class="option">-i</code> and
	    the <em class="replaceable"><code>extension</code></em>. If you provide
	    no <em class="replaceable"><code>extension</code></em> then the
	    old <code class="filename">dsset-</code> is discarded. If
	    an <em class="replaceable"><code>extension</code></em> is present, a
	    backup of the old <code class="filename">dsset-</code> file is kept
	    with the <em class="replaceable"><code>extension</code></em> appended to
	    its filename.
	  </p>
Tinderbox User's avatar
Tinderbox User committed
214
          <p>
215 216 217 218 219 220
            To protect against replay attacks, the modification time
            of the <code class="filename">dsset-</code> file is set to match
            the signature inception time of the child records,
            provided that is later than the file's current
            modification time.
          </p>
Tinderbox User's avatar
Tinderbox User committed
221
        </dd>
222 223
<dt><span class="term">-s <em class="replaceable"><code>start-time</code></em></span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
224
          <p>
225 226 227 228 229 230 231 232 233
            Specify 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 <code class="filename">dsset-</code> file 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.
	  </p>
Tinderbox User's avatar
Tinderbox User committed
234
	  <p>
235 236 237 238
            If no <em class="replaceable"><code>start-time</code></em> is specified, the
            modification time of the <code class="filename">dsset-</code> file
            is used.
          </p>
Tinderbox User's avatar
Tinderbox User committed
239
        </dd>
240
<dt><span class="term">-T <em class="replaceable"><code>ttl</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
241 242
<dd>
          <p>
243 244 245 246
            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 then the new DS records also
            have no explicit TTL.
Tinderbox User's avatar
Tinderbox User committed
247 248
          </p>
        </dd>
249 250
<dt><span class="term">-u</span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
251
          <p>
252 253 254 255
	    Write an <span class="command"><strong>nsupdate</strong></span> script to the
	    standard output, instead of printing the new DS reords.
	    The output will be empty if no change is needed.
          </p>
Tinderbox User's avatar
Tinderbox User committed
256
	  <p>
257 258 259 260 261 262
	    Note: The TTL of new records needs to be specified, either
	    in the original <code class="filename">dsset-</code> file, or with
	    the <code class="option">-T</code> option, or using
	    the <span class="command"><strong>nsupdate</strong></span> <span class="command"><strong>ttl</strong></span>
	    command.
	  </p>
Tinderbox User's avatar
Tinderbox User committed
263
        </dd>
264
<dt><span class="term">-V</span></dt>
Tinderbox User's avatar
Tinderbox User committed
265 266
<dd>
	  <p>
267
	    Print version information.
Tinderbox User's avatar
Tinderbox User committed
268 269
	  </p>
        </dd>
270
<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
271 272
<dd>
          <p>
273 274 275
            Sets the debugging level. Level 1 is intended to be
            usefully verbose for general users; higher levels are
            intended for developers.
Tinderbox User's avatar
Tinderbox User committed
276 277
          </p>
        </dd>
278
<dt><span class="term"><em class="replaceable"><code>domain</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
279 280
<dd>
          <p>
281
            The name of the delegation point / child zone apex.
Tinderbox User's avatar
Tinderbox User committed
282 283
          </p>
        </dd>
284
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
285 286 287
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
288
<a name="id-1.13.6.9"></a><h2>EXIT STATUS</h2>
Tinderbox User's avatar
Tinderbox User committed
289 290

    <p>
291 292 293
      The <span class="command"><strong>dnssec-cds</strong></span> command exits 0 on success, or
      non-zero if an error occurred.
    </p>
Tinderbox User's avatar
Tinderbox User committed
294
    <p>
295 296 297
      In the success case, the DS records might or might not need
      to be changed.
    </p>
Tinderbox User's avatar
Tinderbox User committed
298 299 300 301

  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
302
<a name="id-1.13.6.10"></a><h2>EXAMPLES</h2>
Tinderbox User's avatar
Tinderbox User committed
303 304

    <p>
305 306 307 308
      Before running <span class="command"><strong>dnssec-signzone</strong></span>, you can ensure
      that the delegations are up-to-date by running
      <span class="command"><strong>dnssec-cds</strong></span> on every <code class="filename">dsset-</code> file.
    </p>
Tinderbox User's avatar
Tinderbox User committed
309
    <p>
310 311 312 313 314 315 316 317 318 319 320 321
      To fetch the child records required by <span class="command"><strong>dnssec-cds</strong></span>
      you can invoke <span class="command"><strong>dig</strong></span> as in the script below.  It's
      okay if the <span class="command"><strong>dig</strong></span> fails since
      <span class="command"><strong>dnssec-cds</strong></span> performs all the necessary checking.
    </p>
<pre class="programlisting">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
</pre>
Tinderbox User's avatar
Tinderbox User committed
322 323

    <p>
324 325 326 327 328 329 330 331 332 333 334 335
      When the parent zone is automatically signed by
      <span class="command"><strong>named</strong></span>, you can use <span class="command"><strong>dnssec-cds</strong></span>
      with <span class="command"><strong>nsupdate</strong></span> to maintain a delegation as follows.
      The <code class="filename">dsset-</code> file allows the script to avoid
      having to fetch and validate the parent DS records, and it keeps the
      replay attack protection time.
    </p>
<pre class="programlisting">
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
dnssec-cds -u -i -f /dev/stdin -d $f $d |
nsupdate -l
</pre>
Tinderbox User's avatar
Tinderbox User committed
336 337 338
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
339
<a name="id-1.13.6.11"></a><h2>SEE ALSO</h2>
Tinderbox User's avatar
Tinderbox User committed
340 341 342 343 344 345 346 347 348 349 350 351 352 353

    <p>
      <span class="citerefentry">
        <span class="refentrytitle">dig</span>(1)
      </span>,
      <span class="citerefentry">
        <span class="refentrytitle">dnssec-settime</span>(8)
      </span>,
      <span class="citerefentry">
        <span class="refentrytitle">dnssec-signzone</span>(8)
      </span>,
      <span class="citerefentry">
        <span class="refentrytitle">nsupdate</span>(1)
      </span>,
354 355 356
      <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
      <em class="citetitle">RFC 7344</em>.
    </p>
Tinderbox User's avatar
Tinderbox User committed
357 358 359

  </div>

360 361 362 363 364 365 366
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="man.dig.html">Prev</a> </td>
367
<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch12.html">Up</a></td>
368 369 370 371 372 373 374 375 376 377 378
<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-checkds.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">dig </td>
<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
<td width="40%" align="right" valign="top"> <span class="application">dnssec-checkds</span>
</td>
</tr>
</table>
</div>
Tinderbox User's avatar
Tinderbox User committed
379
<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.14.0 (Stable Release)</p>
380 381
</body>
</html>