2 - Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
3 - Copyright (C) 2000-2003 Internet Software Consortium.
5 - Permission to use, copy, modify, and/or distribute this software for any
6 - purpose with or without fee is hereby granted, provided that the above
7 - copyright notice and this permission notice appear in all copies.
9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 - PERFORMANCE OF THIS SOFTWARE.
17 <!-- $Id: dnssec-signzone.html,v 1.33.44.8 2009/11/07 01:56:11 tbox Exp $ -->
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <title>dnssec-signzone</title>
22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="man.dnssec-signzone"></a><div class="titlepage"></div>
26 <div class="refnamediv">
28 <p><span class="application">dnssec-signzone</span> — DNSSEC zone signing tool</p>
30 <div class="refsynopsisdiv">
32 <div class="cmdsynopsis"><p><code class="command">dnssec-signzone</code> [<code class="option">-a</code>] [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] [<code class="option">-d <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-e <em class="replaceable"><code>end-time</code></em></code>] [<code class="option">-f <em class="replaceable"><code>output-file</code></em></code>] [<code class="option">-g</code>] [<code class="option">-h</code>] [<code class="option">-k <em class="replaceable"><code>key</code></em></code>] [<code class="option">-l <em class="replaceable"><code>domain</code></em></code>] [<code class="option">-i <em class="replaceable"><code>interval</code></em></code>] [<code class="option">-I <em class="replaceable"><code>input-format</code></em></code>] [<code class="option">-j <em class="replaceable"><code>jitter</code></em></code>] [<code class="option">-N <em class="replaceable"><code>soa-serial-format</code></em></code>] [<code class="option">-o <em class="replaceable"><code>origin</code></em></code>] [<code class="option">-O <em class="replaceable"><code>output-format</code></em></code>] [<code class="option">-p</code>] [<code class="option">-P</code>] [<code class="option">-r <em class="replaceable"><code>randomdev</code></em></code>] [<code class="option">-s <em class="replaceable"><code>start-time</code></em></code>] [<code class="option">-t</code>] [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] [<code class="option">-z</code>] [<code class="option">-3 <em class="replaceable"><code>salt</code></em></code>] [<code class="option">-H <em class="replaceable"><code>iterations</code></em></code>] [<code class="option">-A</code>] {zonefile} [key...]</p></div>
34 <div class="refsect1" lang="en">
35 <a name="id2543558"></a><h2>DESCRIPTION</h2>
36 <p><span><strong class="command">dnssec-signzone</strong></span>
37 signs a zone. It generates
38 NSEC and RRSIG records and produces a signed version of the
39 zone. It also generates a <code class="filename">keyset-</code> file containing
40 the key-signing keys for the zone, and if signing a zone which
41 contains delegations, it can optionally generate DS records for
42 the child zones from their <code class="filename">keyset-</code> files.
45 <div class="refsect1" lang="en">
46 <a name="id2543576"></a><h2>OPTIONS</h2>
47 <div class="variablelist"><dl>
48 <dt><span class="term">-a</span></dt>
50 Verify all generated signatures.
52 <dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
54 Specifies the DNS class of the zone.
56 <dt><span class="term">-k <em class="replaceable"><code>key</code></em></span></dt>
58 Treat specified key as a key signing key ignoring any
59 key flags. This option may be specified multiple times.
61 <dt><span class="term">-l <em class="replaceable"><code>domain</code></em></span></dt>
63 Generate a DLV set in addition to the key (DNSKEY) and DS sets.
64 The domain is appended to the name of the records.
66 <dt><span class="term">-d <em class="replaceable"><code>directory</code></em></span></dt>
68 Look for <code class="filename">keyset</code> files in
69 <code class="option">directory</code> as the directory
71 <dt><span class="term">-g</span></dt>
73 If the zone contains any delegations, and there are
74 <code class="filename">keyset-</code> files for any of the child zones,
75 then DS records for the child zones will be generated from the
76 keys in those files. Existing DS records will be removed.
78 <dt><span class="term">-s <em class="replaceable"><code>start-time</code></em></span></dt>
80 Specify the date and time when the generated RRSIG records
81 become valid. This can be either an absolute or relative
82 time. An absolute start time is indicated by a number
83 in YYYYMMDDHHMMSS notation; 20000530144500 denotes
84 14:45:00 UTC on May 30th, 2000. A relative start time is
85 indicated by +N, which is N seconds from the current time.
86 If no <code class="option">start-time</code> is specified, the current
87 time minus 1 hour (to allow for clock skew) is used.
89 <dt><span class="term">-e <em class="replaceable"><code>end-time</code></em></span></dt>
91 Specify the date and time when the generated RRSIG records
92 expire. As with <code class="option">start-time</code>, an absolute
93 time is indicated in YYYYMMDDHHMMSS notation. A time relative
94 to the start time is indicated with +N, which is N seconds from
95 the start time. A time relative to the current time is
96 indicated with now+N. If no <code class="option">end-time</code> is
97 specified, 30 days from the start time is used as a default.
99 <dt><span class="term">-f <em class="replaceable"><code>output-file</code></em></span></dt>
101 The name of the output file containing the signed zone. The
102 default is to append <code class="filename">.signed</code> to
106 <dt><span class="term">-h</span></dt>
108 Prints a short summary of the options and arguments to
109 <span><strong class="command">dnssec-signzone</strong></span>.
111 <dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt>
114 When a previously-signed zone is passed as input, records
115 may be resigned. The <code class="option">interval</code> option
116 specifies the cycle interval as an offset from the current
117 time (in seconds). If a RRSIG record expires after the
118 cycle interval, it is retained. Otherwise, it is considered
119 to be expiring soon, and it will be replaced.
122 The default cycle interval is one quarter of the difference
123 between the signature end and start times. So if neither
124 <code class="option">end-time</code> or <code class="option">start-time</code>
125 are specified, <span><strong class="command">dnssec-signzone</strong></span>
127 signatures that are valid for 30 days, with a cycle
128 interval of 7.5 days. Therefore, if any existing RRSIG records
129 are due to expire in less than 7.5 days, they would be
133 <dt><span class="term">-I <em class="replaceable"><code>input-format</code></em></span></dt>
135 The format of the input zone file.
136 Possible formats are <span><strong class="command">"text"</strong></span> (default)
137 and <span><strong class="command">"raw"</strong></span>.
138 This option is primarily intended to be used for dynamic
139 signed zones so that the dumped zone file in a non-text
140 format containing updates can be signed directly.
141 The use of this option does not make much sense for
144 <dt><span class="term">-j <em class="replaceable"><code>jitter</code></em></span></dt>
147 When signing a zone with a fixed signature lifetime, all
148 RRSIG records issued at the time of signing expires
149 simultaneously. If the zone is incrementally signed, i.e.
150 a previously-signed zone is passed as input to the signer,
151 all expired signatures have to be regenerated at about the
152 same time. The <code class="option">jitter</code> option specifies a
153 jitter window that will be used to randomize the signature
154 expire time, thus spreading incremental signature
155 regeneration over time.
158 Signature lifetime jitter also to some extent benefits
159 validators and servers by spreading out cache expiration,
160 i.e. if large numbers of RRSIGs don't expire at the same time
161 from all caches there will be less congestion than if all
162 validators need to refetch at mostly the same time.
165 <dt><span class="term">-n <em class="replaceable"><code>ncpus</code></em></span></dt>
167 Specifies the number of threads to use. By default, one
168 thread is started for each detected CPU.
170 <dt><span class="term">-N <em class="replaceable"><code>soa-serial-format</code></em></span></dt>
173 The SOA serial number format of the signed zone.
174 Possible formats are <span><strong class="command">"keep"</strong></span> (default),
175 <span><strong class="command">"increment"</strong></span> and
176 <span><strong class="command">"unixtime"</strong></span>.
178 <div class="variablelist"><dl>
179 <dt><span class="term"><span><strong class="command">"keep"</strong></span></span></dt>
180 <dd><p>Do not modify the SOA serial number.</p></dd>
181 <dt><span class="term"><span><strong class="command">"increment"</strong></span></span></dt>
182 <dd><p>Increment the SOA serial number using RFC 1982
183 arithmetics.</p></dd>
184 <dt><span class="term"><span><strong class="command">"unixtime"</strong></span></span></dt>
185 <dd><p>Set the SOA serial number to the number of seconds
186 since epoch.</p></dd>
189 <dt><span class="term">-o <em class="replaceable"><code>origin</code></em></span></dt>
191 The zone origin. If not specified, the name of the zone file
192 is assumed to be the origin.
194 <dt><span class="term">-O <em class="replaceable"><code>output-format</code></em></span></dt>
196 The format of the output file containing the signed zone.
197 Possible formats are <span><strong class="command">"text"</strong></span> (default)
198 and <span><strong class="command">"raw"</strong></span>.
200 <dt><span class="term">-p</span></dt>
202 Use pseudo-random data when signing the zone. This is faster,
203 but less secure, than using real random data. This option
204 may be useful when signing large zones or when the entropy
207 <dt><span class="term">-P</span></dt>
210 Disable post sign verification tests.
213 The post sign verification test ensures that for each algorithm
214 in use there is at least one non revoked self signed KSK key,
215 that all revoked KSK keys are self signed, and that all records
216 in the zone are signed by the algorithm.
217 This option skips these tests.
220 <dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt>
222 Specifies the source of randomness. If the operating
223 system does not provide a <code class="filename">/dev/random</code>
224 or equivalent device, the default source of randomness
225 is keyboard input. <code class="filename">randomdev</code>
227 the name of a character device or file containing random
228 data to be used instead of the default. The special value
229 <code class="filename">keyboard</code> indicates that keyboard
230 input should be used.
232 <dt><span class="term">-t</span></dt>
234 Print statistics at completion.
236 <dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
238 Sets the debugging level.
240 <dt><span class="term">-z</span></dt>
242 Ignore KSK flag on key when determining what to sign.
244 <dt><span class="term">-3 <em class="replaceable"><code>salt</code></em></span></dt>
246 Generate a NSEC3 chain with the given hex encoded salt.
247 A dash (<em class="replaceable"><code>salt</code></em>) can
248 be used to indicate that no salt is to be used when generating the NSEC3 chain.
250 <dt><span class="term">-H <em class="replaceable"><code>iterations</code></em></span></dt>
252 When generating a NSEC3 chain use this many interations. The
255 <dt><span class="term">-A</span></dt>
257 When generating a NSEC3 chain set the OPTOUT flag on all
258 NSEC3 records and do not generate NSEC3 records for insecure
261 <dt><span class="term">zonefile</span></dt>
263 The file containing the zone to be signed.
265 <dt><span class="term">key</span></dt>
267 Specify which keys should be used to sign the zone. If
268 no keys are specified, then the zone will be examined
269 for DNSKEY records at the zone apex. If these are found and
270 there are matching private keys, in the current directory,
271 then these will be used for signing.
275 <div class="refsect1" lang="en">
276 <a name="id2544503"></a><h2>EXAMPLE</h2>
278 The following command signs the <strong class="userinput"><code>example.com</code></strong>
279 zone with the DSA key generated by <span><strong class="command">dnssec-keygen</strong></span>
280 (Kexample.com.+003+17247). The zone's keys must be in the master
281 file (<code class="filename">db.example.com</code>). This invocation looks
282 for <code class="filename">keyset</code> files, in the current directory,
283 so that DS records can be generated from them (<span><strong class="command">-g</strong></span>).
285 <pre class="programlisting">% dnssec-signzone -g -o example.com db.example.com \
286 Kexample.com.+003+17247
287 db.example.com.signed
290 In the above example, <span><strong class="command">dnssec-signzone</strong></span> creates
291 the file <code class="filename">db.example.com.signed</code>. This
292 file should be referenced in a zone statement in a
293 <code class="filename">named.conf</code> file.
296 This example re-signs a previously signed zone with default parameters.
297 The private keys are assumed to be in the current directory.
299 <pre class="programlisting">% cp db.example.com.signed db.example.com
300 % dnssec-signzone -o example.com db.example.com
301 db.example.com.signed
304 <div class="refsect1" lang="en">
305 <a name="id2544554"></a><h2>KNOWN BUGS</h2>
307 <span><strong class="command">dnssec-signzone</strong></span> was designed so that it could
308 sign a zone partially, using only a subset of the DNSSEC keys
309 needed to produce a fully-signed zone. This permits a zone
310 administrator, for example, to sign a zone with one key on one
311 machine, move the resulting partially-signed zone to a second
312 machine, and sign it again with a second key.
315 An unfortunate side-effect of this flexibility is that
316 <span><strong class="command">dnssec-signzone</strong></span> does not check to make sure
317 it's signing a zone with any valid keys at all. An attempt to
318 sign a zone without any keys will appear to succeed, producing
319 a "signed" zone with no signatures. There is no warning issued
320 when a zone is not fully signed.
323 This will be corrected in a future release. In the meantime, ISC
324 recommends examining the output of <span><strong class="command">dnssec-signzone</strong></span>
325 to confirm that the zone is properly signed by all keys before
329 <div class="refsect1" lang="en">
330 <a name="id2544716"></a><h2>SEE ALSO</h2>
331 <p><span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>,
332 <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
333 <em class="citetitle">RFC 4033</em>.
336 <div class="refsect1" lang="en">
337 <a name="id2544741"></a><h2>AUTHOR</h2>
338 <p><span class="corpauthor">Internet Systems Consortium</span>