dnssec-cds.docbook 14.3 KB
Newer Older
Evan Hunt's avatar
Evan Hunt committed
1
<!--
2
 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
Evan Hunt's avatar
Evan Hunt committed
3 4 5 6
 -
 - 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/.
7 8 9
 -
 - See the COPYRIGHT file distributed with this work for additional
 - information regarding copyright ownership.
Evan Hunt's avatar
Evan Hunt committed
10 11
-->

12
<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.dnssec-cds">
Evan Hunt's avatar
Evan Hunt committed
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
  <info>
    <date>2017-10-02</date>
  </info>
  <refentryinfo>
    <corpname>ISC</corpname>
    <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
    <author>
      <personname>Tony Finch</personname>
      <email>dot@dotat.at</email>
      <email>fanf2@cam.ac.uk</email>
      <affiliation>Cambridge University Information Services</affiliation>
      <personblurb></personblurb>
    </author>
  </refentryinfo>

  <refmeta>
    <refentrytitle><application>dnssec-cds</application></refentrytitle>
   <manvolnum>8</manvolnum>
    <refmiscinfo>BIND9</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname><application>dnssec-cds</application></refname>
    <refpurpose>change DS records for a child zone based on CDS/CDNSKEY</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
      <year>2017</year>
42
      <year>2018</year>
Evan Hunt's avatar
Evan Hunt committed
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis sepchar=" ">
      <command>dnssec-cds</command>
      <arg choice="opt" rep="repeat"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-D</option></arg>
      <arg choice="req" rep="norepeat"><option>-d <replaceable class="parameter">dsset-file</replaceable></option></arg>
      <arg choice="req" rep="norepeat"><option>-f <replaceable class="parameter">child-file</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-i</option><arg choice="opt" rep="norepeat"><replaceable class="parameter">extension</replaceable></arg></arg>
      <arg choice="opt" rep="norepeat"><option>-s <replaceable class="parameter">start-time</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">ttl</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-u</option></arg>
      <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-V</option></arg>
      <arg choice="req" rep="norepeat">domain</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsection><info><title>DESCRIPTION</title></info>

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

  </refsection>

  <refsection><info><title>OPTIONS</title></info>

    <variablelist>

      <varlistentry>
	<term>-a <replaceable class="parameter">algorithm</replaceable></term>
        <listitem>
          <para>
	    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.
          </para>
          <para>
	    The <replaceable>algorithm</replaceable> must be one of SHA-1
147
	    (SHA1), SHA-256 (SHA256), or SHA-384 (SHA384). These
Evan Hunt's avatar
Evan Hunt committed
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388
	    values are case insensitive. If no algorithm is specified,
	    the default is SHA-256.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-c <replaceable class="parameter">class</replaceable></term>
        <listitem>
          <para>
            Specifies the DNS class of the zones.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-D</term>
        <listitem>
          <para>
	    Generate DS records from CDNSKEY records if both CDS and
	    CDNSKEY records are present in the child zone. By default
	    CDS records are preferred.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-d <replaceable class="parameter">path</replaceable></term>
        <listitem>
          <para>
            Location of the parent DS records.
	    The <replaceable>path</replaceable> can be the name of a file
	    containing the DS records, or if it is a
	    directory, <command>dnssec-cds</command> looks for
	    a <filename>dsset-</filename> file for
	    the <replaceable>domain</replaceable> inside the directory.
          </para>
          <para>
            To protect against replay attacks, child records are
            rejected if they were signed earlier than the modification
            time of the <filename>dsset-</filename> file. This can be
            adjusted with the <option>-s</option> option.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-f <replaceable class="parameter">child-file</replaceable></term>
        <listitem>
          <para>
	    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.
          </para>
	  <para>
	    The EXAMPLES below describe how to generate this file.
	  </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-i<arg choice="opt" rep="norepeat"><replaceable class="parameter">extension</replaceable></arg></term>
        <listitem>
          <para>
            Update the <filename>dsset-</filename> file in place,
            instead of writing DS records to the standard output.
          </para>
	  <para>
	    There must be no space between the <option>-i</option> and
	    the <replaceable>extension</replaceable>. If you provide
	    no <replaceable>extension</replaceable> then the
	    old <filename>dsset-</filename> is discarded. If
	    an <replaceable>extension</replaceable> is present, a
	    backup of the old <filename>dsset-</filename> file is kept
	    with the <replaceable>extension</replaceable> appended to
	    its filename.
	  </para>
          <para>
            To protect against replay attacks, the modification time
            of the <filename>dsset-</filename> file is set to match
            the signature inception time of the child records,
            provided that is later than the file's current
            modification time.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-s <replaceable class="parameter">start-time</replaceable></term>
        <listitem>
          <para>
            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 <filename>dsset-</filename> 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.
	  </para>
	  <para>
            If no <replaceable>start-time</replaceable> is specified, the
            modification time of the <filename>dsset-</filename> file
            is used.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-T <replaceable class="parameter">ttl</replaceable></term>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-u</term>
        <listitem>
          <para>
	    Write an <command>nsupdate</command> script to the
	    standard output, instead of printing the new DS reords.
	    The output will be empty if no change is needed.
          </para>
	  <para>
	    Note: The TTL of new records needs to be specified, either
	    in the original <filename>dsset-</filename> file, or with
	    the <option>-T</option> option, or using
	    the <command>nsupdate</command> <command>ttl</command>
	    command.
	  </para>
        </listitem>
      </varlistentry>

      <varlistentry>
	<term>-V</term>
        <listitem>
	  <para>
	    Print version information.
	  </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-v <replaceable class="parameter">level</replaceable></term>
        <listitem>
          <para>
            Sets the debugging level. Level 1 is intended to be
            usefully verbose for general users; higher levels are
            intended for developers.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><replaceable>domain</replaceable></term>
        <listitem>
          <para>
            The name of the delegation point / child zone apex.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsection>

  <refsection><info><title>EXIT STATUS</title></info>

    <para>
      The <command>dnssec-cds</command> command exits 0 on success, or
      non-zero if an error occurred.
    </para>
    <para>
      In the success case, the DS records might or might not need
      to be changed.
    </para>

  </refsection>

  <refsection><info><title>EXAMPLES</title></info>

    <para>
      Before running <command>dnssec-signzone</command>, you can ensure
      that the delegations are up-to-date by running
      <command>dnssec-cds</command> on every <filename>dsset-</filename> file.
    </para>
    <para>
      To fetch the child records required by <command>dnssec-cds</command>
      you can invoke <command>dig</command> as in the script below.  It's
      okay if the <command>dig</command> fails since
      <command>dnssec-cds</command> performs all the necessary checking.
    </para>
<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
</programlisting>

    <para>
      When the parent zone is automatically signed by
      <command>named</command>, you can use <command>dnssec-cds</command>
      with <command>nsupdate</command> to maintain a delegation as follows.
      The <filename>dsset-</filename> file allows the script to avoid
      having to fetch and validate the parent DS records, and it keeps the
      replay attack protection time.
    </para>
<programlisting>
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
dnssec-cds -u -i -f /dev/stdin -d $f $d |
nsupdate -l
</programlisting>
  </refsection>

  <refsection><info><title>SEE ALSO</title></info>

    <para>
      <citerefentry>
        <refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>dnssec-settime</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>nsupdate</refentrytitle><manvolnum>1</manvolnum>
      </citerefentry>,
      <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
      <citetitle>RFC 7344</citetitle>.
    </para>

  </refsection>

</refentry>