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