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 "—">]>
5 - Copyright (C) 2004-2009, 2011, 2013 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000-2003 Internet Software Consortium.
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.
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.
21 <!-- $Id: dnssec-signzone.docbook,v 1.52 2011/12/22 07:32:40 each Exp $ -->
22 <refentry id="man.dnssec-signzone">
24 <date>June 05, 2009</date>
28 <refentrytitle><application>dnssec-signzone</application></refentrytitle>
29 <manvolnum>8</manvolnum>
30 <refmiscinfo>BIND9</refmiscinfo>
34 <refname><application>dnssec-signzone</application></refname>
35 <refpurpose>DNSSEC zone signing tool</refpurpose>
48 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
55 <holder>Internet Software Consortium.</holder>
61 <command>dnssec-signzone</command>
62 <arg><option>-a</option></arg>
63 <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
64 <arg><option>-d <replaceable class="parameter">directory</replaceable></option></arg>
65 <arg><option>-D</option></arg>
66 <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
67 <arg><option>-e <replaceable class="parameter">end-time</replaceable></option></arg>
68 <arg><option>-f <replaceable class="parameter">output-file</replaceable></option></arg>
69 <arg><option>-g</option></arg>
70 <arg><option>-h</option></arg>
71 <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
72 <arg><option>-k <replaceable class="parameter">key</replaceable></option></arg>
73 <arg><option>-L <replaceable class="parameter">serial</replaceable></option></arg>
74 <arg><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
75 <arg><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
76 <arg><option>-I <replaceable class="parameter">input-format</replaceable></option></arg>
77 <arg><option>-j <replaceable class="parameter">jitter</replaceable></option></arg>
78 <arg><option>-N <replaceable class="parameter">soa-serial-format</replaceable></option></arg>
79 <arg><option>-o <replaceable class="parameter">origin</replaceable></option></arg>
80 <arg><option>-O <replaceable class="parameter">output-format</replaceable></option></arg>
81 <arg><option>-P</option></arg>
82 <arg><option>-p</option></arg>
83 <arg><option>-R</option></arg>
84 <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
85 <arg><option>-S</option></arg>
86 <arg><option>-s <replaceable class="parameter">start-time</replaceable></option></arg>
87 <arg><option>-T <replaceable class="parameter">ttl</replaceable></option></arg>
88 <arg><option>-t</option></arg>
89 <arg><option>-u</option></arg>
90 <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
91 <arg><option>-X <replaceable class="parameter">extended end-time</replaceable></option></arg>
92 <arg><option>-x</option></arg>
93 <arg><option>-z</option></arg>
94 <arg><option>-3 <replaceable class="parameter">salt</replaceable></option></arg>
95 <arg><option>-H <replaceable class="parameter">iterations</replaceable></option></arg>
96 <arg><option>-A</option></arg>
97 <arg choice="req">zonefile</arg>
98 <arg rep="repeat">key</arg>
103 <title>DESCRIPTION</title>
104 <para><command>dnssec-signzone</command>
105 signs a zone. It generates
106 NSEC and RRSIG records and produces a signed version of the
107 zone. The security status of delegations from the signed zone
108 (that is, whether the child zones are secure or not) is
109 determined by the presence or absence of a
110 <filename>keyset</filename> file for each child zone.
115 <title>OPTIONS</title>
122 Verify all generated signatures.
128 <term>-c <replaceable class="parameter">class</replaceable></term>
131 Specifies the DNS class of the zone.
140 Compatibility mode: Generate a
141 <filename>keyset-<replaceable>zonename</replaceable></filename>
143 <filename>dsset-<replaceable>zonename</replaceable></filename>
144 when signing a zone, for use by older versions of
145 <command>dnssec-signzone</command>.
151 <term>-d <replaceable class="parameter">directory</replaceable></term>
154 Look for <filename>dsset-</filename> or
155 <filename>keyset-</filename> files in <option>directory</option>.
164 Output only those record types automatically managed by
165 <command>dnssec-signzone</command>, i.e. RRSIG, NSEC,
166 NSEC3 and NSEC3PARAM records. If smart signing
167 (<option>-S</option>) is used, DNSKEY records are also
168 included. The resulting file can be included in the original
169 zone file with <command>$INCLUDE</command>. This option
170 cannot be combined with <option>-O raw</option> or serial
177 <term>-E <replaceable class="parameter">engine</replaceable></term>
180 Uses a crypto hardware (OpenSSL engine) for the crypto operations
181 it supports, for instance signing with private keys from
182 a secure key store. When compiled with PKCS#11 support
183 it defaults to pkcs11; the empty name resets it to no engine.
192 Generate DS records for child zones from
193 <filename>dsset-</filename> or <filename>keyset-</filename>
194 file. Existing DS records will be removed.
200 <term>-K <replaceable class="parameter">directory</replaceable></term>
203 Key repository: Specify a directory to search for DNSSEC keys.
204 If not specified, defaults to the current directory.
210 <term>-k <replaceable class="parameter">key</replaceable></term>
213 Treat specified key as a key signing key ignoring any
214 key flags. This option may be specified multiple times.
220 <term>-l <replaceable class="parameter">domain</replaceable></term>
223 Generate a DLV set in addition to the key (DNSKEY) and DS sets.
224 The domain is appended to the name of the records.
230 <term>-s <replaceable class="parameter">start-time</replaceable></term>
233 Specify the date and time when the generated RRSIG records
234 become valid. This can be either an absolute or relative
235 time. An absolute start time is indicated by a number
236 in YYYYMMDDHHMMSS notation; 20000530144500 denotes
237 14:45:00 UTC on May 30th, 2000. A relative start time is
238 indicated by +N, which is N seconds from the current time.
239 If no <option>start-time</option> is specified, the current
240 time minus 1 hour (to allow for clock skew) is used.
246 <term>-e <replaceable class="parameter">end-time</replaceable></term>
249 Specify the date and time when the generated RRSIG records
250 expire. As with <option>start-time</option>, an absolute
251 time is indicated in YYYYMMDDHHMMSS notation. A time relative
252 to the start time is indicated with +N, which is N seconds from
253 the start time. A time relative to the current time is
254 indicated with now+N. If no <option>end-time</option> is
255 specified, 30 days from the start time is used as a default.
256 <option>end-time</option> must be later than
257 <option>start-time</option>.
263 <term>-X <replaceable class="parameter">extended end-time</replaceable></term>
266 Specify the date and time when the generated RRSIG records
267 for the DNSKEY RRset will expire. This is to be used in cases
268 when the DNSKEY signatures need to persist longer than
269 signatures on other records; e.g., when the private component
270 of the KSK is kept offline and the KSK signature is to be
274 As with <option>start-time</option>, an absolute
275 time is indicated in YYYYMMDDHHMMSS notation. A time relative
276 to the start time is indicated with +N, which is N seconds from
277 the start time. A time relative to the current time is
278 indicated with now+N. If no <option>extended end-time</option> is
279 specified, the value of <option>end-time</option> is used as
280 the default. (<option>end-time</option>, in turn, defaults to
281 30 days from the start time.) <option>extended end-time</option>
282 must be later than <option>start-time</option>.
288 <term>-f <replaceable class="parameter">output-file</replaceable></term>
291 The name of the output file containing the signed zone. The
292 default is to append <filename>.signed</filename> to
293 the input filename. If <option>output-file</option> is
294 set to <literal>"-"</literal>, then the signed zone is
295 written to the standard output, with a default output
305 Prints a short summary of the options and arguments to
306 <command>dnssec-signzone</command>.
312 <term>-i <replaceable class="parameter">interval</replaceable></term>
315 When a previously-signed zone is passed as input, records
316 may be resigned. The <option>interval</option> option
317 specifies the cycle interval as an offset from the current
318 time (in seconds). If a RRSIG record expires after the
319 cycle interval, it is retained. Otherwise, it is considered
320 to be expiring soon, and it will be replaced.
323 The default cycle interval is one quarter of the difference
324 between the signature end and start times. So if neither
325 <option>end-time</option> or <option>start-time</option>
326 are specified, <command>dnssec-signzone</command>
328 signatures that are valid for 30 days, with a cycle
329 interval of 7.5 days. Therefore, if any existing RRSIG records
330 are due to expire in less than 7.5 days, they would be
337 <term>-I <replaceable class="parameter">input-format</replaceable></term>
340 The format of the input zone file.
341 Possible formats are <command>"text"</command> (default)
342 and <command>"raw"</command>.
343 This option is primarily intended to be used for dynamic
344 signed zones so that the dumped zone file in a non-text
345 format containing updates can be signed directly.
346 The use of this option does not make much sense for
353 <term>-j <replaceable class="parameter">jitter</replaceable></term>
356 When signing a zone with a fixed signature lifetime, all
357 RRSIG records issued at the time of signing expires
358 simultaneously. If the zone is incrementally signed, i.e.
359 a previously-signed zone is passed as input to the signer,
360 all expired signatures have to be regenerated at about the
361 same time. The <option>jitter</option> option specifies a
362 jitter window that will be used to randomize the signature
363 expire time, thus spreading incremental signature
364 regeneration over time.
367 Signature lifetime jitter also to some extent benefits
368 validators and servers by spreading out cache expiration,
369 i.e. if large numbers of RRSIGs don't expire at the same time
370 from all caches there will be less congestion than if all
371 validators need to refetch at mostly the same time.
377 <term>-L <replaceable class="parameter">serial</replaceable></term>
380 When writing a signed zone to 'raw' format, set the "source serial"
381 value in the header to the specified serial number. (This is
382 expected to be used primarily for testing purposes.)
388 <term>-n <replaceable class="parameter">ncpus</replaceable></term>
391 Specifies the number of threads to use. By default, one
392 thread is started for each detected CPU.
398 <term>-N <replaceable class="parameter">soa-serial-format</replaceable></term>
401 The SOA serial number format of the signed zone.
402 Possible formats are <command>"keep"</command> (default),
403 <command>"increment"</command> and
404 <command>"unixtime"</command>.
409 <term><command>"keep"</command></term>
411 <para>Do not modify the SOA serial number.</para>
416 <term><command>"increment"</command></term>
418 <para>Increment the SOA serial number using RFC 1982
424 <term><command>"unixtime"</command></term>
426 <para>Set the SOA serial number to the number of seconds
436 <term>-o <replaceable class="parameter">origin</replaceable></term>
439 The zone origin. If not specified, the name of the zone file
440 is assumed to be the origin.
446 <term>-O <replaceable class="parameter">output-format</replaceable></term>
449 The format of the output file containing the signed zone.
450 Possible formats are <command>"text"</command> (default)
451 <command>"full"</command>, which is text output in a
452 format suitable for processing by external scripts,
453 and <command>"raw"</command> or <command>"raw=N"</command>,
454 which store the zone in a binary format for rapid loading
455 by <command>named</command>. <command>"raw=N"</command>
456 specifies the format version of the raw zone file: if N
457 is 0, the raw file can be read by any version of
458 <command>named</command>; if N is 1, the file can be
459 read by release 9.9.0 or higher. The default is 1.
468 Use pseudo-random data when signing the zone. This is faster,
469 but less secure, than using real random data. This option
470 may be useful when signing large zones or when the entropy
480 Disable post sign verification tests.
483 The post sign verification test ensures that for each algorithm
484 in use there is at least one non revoked self signed KSK key,
485 that all revoked KSK keys are self signed, and that all records
486 in the zone are signed by the algorithm.
487 This option skips these tests.
496 Remove signatures from keys that are no longer active.
499 Normally, when a previously-signed zone is passed as input
500 to the signer, and a DNSKEY record has been removed and
501 replaced with a new one, signatures from the old key
502 that are still within their validity period are retained.
503 This allows the zone to continue to validate with cached
504 copies of the old DNSKEY RRset. The <option>-Q</option>
505 forces <command>dnssec-signzone</command> to remove
506 signatures from keys that are no longer active. This
507 enables ZSK rollover using the procedure described in
508 RFC 4641, section 4.2.1.1 ("Pre-Publish Key Rollover").
516 Remove signatures from keys that are no longer published.
519 This option is similar to <option>-Q</option>, except it
520 forces <command>dnssec-signzone</command> to signatures from
521 keys that are no longer published. This enables ZSK rollover
522 using the procedure described in RFC 4641, section 4.2.1.2
523 ("Double Signature Zone Signing Key Rollover").
528 <term>-r <replaceable class="parameter">randomdev</replaceable></term>
531 Specifies the source of randomness. If the operating
532 system does not provide a <filename>/dev/random</filename>
533 or equivalent device, the default source of randomness
534 is keyboard input. <filename>randomdev</filename>
536 the name of a character device or file containing random
537 data to be used instead of the default. The special value
538 <filename>keyboard</filename> indicates that keyboard
539 input should be used.
548 Smart signing: Instructs <command>dnssec-signzone</command> to
549 search the key repository for keys that match the zone being
550 signed, and to include them in the zone if appropriate.
553 When a key is found, its timing metadata is examined to
554 determine how it should be used, according to the following
555 rules. Each successive rule takes priority over the prior
562 If no timing metadata has been set for the key, the key is
563 published in the zone and used to sign the zone.
571 If the key's publication date is set and is in the past, the
572 key is published in the zone.
580 If the key's activation date is set and in the past, the
581 key is published (regardless of publication date) and
582 used to sign the zone.
590 If the key's revocation date is set and in the past, and the
591 key is published, then the key is revoked, and the revoked key
592 is used to sign the zone.
600 If either of the key's unpublication or deletion dates are set
601 and in the past, the key is NOT published or used to sign the
602 zone, regardless of any other metadata.
611 <term>-T <replaceable class="parameter">ttl</replaceable></term>
614 Specifies a TTL to be used for new DNSKEY records imported
615 into the zone from the key repository. If not
616 specified, the default is the TTL value from the zone's SOA
617 record. This option is ignored when signing without
618 <option>-S</option>, since DNSKEY records are not imported
619 from the key repository in that case. It is also ignored if
620 there are any pre-existing DNSKEY records at the zone apex,
621 in which case new records' TTL values will be set to match
622 them, or if any of the imported DNSKEY records had a default
623 TTL value. In the event of a a conflict between TTL values in
624 imported keys, the shortest one is used.
633 Print statistics at completion.
642 Update NSEC/NSEC3 chain when re-signing a previously signed
643 zone. With this option, a zone signed with NSEC can be
644 switched to NSEC3, or a zone signed with NSEC3 can
645 be switch to NSEC or to NSEC3 with different parameters.
646 Without this option, <command>dnssec-signzone</command> will
647 retain the existing chain when re-signing.
653 <term>-v <replaceable class="parameter">level</replaceable></term>
656 Sets the debugging level.
665 Only sign the DNSKEY RRset with key-signing keys, and omit
666 signatures from zone-signing keys. (This is similar to the
667 <command>dnssec-dnskey-kskonly yes;</command> zone option in
668 <command>named</command>.)
677 Ignore KSK flag on key when determining what to sign. This
678 causes KSK-flagged keys to sign all records, not just the
679 DNSKEY RRset. (This is similar to the
680 <command>update-check-ksk no;</command> zone option in
681 <command>named</command>.)
687 <term>-3 <replaceable class="parameter">salt</replaceable></term>
690 Generate an NSEC3 chain with the given hex encoded salt.
691 A dash (<replaceable class="parameter">salt</replaceable>) can
692 be used to indicate that no salt is to be used when generating the NSEC3 chain.
698 <term>-H <replaceable class="parameter">iterations</replaceable></term>
701 When generating an NSEC3 chain, use this many iterations. The
711 When generating an NSEC3 chain set the OPTOUT flag on all
712 NSEC3 records and do not generate NSEC3 records for insecure
716 Using this option twice (i.e., <option>-AA</option>)
717 turns the OPTOUT flag off for all records. This is useful
718 when using the <option>-u</option> option to modify an NSEC3
719 chain which previously had OPTOUT set.
725 <term>zonefile</term>
728 The file containing the zone to be signed.
737 Specify which keys should be used to sign the zone. If
738 no keys are specified, then the zone will be examined
739 for DNSKEY records at the zone apex. If these are found and
740 there are matching private keys, in the current directory,
741 then these will be used for signing.
750 <title>EXAMPLE</title>
752 The following command signs the <userinput>example.com</userinput>
753 zone with the DSA key generated by <command>dnssec-keygen</command>
754 (Kexample.com.+003+17247). Because the <command>-S</command> option
755 is not being used, the zone's keys must be in the master file
756 (<filename>db.example.com</filename>). This invocation looks
757 for <filename>dsset</filename> files, in the current directory,
758 so that DS records can be imported from them (<command>-g</command>).
760 <programlisting>% dnssec-signzone -g -o example.com db.example.com \
761 Kexample.com.+003+17247
762 db.example.com.signed
765 In the above example, <command>dnssec-signzone</command> creates
766 the file <filename>db.example.com.signed</filename>. This
767 file should be referenced in a zone statement in a
768 <filename>named.conf</filename> file.
771 This example re-signs a previously signed zone with default parameters.
772 The private keys are assumed to be in the current directory.
774 <programlisting>% cp db.example.com.signed db.example.com
775 % dnssec-signzone -o example.com db.example.com
776 db.example.com.signed
781 <title>SEE ALSO</title>
783 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
785 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
786 <citetitle>RFC 4033</citetitle>, <citetitle>RFC 4641</citetitle>.
791 <title>AUTHOR</title>
792 <para><corpauthor>Internet Systems Consortium</corpauthor>