contrib/bind9/bin/dnssec/dnssec-signzone.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004-2009, 2012  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000-2003  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and/or distribute this software for any
   9  - purpose with or without fee is hereby granted, provided that the above
  10  - copyright notice and this permission notice appear in all copies.
  11  -
  12  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18  - PERFORMANCE OF THIS SOFTWARE.
  19 -->
  20
  21 <!-- $Id$ -->
  22 <refentry id="man.dnssec-signzone">
  23   <refentryinfo>
  24     <date>June 08, 2009</date>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle><application>dnssec-signzone</application></refentrytitle>
  29    <manvolnum>8</manvolnum>
  30     <refmiscinfo>BIND9</refmiscinfo>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname><application>dnssec-signzone</application></refname>
  35     <refpurpose>DNSSEC zone signing tool</refpurpose>
  36   </refnamediv>
  37
  38   <docinfo>
  39     <copyright>
  40       <year>2004</year>
  41       <year>2005</year>
  42       <year>2006</year>
  43       <year>2007</year>
  44       <year>2008</year>
  45       <year>2009</year>
  46       <year>2012</year>
  47       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  48     </copyright>
  49     <copyright>
  50       <year>2000</year>
  51       <year>2001</year>
  52       <year>2002</year>
  53       <year>2003</year>
  54       <holder>Internet Software Consortium.</holder>
  55     </copyright>
  56   </docinfo>
  57
  58   <refsynopsisdiv>
  59     <cmdsynopsis>
  60       <command>dnssec-signzone</command>
  61       <arg><option>-a</option></arg>
  62       <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
  63       <arg><option>-d <replaceable class="parameter">directory</replaceable></option></arg>
  64       <arg><option>-e <replaceable class="parameter">end-time</replaceable></option></arg>
  65       <arg><option>-f <replaceable class="parameter">output-file</replaceable></option></arg>
  66       <arg><option>-g</option></arg>
  67       <arg><option>-h</option></arg>
  68       <arg><option>-k <replaceable class="parameter">key</replaceable></option></arg>
  69       <arg><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
  70       <arg><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
  71       <arg><option>-I <replaceable class="parameter">input-format</replaceable></option></arg>
  72       <arg><option>-j <replaceable class="parameter">jitter</replaceable></option></arg>
  73       <arg><option>-N <replaceable class="parameter">soa-serial-format</replaceable></option></arg>
  74       <arg><option>-o <replaceable class="parameter">origin</replaceable></option></arg>
  75       <arg><option>-O <replaceable class="parameter">output-format</replaceable></option></arg>
  76       <arg><option>-p</option></arg>
  77       <arg><option>-P</option></arg>
  78       <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
  79       <arg><option>-s <replaceable class="parameter">start-time</replaceable></option></arg>
  80       <arg><option>-t</option></arg>
  81       <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
  82       <arg><option>-z</option></arg>
  83       <arg><option>-3 <replaceable class="parameter">salt</replaceable></option></arg>
  84       <arg><option>-H <replaceable class="parameter">iterations</replaceable></option></arg>
  85       <arg><option>-A</option></arg>
  86       <arg choice="req">zonefile</arg>
  87       <arg rep="repeat">key</arg>
  88     </cmdsynopsis>
  89   </refsynopsisdiv>
  90
  91   <refsect1>
  92     <title>DESCRIPTION</title>
  93     <para><command>dnssec-signzone</command>
  94       signs a zone.  It generates
  95       NSEC and RRSIG records and produces a signed version of the
  96       zone.  It also generates a <filename>keyset-</filename> file containing
  97       the key-signing keys for the zone, and if signing a zone which
  98       contains delegations, it can optionally generate DS records for
  99       the child zones from their <filename>keyset-</filename> files.
 100     </para>
 101   </refsect1>
 102
 103   <refsect1>
 104     <title>OPTIONS</title>
 105
 106     <variablelist>
 107       <varlistentry>
 108         <term>-a</term>
 109         <listitem>
 110           <para>
 111             Verify all generated signatures.
 112           </para>
 113         </listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term>-c <replaceable class="parameter">class</replaceable></term>
 118         <listitem>
 119           <para>
 120             Specifies the DNS class of the zone.
 121           </para>
 122         </listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term>-k <replaceable class="parameter">key</replaceable></term>
 127         <listitem>
 128           <para>
 129             Treat specified key as a key signing key ignoring any
 130             key flags.  This option may be specified multiple times.
 131           </para>
 132         </listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term>-l <replaceable class="parameter">domain</replaceable></term>
 137         <listitem>
 138           <para>
 139             Generate a DLV set in addition to the key (DNSKEY) and DS sets.
 140             The domain is appended to the name of the records.
 141           </para>
 142         </listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term>-d <replaceable class="parameter">directory</replaceable></term>
 147         <listitem>
 148           <para>
 149             Look for <filename>keyset</filename> files in
 150             <option>directory</option> as the directory
 151           </para>
 152         </listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term>-g</term>
 157         <listitem>
 158           <para>
 159             If the zone contains any delegations, and there are
 160             <filename>keyset-</filename> files for any of the child zones,
 161             then DS records for the child zones will be generated from the
 162             keys in those files.  Existing DS records will be removed.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term>-s <replaceable class="parameter">start-time</replaceable></term>
 169         <listitem>
 170           <para>
 171             Specify the date and time when the generated RRSIG records
 172             become valid.  This can be either an absolute or relative
 173             time.  An absolute start time is indicated by a number
 174             in YYYYMMDDHHMMSS notation; 20000530144500 denotes
 175             14:45:00 UTC on May 30th, 2000.  A relative start time is
 176             indicated by +N, which is N seconds from the current time.
 177             If no <option>start-time</option> is specified, the current
 178             time minus 1 hour (to allow for clock skew) is used.
 179           </para>
 180         </listitem>
 181       </varlistentry>
 182
 183       <varlistentry>
 184         <term>-e <replaceable class="parameter">end-time</replaceable></term>
 185         <listitem>
 186           <para>
 187             Specify the date and time when the generated RRSIG records
 188             expire.  As with <option>start-time</option>, an absolute
 189             time is indicated in YYYYMMDDHHMMSS notation.  A time relative
 190             to the start time is indicated with +N, which is N seconds from
 191             the start time.  A time relative to the current time is
 192             indicated with now+N.  If no <option>end-time</option> is
 193             specified, 30 days from the start time is used as a default.
 194           </para>
 195         </listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term>-f <replaceable class="parameter">output-file</replaceable></term>
 200         <listitem>
 201           <para>
 202             The name of the output file containing the signed zone.  The
 203             default is to append <filename>.signed</filename> to
 204             the
 205             input filename.
 206           </para>
 207         </listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term>-h</term>
 212         <listitem>
 213           <para>
 214             Prints a short summary of the options and arguments to
 215             <command>dnssec-signzone</command>.
 216           </para>
 217         </listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221         <term>-i <replaceable class="parameter">interval</replaceable></term>
 222         <listitem>
 223           <para>
 224             When a previously-signed zone is passed as input, records
 225             may be resigned.  The <option>interval</option> option
 226             specifies the cycle interval as an offset from the current
 227             time (in seconds).  If a RRSIG record expires after the
 228             cycle interval, it is retained.  Otherwise, it is considered
 229             to be expiring soon, and it will be replaced.
 230           </para>
 231           <para>
 232             The default cycle interval is one quarter of the difference
 233             between the signature end and start times.  So if neither
 234             <option>end-time</option> or <option>start-time</option>
 235             are specified, <command>dnssec-signzone</command>
 236             generates
 237             signatures that are valid for 30 days, with a cycle
 238             interval of 7.5 days.  Therefore, if any existing RRSIG records
 239             are due to expire in less than 7.5 days, they would be
 240             replaced.
 241           </para>
 242         </listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term>-I <replaceable class="parameter">input-format</replaceable></term>
 247         <listitem>
 248           <para>
 249             The format of the input zone file.
 250             Possible formats are <command>"text"</command> (default)
 251             and <command>"raw"</command>.
 252             This option is primarily intended to be used for dynamic
 253             signed zones so that the dumped zone file in a non-text
 254             format containing updates can be signed directly.
 255             The use of this option does not make much sense for
 256             non-dynamic zones.
 257           </para>
 258         </listitem>
 259       </varlistentry>
 260
 261       <varlistentry>
 262         <term>-j <replaceable class="parameter">jitter</replaceable></term>
 263         <listitem>
 264           <para>
 265             When signing a zone with a fixed signature lifetime, all
 266             RRSIG records issued at the time of signing expires
 267             simultaneously.  If the zone is incrementally signed, i.e.
 268             a previously-signed zone is passed as input to the signer,
 269             all expired signatures have to be regenerated at about the
 270             same time.  The <option>jitter</option> option specifies a
 271             jitter window that will be used to randomize the signature
 272             expire time, thus spreading incremental signature
 273             regeneration over time.
 274           </para>
 275           <para>
 276             Signature lifetime jitter also to some extent benefits
 277             validators and servers by spreading out cache expiration,
 278             i.e. if large numbers of RRSIGs don't expire at the same time
 279             from all caches there will be less congestion than if all
 280             validators need to refetch at mostly the same time.
 281           </para>
 282         </listitem>
 283       </varlistentry>
 284
 285       <varlistentry>
 286         <term>-n <replaceable class="parameter">ncpus</replaceable></term>
 287         <listitem>
 288           <para>
 289             Specifies the number of threads to use.  By default, one
 290             thread is started for each detected CPU.
 291           </para>
 292         </listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term>-N <replaceable class="parameter">soa-serial-format</replaceable></term>
 297         <listitem>
 298           <para>
 299             The SOA serial number format of the signed zone.
 300             Possible formats are <command>"keep"</command> (default),
 301             <command>"increment"</command> and
 302             <command>"unixtime"</command>.
 303           </para>
 304
 305           <variablelist>
 306             <varlistentry>
 307               <term><command>"keep"</command></term>
 308               <listitem>
 309                 <para>Do not modify the SOA serial number.</para>
 310               </listitem>
 311             </varlistentry>
 312
 313             <varlistentry>
 314               <term><command>"increment"</command></term>
 315               <listitem>
 316                 <para>Increment the SOA serial number using RFC 1982
 317                       arithmetics.</para>
 318               </listitem>
 319             </varlistentry>
 320
 321             <varlistentry>
 322               <term><command>"unixtime"</command></term>
 323               <listitem>
 324                 <para>Set the SOA serial number to the number of seconds
 325                 since epoch.</para>
 326               </listitem>
 327             </varlistentry>
 328          </variablelist>
 329
 330         </listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term>-o <replaceable class="parameter">origin</replaceable></term>
 335         <listitem>
 336           <para>
 337             The zone origin.  If not specified, the name of the zone file
 338             is assumed to be the origin.
 339           </para>
 340         </listitem>
 341       </varlistentry>
 342
 343       <varlistentry>
 344         <term>-O <replaceable class="parameter">output-format</replaceable></term>
 345         <listitem>
 346           <para>
 347             The format of the output file containing the signed zone.
 348             Possible formats are <command>"text"</command> (default)
 349             and <command>"raw"</command>.
 350           </para>
 351         </listitem>
 352       </varlistentry>
 353
 354       <varlistentry>
 355         <term>-p</term>
 356         <listitem>
 357           <para>
 358             Use pseudo-random data when signing the zone.  This is faster,
 359             but less secure, than using real random data.  This option
 360             may be useful when signing large zones or when the entropy
 361             source is limited.
 362           </para>
 363         </listitem>
 364       </varlistentry>
 365
 366       <varlistentry>
 367         <term>-P</term>
 368         <listitem>
 369           <para>
 370             Disable post sign verification tests.
 371           </para>
 372           <para>
 373             The post sign verification test ensures that for each algorithm
 374             in use there is at least one non revoked self signed KSK key,
 375             that all revoked KSK keys are self signed, and that all records
 376             in the zone are signed by the algorithm.
 377             This option skips these tests.
 378           </para>
 379         </listitem>
 380       </varlistentry>
 381
 382       <varlistentry>
 383         <term>-r <replaceable class="parameter">randomdev</replaceable></term>
 384         <listitem>
 385           <para>
 386             Specifies the source of randomness.  If the operating
 387             system does not provide a <filename>/dev/random</filename>
 388             or equivalent device, the default source of randomness
 389             is keyboard input.  <filename>randomdev</filename>
 390             specifies
 391             the name of a character device or file containing random
 392             data to be used instead of the default.  The special value
 393             <filename>keyboard</filename> indicates that keyboard
 394             input should be used.
 395           </para>
 396         </listitem>
 397       </varlistentry>
 398
 399       <varlistentry>
 400         <term>-t</term>
 401         <listitem>
 402           <para>
 403             Print statistics at completion.
 404           </para>
 405         </listitem>
 406       </varlistentry>
 407
 408       <varlistentry>
 409         <term>-v <replaceable class="parameter">level</replaceable></term>
 410         <listitem>
 411           <para>
 412             Sets the debugging level.
 413           </para>
 414         </listitem>
 415       </varlistentry>
 416
 417       <varlistentry>
 418         <term>-z</term>
 419         <listitem>
 420           <para>
 421             Ignore KSK flag on key when determining what to sign.
 422           </para>
 423         </listitem>
 424       </varlistentry>
 425
 426       <varlistentry>
 427         <term>-3 <replaceable class="parameter">salt</replaceable></term>
 428         <listitem>
 429           <para>
 430             Generate a NSEC3 chain with the given hex encoded salt.
 431             A dash (<replaceable class="parameter">salt</replaceable>) can
 432             be used to indicate that no salt is to be used when generating                  the NSEC3 chain.
 433           </para>
 434         </listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term>-H <replaceable class="parameter">iterations</replaceable></term>
 439         <listitem>
 440           <para>
 441             When generating a NSEC3 chain use this many interations.  The
 442             default is 100.
 443           </para>
 444         </listitem>
 445       </varlistentry>
 446
 447       <varlistentry>
 448         <term>-A</term>
 449         <listitem>
 450           <para>
 451             When generating a NSEC3 chain set the OPTOUT flag on all
 452             NSEC3 records and do not generate NSEC3 records for insecure
 453             delegations.
 454           </para>
 455         </listitem>
 456       </varlistentry>
 457
 458       <varlistentry>
 459         <term>zonefile</term>
 460         <listitem>
 461           <para>
 462             The file containing the zone to be signed.
 463           </para>
 464         </listitem>
 465       </varlistentry>
 466
 467       <varlistentry>
 468         <term>key</term>
 469         <listitem>
 470           <para>
 471             Specify which keys should be used to sign the zone.  If
 472             no keys are specified, then the zone will be examined
 473             for DNSKEY records at the zone apex.  If these are found and
 474             there are matching private keys, in the current directory,
 475             then these will be used for signing.
 476           </para>
 477         </listitem>
 478       </varlistentry>
 479
 480     </variablelist>
 481   </refsect1>
 482
 483   <refsect1>
 484     <title>EXAMPLE</title>
 485     <para>
 486       The following command signs the <userinput>example.com</userinput>
 487       zone with the DSA key generated by <command>dnssec-keygen</command>
 488       (Kexample.com.+003+17247).  The zone's keys must be in the master
 489       file (<filename>db.example.com</filename>).  This invocation looks
 490       for <filename>keyset</filename> files, in the current directory,
 491       so that DS records can be generated from them (<command>-g</command>).
 492     </para>
 493 <programlisting>% dnssec-signzone -g -o example.com db.example.com \
 494 Kexample.com.+003+17247
 495 db.example.com.signed
 496 %</programlisting>
 497     <para>
 498       In the above example, <command>dnssec-signzone</command> creates
 499       the file <filename>db.example.com.signed</filename>.  This
 500       file should be referenced in a zone statement in a
 501       <filename>named.conf</filename> file.
 502     </para>
 503     <para>
 504       This example re-signs a previously signed zone with default parameters.
 505       The private keys are assumed to be in the current directory.
 506     </para>
 507 <programlisting>% cp db.example.com.signed db.example.com
 508 % dnssec-signzone -o example.com db.example.com
 509 db.example.com.signed
 510 %</programlisting>
 511   </refsect1>
 512
 513   <refsect1>
 514     <title>KNOWN BUGS</title>
 515     <para>
 516         <command>dnssec-signzone</command> was designed so that it could
 517         sign a zone partially, using only a subset of the DNSSEC keys
 518         needed to produce a fully-signed zone.  This permits a zone
 519         administrator, for example, to sign a zone with one key on one
 520         machine, move the resulting partially-signed zone to a second
 521         machine, and sign it again with a second key.
 522     </para>
 523     <para>
 524         An unfortunate side-effect of this flexibility is that
 525         <command>dnssec-signzone</command> does not check to make sure
 526         it's signing a zone with any valid keys at all.  An attempt to
 527         sign a zone without any keys will appear to succeed, producing
 528         a "signed" zone with no signatures.  There is no warning issued
 529         when a zone is not fully signed.
 530     </para>
 531
 532     <para>
 533         This will be corrected in a future release.  In the meantime, ISC
 534         recommends examining the output of <command>dnssec-signzone</command>
 535         to confirm that the zone is properly signed by all keys before
 536         using it.
 537     </para>
 538   </refsect1>
 539
 540   <refsect1>
 541     <title>SEE ALSO</title>
 542     <para><citerefentry>
 543         <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
 544       </citerefentry>,
 545       <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
 546       <citetitle>RFC 4033</citetitle>.
 547     </para>
 548   </refsect1>
 549
 550   <refsect1>
 551     <title>AUTHOR</title>
 552     <para><corpauthor>Internet Systems Consortium</corpauthor>
 553     </para>
 554   </refsect1>
 555
 556 </refentry><!--
 557  - Local variables:
 558  - mode: sgml
 559  - End:
 560 -->