etc/services - sync with NetBSD-8
[minix.git] / external / bsd / bind / dist / bin / dnssec / dnssec-signzone.8
blobcec30415d94e88f215349cbd354b1fa85a8a32c5
1 .\"     $NetBSD: dnssec-signzone.8,v 1.8 2014/12/10 04:37:51 christos Exp $
2 .\"
3 .\" Copyright (C) 2004-2009, 2011-2014 Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (C) 2000-2003 Internet Software Consortium.
5 .\" 
6 .\" Permission to use, copy, modify, and/or distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\" 
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
11 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
12 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
13 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
14 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
15 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
16 .\" PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .\" Id
19 .\"
20 .hy 0
21 .ad l
22 .\"     Title: dnssec\-signzone
23 .\"    Author: 
24 .\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
25 .\"      Date: February 18, 2014
26 .\"    Manual: BIND9
27 .\"    Source: BIND9
28 .\"
29 .TH "DNSSEC\-SIGNZONE" "8" "February 18, 2014" "BIND9" "BIND9"
30 .\" disable hyphenation
31 .nh
32 .\" disable justification (adjust text to left margin only)
33 .ad l
34 .SH "NAME"
35 dnssec\-signzone \- DNSSEC zone signing tool
36 .SH "SYNOPSIS"
37 .HP 16
38 \fBdnssec\-signzone\fR [\fB\-a\fR] [\fB\-c\ \fR\fB\fIclass\fR\fR] [\fB\-d\ \fR\fB\fIdirectory\fR\fR] [\fB\-D\fR] [\fB\-E\ \fR\fB\fIengine\fR\fR] [\fB\-e\ \fR\fB\fIend\-time\fR\fR] [\fB\-f\ \fR\fB\fIoutput\-file\fR\fR] [\fB\-g\fR] [\fB\-h\fR] [\fB\-K\ \fR\fB\fIdirectory\fR\fR] [\fB\-k\ \fR\fB\fIkey\fR\fR] [\fB\-L\ \fR\fB\fIserial\fR\fR] [\fB\-l\ \fR\fB\fIdomain\fR\fR] [\fB\-M\ \fR\fB\fIdomain\fR\fR] [\fB\-i\ \fR\fB\fIinterval\fR\fR] [\fB\-I\ \fR\fB\fIinput\-format\fR\fR] [\fB\-j\ \fR\fB\fIjitter\fR\fR] [\fB\-N\ \fR\fB\fIsoa\-serial\-format\fR\fR] [\fB\-o\ \fR\fB\fIorigin\fR\fR] [\fB\-O\ \fR\fB\fIoutput\-format\fR\fR] [\fB\-P\fR] [\fB\-p\fR] [\fB\-R\fR] [\fB\-r\ \fR\fB\fIrandomdev\fR\fR] [\fB\-S\fR] [\fB\-s\ \fR\fB\fIstart\-time\fR\fR] [\fB\-T\ \fR\fB\fIttl\fR\fR] [\fB\-t\fR] [\fB\-u\fR] [\fB\-v\ \fR\fB\fIlevel\fR\fR] [\fB\-V\fR] [\fB\-X\ \fR\fB\fIextended\ end\-time\fR\fR] [\fB\-x\fR] [\fB\-z\fR] [\fB\-3\ \fR\fB\fIsalt\fR\fR] [\fB\-H\ \fR\fB\fIiterations\fR\fR] [\fB\-A\fR] {zonefile} [key...]
39 .SH "DESCRIPTION"
40 .PP
41 \fBdnssec\-signzone\fR
42 signs a zone. It generates NSEC and RRSIG records and produces a signed version of the zone. The security status of delegations from the signed zone (that is, whether the child zones are secure or not) is determined by the presence or absence of a
43 \fIkeyset\fR
44 file for each child zone.
45 .SH "OPTIONS"
46 .PP
47 \-a
48 .RS 4
49 Verify all generated signatures.
50 .RE
51 .PP
52 \-c \fIclass\fR
53 .RS 4
54 Specifies the DNS class of the zone.
55 .RE
56 .PP
57 \-C
58 .RS 4
59 Compatibility mode: Generate a
60 \fIkeyset\-\fR\fI\fIzonename\fR\fR
61 file in addition to
62 \fIdsset\-\fR\fI\fIzonename\fR\fR
63 when signing a zone, for use by older versions of
64 \fBdnssec\-signzone\fR.
65 .RE
66 .PP
67 \-d \fIdirectory\fR
68 .RS 4
69 Look for
70 \fIdsset\-\fR
72 \fIkeyset\-\fR
73 files in
74 \fBdirectory\fR.
75 .RE
76 .PP
77 \-D
78 .RS 4
79 Output only those record types automatically managed by
80 \fBdnssec\-signzone\fR, i.e. RRSIG, NSEC, NSEC3 and NSEC3PARAM records. If smart signing (\fB\-S\fR) is used, DNSKEY records are also included. The resulting file can be included in the original zone file with
81 \fB$INCLUDE\fR. This option cannot be combined with
82 \fB\-O raw\fR,
83 \fB\-O map\fR, or serial number updating.
84 .RE
85 .PP
86 \-E \fIengine\fR
87 .RS 4
88 When applicable, specifies the hardware to use for cryptographic operations, such as a secure key store used for signing.
89 .sp
90 When BIND is built with OpenSSL PKCS#11 support, this defaults to the string "pkcs11", which identifies an OpenSSL engine that can drive a cryptographic accelerator or hardware service module. When BIND is built with native PKCS#11 cryptography (\-\-enable\-native\-pkcs11), it defaults to the path of the PKCS#11 provider library specified via "\-\-with\-pkcs11".
91 .RE
92 .PP
93 \-g
94 .RS 4
95 Generate DS records for child zones from
96 \fIdsset\-\fR
98 \fIkeyset\-\fR
99 file. Existing DS records will be removed.
102 \-K \fIdirectory\fR
103 .RS 4
104 Key repository: Specify a directory to search for DNSSEC keys. If not specified, defaults to the current directory.
107 \-k \fIkey\fR
108 .RS 4
109 Treat specified key as a key signing key ignoring any key flags. This option may be specified multiple times.
112 \-l \fIdomain\fR
113 .RS 4
114 Generate a DLV set in addition to the key (DNSKEY) and DS sets. The domain is appended to the name of the records.
117 \-M \fImaxttl\fR
118 .RS 4
119 Sets the maximum TTL for the signed zone. Any TTL higher than
120 \fImaxttl\fR
121 in the input zone will be reduced to
122 \fImaxttl\fR
123 in the output. This provides certainty as to the largest possible TTL in the signed zone, which is useful to know when rolling keys because it is the longest possible time before signatures that have been retrieved by resolvers will expire from resolver caches. Zones that are signed with this option should be configured to use a matching
124 \fBmax\-zone\-ttl\fR
126 \fInamed.conf\fR. (Note: This option is incompatible with
127 \fB\-D\fR, because it modifies non\-DNSSEC data in the output zone.)
130 \-s \fIstart\-time\fR
131 .RS 4
132 Specify the date and time when the generated RRSIG records become valid. This can be either an absolute or relative time. An absolute start time is indicated by a number in YYYYMMDDHHMMSS notation; 20000530144500 denotes 14:45:00 UTC on May 30th, 2000. A relative start time is indicated by +N, which is N seconds from the current time. If no
133 \fBstart\-time\fR
134 is specified, the current time minus 1 hour (to allow for clock skew) is used.
137 \-e \fIend\-time\fR
138 .RS 4
139 Specify the date and time when the generated RRSIG records expire. As with
140 \fBstart\-time\fR, an absolute time is indicated in YYYYMMDDHHMMSS notation. A time relative to the start time is indicated with +N, which is N seconds from the start time. A time relative to the current time is indicated with now+N. If no
141 \fBend\-time\fR
142 is specified, 30 days from the start time is used as a default.
143 \fBend\-time\fR
144 must be later than
145 \fBstart\-time\fR.
148 \-X \fIextended end\-time\fR
149 .RS 4
150 Specify the date and time when the generated RRSIG records for the DNSKEY RRset will expire. This is to be used in cases when the DNSKEY signatures need to persist longer than signatures on other records; e.g., when the private component of the KSK is kept offline and the KSK signature is to be refreshed manually.
152 As with
153 \fBstart\-time\fR, an absolute time is indicated in YYYYMMDDHHMMSS notation. A time relative to the start time is indicated with +N, which is N seconds from the start time. A time relative to the current time is indicated with now+N. If no
154 \fBextended end\-time\fR
155 is specified, the value of
156 \fBend\-time\fR
157 is used as the default. (\fBend\-time\fR, in turn, defaults to 30 days from the start time.)
158 \fBextended end\-time\fR
159 must be later than
160 \fBstart\-time\fR.
163 \-f \fIoutput\-file\fR
164 .RS 4
165 The name of the output file containing the signed zone. The default is to append
166 \fI.signed\fR
167 to the input filename. If
168 \fBoutput\-file\fR
169 is set to
170 "\-", then the signed zone is written to the standard output, with a default output format of "full".
174 .RS 4
175 Prints a short summary of the options and arguments to
176 \fBdnssec\-signzone\fR.
180 .RS 4
181 Prints version information.
184 \-i \fIinterval\fR
185 .RS 4
186 When a previously\-signed zone is passed as input, records may be resigned. The
187 \fBinterval\fR
188 option specifies the cycle interval as an offset from the current time (in seconds). If a RRSIG record expires after the cycle interval, it is retained. Otherwise, it is considered to be expiring soon, and it will be replaced.
190 The default cycle interval is one quarter of the difference between the signature end and start times. So if neither
191 \fBend\-time\fR
193 \fBstart\-time\fR
194 are specified,
195 \fBdnssec\-signzone\fR
196 generates signatures that are valid for 30 days, with a cycle interval of 7.5 days. Therefore, if any existing RRSIG records are due to expire in less than 7.5 days, they would be replaced.
199 \-I \fIinput\-format\fR
200 .RS 4
201 The format of the input zone file. Possible formats are
202 \fB"text"\fR
203 (default),
204 \fB"raw"\fR, and
205 \fB"map"\fR. This option is primarily intended to be used for dynamic signed zones so that the dumped zone file in a non\-text format containing updates can be signed directly. The use of this option does not make much sense for non\-dynamic zones.
208 \-j \fIjitter\fR
209 .RS 4
210 When signing a zone with a fixed signature lifetime, all RRSIG records issued at the time of signing expires simultaneously. If the zone is incrementally signed, i.e. a previously\-signed zone is passed as input to the signer, all expired signatures have to be regenerated at about the same time. The
211 \fBjitter\fR
212 option specifies a jitter window that will be used to randomize the signature expire time, thus spreading incremental signature regeneration over time.
214 Signature lifetime jitter also to some extent benefits validators and servers by spreading out cache expiration, i.e. if large numbers of RRSIGs don't expire at the same time from all caches there will be less congestion than if all validators need to refetch at mostly the same time.
217 \-L \fIserial\fR
218 .RS 4
219 When writing a signed zone to "raw" or "map" format, set the "source serial" value in the header to the specified serial number. (This is expected to be used primarily for testing purposes.)
222 \-n \fIncpus\fR
223 .RS 4
224 Specifies the number of threads to use. By default, one thread is started for each detected CPU.
227 \-N \fIsoa\-serial\-format\fR
228 .RS 4
229 The SOA serial number format of the signed zone. Possible formats are
230 \fB"keep"\fR
231 (default),
232 \fB"increment"\fR
234 \fB"unixtime"\fR.
235 .RS 4
237 \fB"keep"\fR
238 .RS 4
239 Do not modify the SOA serial number.
242 \fB"increment"\fR
243 .RS 4
244 Increment the SOA serial number using RFC 1982 arithmetics.
247 \fB"unixtime"\fR
248 .RS 4
249 Set the SOA serial number to the number of seconds since epoch.
254 \-o \fIorigin\fR
255 .RS 4
256 The zone origin. If not specified, the name of the zone file is assumed to be the origin.
259 \-O \fIoutput\-format\fR
260 .RS 4
261 The format of the output file containing the signed zone. Possible formats are
262 \fB"text"\fR
263 (default), which is the standard textual representation of the zone;
264 \fB"full"\fR, which is text output in a format suitable for processing by external scripts; and
265 \fB"map"\fR,
266 \fB"raw"\fR, and
267 \fB"raw=N"\fR, which store the zone in binary formats for rapid loading by
268 \fBnamed\fR.
269 \fB"raw=N"\fR
270 specifies the format version of the raw zone file: if N is 0, the raw file can be read by any version of
271 \fBnamed\fR; if N is 1, the file can be read by release 9.9.0 or higher; the default is 1.
275 .RS 4
276 Use pseudo\-random data when signing the zone. This is faster, but less secure, than using real random data. This option may be useful when signing large zones or when the entropy source is limited.
280 .RS 4
281 Disable post sign verification tests.
283 The post sign verification test ensures that for each algorithm in use there is at least one non revoked self signed KSK key, that all revoked KSK keys are self signed, and that all records in the zone are signed by the algorithm. This option skips these tests.
287 .RS 4
288 Remove signatures from keys that are no longer active.
290 Normally, when a previously\-signed zone is passed as input to the signer, and a DNSKEY record has been removed and replaced with a new one, signatures from the old key that are still within their validity period are retained. This allows the zone to continue to validate with cached copies of the old DNSKEY RRset. The
291 \fB\-Q\fR
292 forces
293 \fBdnssec\-signzone\fR
294 to remove signatures from keys that are no longer active. This enables ZSK rollover using the procedure described in RFC 4641, section 4.2.1.1 ("Pre\-Publish Key Rollover").
298 .RS 4
299 Remove signatures from keys that are no longer published.
301 This option is similar to
302 \fB\-Q\fR, except it forces
303 \fBdnssec\-signzone\fR
304 to signatures from keys that are no longer published. This enables ZSK rollover using the procedure described in RFC 4641, section 4.2.1.2 ("Double Signature Zone Signing Key Rollover").
307 \-r \fIrandomdev\fR
308 .RS 4
309 Specifies the source of randomness. If the operating system does not provide a
310 \fI/dev/random\fR
311 or equivalent device, the default source of randomness is keyboard input.
312 \fIrandomdev\fR
313 specifies the name of a character device or file containing random data to be used instead of the default. The special value
314 \fIkeyboard\fR
315 indicates that keyboard input should be used.
319 .RS 4
320 Smart signing: Instructs
321 \fBdnssec\-signzone\fR
322 to search the key repository for keys that match the zone being signed, and to include them in the zone if appropriate.
324 When a key is found, its timing metadata is examined to determine how it should be used, according to the following rules. Each successive rule takes priority over the prior ones:
325 .RS 4
327 .RS 4
328 If no timing metadata has been set for the key, the key is published in the zone and used to sign the zone.
331 .RS 4
332 If the key's publication date is set and is in the past, the key is published in the zone.
335 .RS 4
336 If the key's activation date is set and in the past, the key is published (regardless of publication date) and used to sign the zone.
339 .RS 4
340 If the key's revocation date is set and in the past, and the key is published, then the key is revoked, and the revoked key is used to sign the zone.
343 .RS 4
344 If either of the key's unpublication or deletion dates are set and in the past, the key is NOT published or used to sign the zone, regardless of any other metadata.
349 \-T \fIttl\fR
350 .RS 4
351 Specifies a TTL to be used for new DNSKEY records imported into the zone from the key repository. If not specified, the default is the TTL value from the zone's SOA record. This option is ignored when signing without
352 \fB\-S\fR, since DNSKEY records are not imported from the key repository in that case. It is also ignored if there are any pre\-existing DNSKEY records at the zone apex, in which case new records' TTL values will be set to match them, or if any of the imported DNSKEY records had a default TTL value. In the event of a a conflict between TTL values in imported keys, the shortest one is used.
356 .RS 4
357 Print statistics at completion.
361 .RS 4
362 Update NSEC/NSEC3 chain when re\-signing a previously signed zone. With this option, a zone signed with NSEC can be switched to NSEC3, or a zone signed with NSEC3 can be switch to NSEC or to NSEC3 with different parameters. Without this option,
363 \fBdnssec\-signzone\fR
364 will retain the existing chain when re\-signing.
367 \-v \fIlevel\fR
368 .RS 4
369 Sets the debugging level.
373 .RS 4
374 Only sign the DNSKEY RRset with key\-signing keys, and omit signatures from zone\-signing keys. (This is similar to the
375 \fBdnssec\-dnskey\-kskonly yes;\fR
376 zone option in
377 \fBnamed\fR.)
381 .RS 4
382 Ignore KSK flag on key when determining what to sign. This causes KSK\-flagged keys to sign all records, not just the DNSKEY RRset. (This is similar to the
383 \fBupdate\-check\-ksk no;\fR
384 zone option in
385 \fBnamed\fR.)
388 \-3 \fIsalt\fR
389 .RS 4
390 Generate an NSEC3 chain with the given hex encoded salt. A dash (\fIsalt\fR) can be used to indicate that no salt is to be used when generating the NSEC3 chain.
393 \-H \fIiterations\fR
394 .RS 4
395 When generating an NSEC3 chain, use this many iterations. The default is 10.
399 .RS 4
400 When generating an NSEC3 chain set the OPTOUT flag on all NSEC3 records and do not generate NSEC3 records for insecure delegations.
402 Using this option twice (i.e.,
403 \fB\-AA\fR) turns the OPTOUT flag off for all records. This is useful when using the
404 \fB\-u\fR
405 option to modify an NSEC3 chain which previously had OPTOUT set.
408 zonefile
409 .RS 4
410 The file containing the zone to be signed.
414 .RS 4
415 Specify which keys should be used to sign the zone. If no keys are specified, then the zone will be examined for DNSKEY records at the zone apex. If these are found and there are matching private keys, in the current directory, then these will be used for signing.
417 .SH "EXAMPLE"
419 The following command signs the
420 \fBexample.com\fR
421 zone with the DSA key generated by
422 \fBdnssec\-keygen\fR
423 (Kexample.com.+003+17247). Because the
424 \fB\-S\fR
425 option is not being used, the zone's keys must be in the master file (\fIdb.example.com\fR). This invocation looks for
426 \fIdsset\fR
427 files, in the current directory, so that DS records can be imported from them (\fB\-g\fR).
429 .RS 4
431 % dnssec\-signzone \-g \-o example.com db.example.com \\
432 Kexample.com.+003+17247
433 db.example.com.signed
438 In the above example,
439 \fBdnssec\-signzone\fR
440 creates the file
441 \fIdb.example.com.signed\fR. This file should be referenced in a zone statement in a
442 \fInamed.conf\fR
443 file.
445 This example re\-signs a previously signed zone with default parameters. The private keys are assumed to be in the current directory.
447 .RS 4
449 % cp db.example.com.signed db.example.com
450 % dnssec\-signzone \-o example.com db.example.com
451 db.example.com.signed
455 .SH "SEE ALSO"
457 \fBdnssec\-keygen\fR(8),
458 BIND 9 Administrator Reference Manual,
459 RFC 4033,
460 RFC 4641.
461 .SH "AUTHOR"
463 Internet Systems Consortium
464 .SH "COPYRIGHT"
465 Copyright \(co 2004\-2009, 2011\-2014 Internet Systems Consortium, Inc. ("ISC")
467 Copyright \(co 2000\-2003 Internet Software Consortium.