1ZONESIGNER(1) User Contributed Perl Documentation ZONESIGNER(1)
2
6 zonesigner - Generates encryption keys and signs a DNS zone
7
9 zonesigner [options] <zone-file> <signed-zone-file>
10 # get started immediately examples:
12 # first run on a zone for example.com:
14 zonesigner -genkeys -endtime +2678400 example.com
15 # future runs before expiration time (reuses the same keys):
17 zonesigner -endtime +2678400 example.com
18
20 This script combines into a single command many actions that are
21 required to sign a DNS zone. It generates the required KSK and ZSK
22 keys, adds the key data to a zone record file, signs the zone file, and
23 runs checks to ensure that everything worked properly. It also keeps
24 records about the keys and how the zone was signed in order to facili‐
25 tate re-signing of the zone in the future.
26 The zonesigner-specific zone-signing records are kept in keyrec files.
28 Using keyrec files, defined and maintained by DNSSEC-Tools, zonesigner
29 can automatically gather many of the options used to previously sign
30 and generate a zone and its keys. This allows the zone to be main‐
31 tained using the same key lengths and expiration times, for example,
32 without an administrator needing to manually track these fields.
33
35 The following are examples that will allow a quick start on using zone‐
36 signer:
37 first run on example.com
39 The following command will generate keys and sign the zone file for
40 example.com, giving an expiration date 31 days in the future. The
41 zone file is named example.com and the signed zone file will be
42 named example.com.signed.
43 zonesigner -genkeys -endtime +2678400 example.com
45 subsequent runs on example.com
47 The following command will re-sign example.com's zone file, but
48 will not generate new keys. The files and all key-generation and
49 zone-signing arguments will remain the same.
50 zonesigner example.com
52
54 zonesigner is used in this way:
55 zonesigner [options] <zone-file> <signed-zone-file>
57 The zone-file argument is required.
59 zone-file is the name of the zone file from which a signed zone file
61 will be created. If the -zone option is not given, then zone-file will
62 be used as the name of the zone that will be signed. Generated keys
63 are given this name as their base.
64 The zone file is modified to have include commands, which will include
66 the KSK and ZSK keys. These lines are placed at the end of the file
67 and should not be modified by the user. If the zone file already
68 includes any key files, those inclusions will be deleted. These lines
69 are distinguished by starting with "$INCLUDE" and end with ".key".
70 Only the actual include lines are deleted; any related comment lines
71 are left untouched.
72 An intermediate file is used in signing the zone. zone-file is copied
74 to the intermediate file and is modified in preparation of signing the
75 zone file. Several $INCLUDE lines will be added at the end of the file
76 and the SOA serial number will be incremented.
77 signed-zone is the name of the signed zone file. If it is not given on
79 the command line, the default signed zone filename is the zone-file
80 appended with ".signed". Thus, executing zonesigner example.com will
81 result in the signed zone being stored in example.com.signed.
82 Unless the -genkeys, -genksk, -genzsk, or -newpubksk options are speci‐
84 fied, the last keys generated for a particular zone will be used in
85 subsequent zonesigner executions.
86
88 keyrec files retain information about previous key-generation and zone-
89 signing operations. If a keyrec file is not specified (by way of the
90 -krfile option), then a default keyrec file is used. If this default
91 is not specified in the system's DNSSEC-Tools configuration file, the
92 filename will be the zone name appended with .krf. If the -nokrfile
93 option is given, then no keyrec file will be consulted or saved.
94 keyrec files contain three types of entries: zone keyrecs, set
96 keyrecs, and key keyrecs. Zone keyrecs contain information specifi‐
97 cally about the zone, such as the number of ZSKs used to sign the zone,
98 the end-time for the zone, and the key signing set names (names of set
99 keyrecs.) Set keyrecs contain lists of key keyrec names used for a spe‐
100 cific purpose, such as the current ZSK keys or the published ZSK keys.
101 Key keyrecs contain information about the generated keys themselves,
102 such as encryption algorithm, key length, and key lifetime.
103 Each keyrec contains a set of "key/value" entries, one per line. Exam‐
105 ple 4 below contains the contents of a sample keyrec file.
106
108 On some systems, the implementation of the pseudo-random number genera‐
109 tor requires keyboard activity. This keyboard activity is used to fill
110 a buffer in the system's random number generator. If zonesigner
111 appears hung, you may have to add entropy to the random number genera‐
112 tor by randomly striking keys until the program completes. Display of
113 this message is controlled by the entropy_msg configuration file param‐
114 eter.
115
117 zonesigner checks four places in order to determine option values. In
118 descending order of precedence, these places are:
119 command line options
121 keyrec file
123 DNSSEC-Tools configuration file
125 zonesigner defaults
127 Each is checked until a value is found. That value is then used for
129 that zonesigner execution and the value is stored in the keyrec file.
130 Example
132 For example, the KSK length has the following values:
134 -ksklength command line option: 8192
136 keyrec file: 1024
138 DNSSEC-Tools configuration file: 2048
140 zonesigner defaults: 512
142 If all are present, then the KSK length will be 8192.
144 If the -ksklength command line option wasn't given, the KSK length will
146 be 1024.
147 If the KSK length wasn't given in the configuration file, it will be
149 8192.
150 If the KSK length wasn't in the keyrec file or the configuration file,
152 the KSK length will be 8192.
153 If the -ksklength command line option wasn't given and the KSK length
155 wasn't in the configuration file, it'll be 1024.
156 If the command line option wasn't given, the KSK length wasn't in the
158 keyrec file, and it wasn't in the configuration file, then the KSK
159 length will be 512.
160
162 Three types of options may be given, based on the command for which
163 they are intended. These commands are dnssec-keygen, dnssec-signzone,
164 and zonesigner.
165 zonesigner-specific Options
167 -nokrfile
169 No keyrec file will be consulted or created.
170 -krfile
172 keyrec file to use in processing options. See the man page for
173 Net::DNS::SEC::Tools::tooloptions.pm for more details about this
174 file.
175 -genkeys
177 Generate new KSKs and ZSKs for the zone.
178 -genksk
180 Generate new Current KSKs for the zone. Any existing Current KSKs
181 will be marked as obsolete. If this option is not given, the last
182 KSKs generated for this zone will be used.
183 -genzsk
185 Generate new ZSKs for the zone. By default, the last ZSKs gener‐
186 ated for this zone will be used.
187 -newpubksk
189 Generate new Published KSKs for the zone. Any existing Published
190 KSKs will be marked as obsolete.
191 -useboth
193 Use the existing Current and Published ZSKs to sign the zone.
194 -usezskpub
196 Use the existing Published ZSKs to sign the zone.
197 -archivedir
199 The key archive directory. If a key archive directory hasn't been
200 specified (on the command line or in the DNSSEC-Tools configuration
201 file) and the -nosave option was not given, an error message will
202 be displayed and zonesigner will exit.
203 When the files are saved into the archive directory, the existing
205 file names are prepended with a timestamp. The timestamp indicates
206 when the files are archived.
207 This directory may not be the root directory.
209 -nosave
211 Do not save obsolete keys to the key archive directory. The
212 default behavior is to save obsolete keys.
213 -kskcount
215 The number of KSK keys to generate and with which to sign the zone.
216 The default is to use a single KSK key.
217 -ksklife
219 The time between KSK rollovers. This is measured in seconds.
220 -ksignset
222 The name of the KSK signing set to use. If the signing set does
223 not exist, then this must be used in conjunction with either
224 -genkeys or -genksk. The name may contain alphanumerics, under‐
225 scores, hyphens, periods, and commas.
226 The default signing set name is "signing-set-N", where N is a num‐
228 ber. If -signset is not specified, then zonesigner will use the
229 default and increment the number for subsequent signing sets.
230 -zsklife
232 The time between ZSK rollovers. This is measured in seconds.
233 -zskcount
235 The number of ZSK keys to generate and with which to sign the zone.
236 The default is to use a single ZSK key.
237 -signset
239 The name of the ZSK signing set to use as the Current ZSK signing
240 set. The zone is signed and the given signing set becomes the
241 zone's new Current ZSK signing set. If the signing set does not
242 exist, then this must be used in conjunction with either -genkeys
243 or -genzsk.
244 The name may contain alphanumerics, underscores, hyphens, periods,
246 and commas. The default signing set name is "signing-set-N", where
247 N is a number. If -signset is not specified, then zonesigner will
248 use the default and increment the number for subsequent signing
249 sets.
250 -rollksk
252 Force a rollover of the KSK keys. The Current KSK keys are marked
253 as Obsolete and the Published KSK keys are marked as Current. The
254 zone is then signed with the new set of Current KSK keys. If the
255 zone's keyrec does not list a Current or Published KSK, an error
256 message is printed and zonesigner stops execution.
257 The zone's keyrec file is updated to show the new key state.
259 The keyrecs of the KSK keys are adjusted as follows:
261 The Current KSK keys are marked as Obsolete.
263 The Published KSK keys are marked as Current.
264 The obsolete KSK keys are moved to the archive directory.
265 Warning: The timing of key-rolling is critical. Great care must
267 be taken when using this option. In the future, rollerd will auto‐
268 mate the KSK rollover process and may be used to safely take care
269 of this aspect of DNSSEC management.
270 Warning: Using the -rollksk option should only be used if you know
272 what you're doing.
273 Warning: This is a temporary method of KSK rollover. It may be
275 changed in the future.
276 -rollzsk
278 Force a rollover of the ZSK keys using the Pre-Publish Key Rollover
279 method. The rollover process adjusts the keys used to sign the
280 specified zone, generates new keys, signs the zone with the appro‐
281 priate keys, and updates the keyrec file. The Pre-Publish Key
282 Rollover process is described in the DNSSEC Operational Practices
283 document.
284 Three sets of ZSK keys are used in the rollover process: Current,
286 Published, and New. Current ZSKs are those which are used to sign
287 the zone. Published ZSKs are available in the zone data, and
288 therefore in cached zone data, but are not yet used to sign the
289 zone. New ZSKs are not available in zone data nor yet used to sign
290 the zone, but are waiting in the wings for future use.
291 The keyrecs of the ZSK keys are adjusted as follows:
293 The Current ZSK keys are marked as obsolete.
295 The Published ZSK keys are marked as Current.
296 The New ZSK keys, if they exist, are marked as Published.
297 Another set of ZSK keys are generated, which will be
298 marked as the New ZSK keys.
299 The Published ZSK keys' zsklife field is copied to the
300 new ZSK keys' keyrecs.
301 The obsolete ZSK keys are moved to the archive directory.
302 The quick summary of proper ZSK rolling (which rollerd does for you
304 if you use it):
305 - wait 2 * max(TTL in zone)
307 - run zonesigner using -usezskpub
308 - wait 2 * max(TTL in zone)
309 - run zonesigner using -rollzsk
310 - wait 2 * max(TTL in zone)
311 Warning: The timing of key-rolling is critical. Great care must
313 be taken when using this option. rollerd automates the rollover
314 process and may be used to safely take care of this aspect of
315 DNSSEC management. Using the -rollzsk option should only be used
316 if you know what you're doing.
317 -intermediate
319 Filename to use for the temporary zone file. The zone file will be
320 copied to this file and then the key names appended.
321 -zone
323 Name of the zone that will be signed. This zone name may be given
324 with this option or as the first non-option command line argument.
325 -help
327 Display a usage message.
328 -Version
330 Display the version information for zonesigner and the DNSSEC-Tools
331 package.
332 -verbose
334 Verbose output will be given. As more instances of -verbose are
335 given on the command line, additional levels of verbosity are
336 achieved.
337 level output
339 ----- ------
340 1 operations being performed
341 (e.g., generating key files, signing zone)
342 2 details on operations and some operation results
343 (e.g., new key names, zone serial number)
344 3 operations' parameters and additional details
345 (e.g., key lengths, encryption algorithm,
346 executed commands)
347 Higher levels of verbosity are cumulative. Specifying two
349 instances of -verbose will get the output from the first and second
350 levels of output.
351 -showkeycmd
353 Display the actual key-generation command (with options and argu‐
354 ments) that is executed. This is a small subset of verbose level 3
355 output.
356 -showsigncmd
358 Display the actual zone-signing command (with options and argu‐
359 ments) that is executed. This is a small subset of verbose level 3
360 output.
361 dnssec-keygen-specific Options
363 -algorithm
365 Cryptographic algorithm used to generate the zone's keys. The
366 default value is RSASHA1. The option value is passed to dnssec-
367 keygen as the the -a flag. Consult dnssec-keygen's manual page to
368 determine legal values.
369 -ksklength
371 Bit length of the zone's KSK key. The default is 1024.
372 -random
374 Source of randomness used to generate the zone's keys. This is
375 assumed to be a file, for example /dev/urandom.
376 -zsklength
378 Bit length of the zone's ZSK key. The default is 512.
379 -kgopts
381 Additional options for dnssec-keygen may be specified using this
382 option. The additional options are passed as a single string value
383 as an argument to the -kgopts option.
384 dnssec-signzone-specific Options
386 -endtime
388 Time that the zone expires, measured in seconds. See the man page
389 for dnssec-signzone for the valid format of this field. The
390 default value is 2592000 seconds (30 days.)
391 -gends
393 Force dnssec-signzone to generate DS records for the zone. This
394 option is translated into -g when passed to dnssec-signzone.
395 -ksdir
397 Specify a directory for storing keysets. This is passed to dnssec-
398 signzone as the -d option.
399 -szopts
401 Additional options for dnssec-signzone may be specified using this
402 option. The additional options are passed as a single string value
403 as an argument to the -szopts option.
404 Other Options
406 -zcopts
408 Additional options for named-checkzone may be specified using this
409 option. The additional options are passed as a single string value
410 as an argument to the -zcopts option.
411
413 Example 1.
414 In the first example, an existing keyrec file is used to assist in
416 signing the example.com domain. Zone data are stored in example.com,
417 and the keyrec is in example.krf. The final signed zone file will be
418 db.example.com.signed. Using this execution:
419 # zonesigner -krfile example.krf example.com db.example.com.signed
421 the following files are created:
423 Kexample.com.+005+45842.private
425 Kexample.com.+005+45842.key
426 Kexample.com.+005+50186.private
427 Kexample.com.+005+50186.key
428 Kexample.com.+005+59143.private
429 Kexample.com.+005+59143.key
430 dsset-example.com.
432 keyset-example.com.
433 db.example.com.signed
435 The first six files are the KSK and ZSK keys required for the zone.
437 The next two files are created by the zone-signing process. The last
438 file is the final signed zone file.
439 Example 2.
441 In the second example, an existing keyrec file is used to assist in
443 signing the example.com domain. Zone data are stored in example.com,
444 and the keyrec is in example.krf. The generated keys, an intermediate
445 zone file, and final signed zone file will use example.com as a base.
446 Using this execution:
447 # zonesigner -krfile example.krf -intermediate example.zs example.com
449 the following files are created:
451 Kdb.example.com.+005+12354.key
453 Kdb.example.com.+005+12354.private
454 Kdb.example.com.+005+82197.key
455 Kdb.example.com.+005+82197.private
456 Kdb.example.com.+005+55888.key
457 Kdb.example.com.+005+55888.private
458 dsset-db.example.com.
460 keyset-db.example.com.
461 example.zs
463 example.com.signed
464 The first six files are the KSK and ZSK keys required for the zone.
466 The next two files are created by the zone-signing process. The second
467 last file is an intermediate file that will be signed. The last file
468 is file is the final signed zone.
469 Example 3.
471 In the third example, no keyrec file is specified for the signing of
473 the example.com domain. In addition to files created as shown in pre‐
474 vious examples, a new keyrec file is created. The new keyrec file uses
475 the domain name as its base. Using this execution:
476 # zonesigner example.com db.example.com
478 the following keyrec file is created:
480 example.com.krf
482 The signed zone file is created in:
484 db.example.com
486 Example 4.
488 This example shows a keyrec file generated by zonesigner.
490 The command executed is:
492 # zonesigner example.com db.example.com
494 The generated keyrec file contains six keyrecs: a zone keyrec, two set
496 keyrecs, one KSK keyrec, and two ZSK keyrecs.
497 zone "example.com"
499 zonefile "example.com"
500 signedzone "db.example.com"
501 endtime "+2592000"
502 kskcur "signing-set-24"
503 kskdirectory "."
504 zskcur "signing-set-42"
505 zskpub "signing-set-43"
506 zskdirectory "."
507 keyrec_type "zone"
508 keyrec_signsecs "1115166642"
509 keyrec_signdate "Wed May 4 00:30:42 2005"
510 set "signing-set-24"
512 zonename "example.com"
513 keys "Kexample.com.+005+24082"
514 keyrec_setsecs "1110000042"
515 keyrec_setdate "Sat Mar 5 05:20:42 2005"
516 set "signing-set-42"
518 zonename "example.com"
519 keys "Kexample.com.+005+53135"
520 keyrec_setsecs "1115166640"
521 keyrec_setdate "Wed May 4 00:30:40 2005"
522 set "signing-set-43"
524 zonename "example.com"
525 keys "Kexample.com.+005+13531"
526 keyrec_setsecs "1115166641"
527 keyrec_setdate "Wed May 4 00:30:41 2005"
528 key "Kexample.com.+005+24082"
530 zonename "example.com"
531 keyrec_type "kskcur"
532 algorithm "rsasha1"
533 random "/dev/urandom"
534 keypath "./Kexample.com.+005+24082.key"
535 ksklength "1024"
536 ksklife "15768000"
537 keyrec_gensecs "1110000042"
538 keyrec_gendate "Sat Mar 5 05:20:42 2005"
539 key "Kexample.com.+005+53135"
541 zonename "example.com"
542 keyrec_type "zskcur"
543 algorithm "rsasha1"
544 random "/dev/urandom"
545 keypath "./Kexample.com.+005+53135.key"
546 zsklength "512"
547 zsklife "604800"
548 keyrec_gensecs "1115166638"
549 keyrec_gendate "Wed May 4 00:30:38 2005"
550 key "Kexample.com.+005+13531"
552 zonename "example.com"
553 keyrec_type "zskpub"
554 algorithm "rsasha1"
555 random "/dev/urandom"
556 keypath "./Kexample.com.+005+13531.key"
557 zsklength "512"
558 zsklife "604800"
559 keyrec_gensecs "1115166638"
560 keyrec_gendate "Wed May 4 00:30:38 2005"
561
563 1. One Zone in a keyrec File
564 There is a bug in the signing-set code that necessitates only stor‐
565 ing one zone in a keyrec file.
566 2. SOA Serial Numbers
568 Serial numbers in SOA records are merely incremented in this ver‐
569 sion. Future plans are to allow for more flexible serial number
570 manipulation.
571
573 Copyright 2004-2007 SPARTA, Inc. All rights reserved. See the COPYING
574 file included with the DNSSEC-Tools package for details.
575
577 Wayne Morrison, tewok@users.sourceforge.net
578
580 dnssec-keygen(8), dnssec-signzone(8)
581 Net::DNS::SEC::Tools::conf.pm(3), Net::DNS::SEC::Tools::defaults.pm(3),
583 Net::DNS::SEC::Tools::keyrec.pm(3), Net::DNS::SEC::Tools::toolop‐
584 tions.pm(3)
585perl v5.8.8 2007-09-14 ZONESIGNER(1)