zonesigner

Langue: en

Autres versions - même langue

Version: 2010-06-30 (fedora - 01/12/10)

Section: 1 (Commandes utilisateur)

Sommaire

NAME

zonesigner - Generates encryption keys and signs a DNS zone

SYNOPSIS

   zonesigner [options] <zone-file> <signed-zone-file>
 
   # get started immediately examples:
 
   # first run on a zone for example.com:
   zonesigner -genkeys -endtime +2678400 example.com
 
   # future runs before expiration time (reuses the same keys):
   zonesigner -endtime +2678400 example.com

DESCRIPTION

This script combines into a single command many actions that are required to sign a DNS zone. It generates the required KSK and ZSK keys, adds the key data to a zone record file, signs the zone file, and runs checks to ensure that everything worked properly. It also keeps records about the keys and how the zone was signed in order to facilitate re-signing of the zone in the future.

The zonesigner-specific zone-signing records are kept in keyrec files. Using keyrec files, defined and maintained by DNSSEC-Tools, zonesigner can automatically gather many of the options used to previously sign and generate a zone and its keys. This allows the zone to be maintained using the same key lengths and expiration times, for example, without an administrator needing to manually track these fields.

QUICK START

The following are examples that will allow a quick start on using zonesigner:
first run on example.com
The following command will generate keys and sign the zone file for example.com, giving an expiration date 31 days in the future. The zone file is named example.com and the signed zone file will be named example.com.signed. 
     zonesigner -genkeys -endtime +2678400 example.com
subsequent runs on example.com
The following command will re-sign example.com's zone file, but will not generate new keys. The files and all key-generation and zone-signing arguments will remain the same. 
     zonesigner example.com

USING ZONESIGNER

zonesigner is used in this way: 
     zonesigner [options] <zone-file> <signed-zone-file>

The zone-file argument is required.

zone-file is the name of the zone file from which a signed zone file will be created. If the -zone option is not given, then zone-file will be used as the name of the zone that will be signed. Generated keys are given this name as their base.

The zone file is modified to have include commands, which will include the KSK and ZSK keys. These lines are placed at the end of the file and should not be modified by the user. If the zone file already includes any key files, those inclusions will be deleted. These lines are distinguished by starting with ``$INCLUDE'' and end with ``.key''. Only the actual include lines are deleted; any related comment lines are left untouched.

An intermediate file is used in signing the zone. zone-file is copied to the intermediate file and is modified in preparation of signing the zone file. Several $INCLUDE lines will be added at the end of the file and the SOA serial number will be incremented.

signed-zone is the name of the signed zone file. If it is not given on the command line, the default signed zone filename is the zone-file appended with ``.signed''. Thus, executing zonesigner example.com will result in the signed zone being stored in example.com.signed.

Unless the -genkeys, -genksk, -genzsk, or -newpubksk options are specified, the last keys generated for a particular zone will be used in subsequent zonesigner executions.

KEYREC FILES

keyrec files retain information about previous key-generation and zone-signing operations. If a keyrec file is not specified (by way of the -krfile option), then a default keyrec file is used. If this default is not specified in the system's DNSSEC-Tools configuration file, the filename will be the zone name appended with .krf. If the -nokrfile option is given, then no keyrec file will be consulted or saved.

Each keyrec contains a set of ``key/value'' entries, one per line. Example 4 below contains the contents of a sample keyrec file.

keyrec files contain three types of entries: zone keyrecs, set keyrecs, and key keyrecs. Zone keyrecs contain information specifically about the zone, such as the number of ZSKs used to sign the zone, the end-time for the zone, and the key signing set names (names of set keyrecs.) Set keyrecs contain lists of key keyrec names used for a specific purpose, such as the current ZSK keys or the published ZSK keys. Key keyrecs contain information about the generated keys themselves, such as encryption algorithm, key length, and key lifetime.

Keyrec Files and RFC5011 KSK Revocation

If RFC5011 processing is enabled, there is special handling of the zone's set keyrec of revoked KSK keys. The ``kskrev'' field in the zone's keyrec points to a set keyrec, marked as being of type ``kskrev''. This set keyrec, in turn, points to a number of other set keyrecs, all of which are also marked as being of type ``kskrev''. The group of all revoked KSK keys is found by consulting that subsidiary set of ``kskrev'' set keyrecs. When the ages of these revoked keys exceeds their revocation periods, they are marked as being obsolete (``kskobs''). If this happens as part of normal rollover, these revoked key and set keyrecs are all removed from the chain of active, revoked keyrecs. If this happens to a key that's part of a larger set of keys, it is removed from that signing set and put in its own new signing set.

ENTROPY

On some systems, the implementation of the pseudo-random number generator requires keyboard activity. This keyboard activity is used to fill a buffer in the system's random number generator. If zonesigner appears hung, you may have to add entropy to the random number generator by randomly striking keys until the program completes. Display of this message is controlled by the entropy_msg configuration file parameter.

DETERMINING OPTION VALUES

zonesigner checks four places in order to determine option values. In descending order of precedence, these places are: 
     command line options
 
     keyrec file
 
     DNSSEC-Tools configuration file
 
     zonesigner defaults

Each is checked until a value is found. That value is then used for that zonesigner execution and the value is stored in the keyrec file.

Example

For example, the KSK length has the following values: 
     -ksklength command line option:     8192
 
     keyrec file:                        1024
 
     DNSSEC-Tools configuration file:     512
 
     zonesigner defaults:                2048

If all are present, then the KSK length will be 8192.

If the -ksklength command line option wasn't given, the KSK length will be 1024.

If the KSK length wasn't given in the configuration file, it will be 8192.

If the KSK length wasn't in the keyrec file or the configuration file, the KSK length will be 8192.

If the -ksklength command line option wasn't given and the KSK length wasn't in the configuration file, it'll be 1024.

If the command line option wasn't given, the KSK length wasn't in the keyrec file, and it wasn't in the configuration file, then the KSK length will be 512.

OPTIONS

Three types of options may be given, based on the command for which they are intended. These commands are dnssec-keygen, dnssec-signzone, and zonesigner.

zonesigner-specific Options

-nokrfile
No keyrec file will be consulted or created.
-krfile
keyrec file to use in processing options. See the man page for Net::DNS::SEC::Tools::tooloptions.pm for more details about this file.
-genkeys
Generate new KSKs and ZSKs for the zone.
-genksk
Generate new Current KSKs for the zone. Any existing Current KSKs will be marked as obsolete. If this option is not given, the last KSKs generated for this zone will be used.
-genzsk
Generate new ZSKs for the zone. By default, the last ZSKs generated for this zone will be used.
-newpubksk
Generate new Published KSKs for the zone. Any existing Published KSKs will be marked as obsolete.
-norfc5011
Disable RFC5011 KSK revocation when rolling or replacing existing KSK key sets. By default, zonesigner performs RFC5011 KSK revocation and this option supercedes this behavior and any option setting within the keyrec file.
-droprevoked
Explicitly obsolete currently revoked KSKs and remove them from the signing set before resigning.
-useboth
Use the existing Current and Published ZSKs to sign the zone.
-usezskpub
Use the existing Published ZSKs to sign the zone.
-archivedir
The key archive directory. If a key archive directory hasn't been specified (on the command line or in the DNSSEC-Tools configuration file) and the -nosave option was not given, then zonesigner will leave the keys in the current directory.

When the files are saved into the archive directory, the existing file names are prepended with a timestamp. The timestamp indicates when the files are archived.

This directory may not be the root directory.

-keydirectory
The directory in which KSK and ZSK keys will be stored. The default is to store the keys in the directory in which zonesigner is executed.

This directory may not be the root directory.

-nosave
Do not save obsolete keys to the key archive directory. The default behavior is to save obsolete keys.
-kskcount
The number of KSK keys to generate and with which to sign the zone. The default is to use a single KSK key.
-kskdirectory
The directory in which KSK keys will be stored. The default is to store the keys in the directory in which zonesigner is executed.

This directory may not be the root directory.

-ksklife
The time between KSK rollovers. This is measured in seconds.
-ksignset
The name of the KSK signing set to use. If the signing set does not exist, then this must be used in conjunction with either -genkeys or -genksk. The name may contain alphanumerics, underscores, hyphens, periods, and commas.

The name may contain alphanumerics, underscores, hyphens, periods, and commas. The default signing set name is "zone-signset-N", where zone is the zone being signed and N is a number.

If -ksignset is not specified, then zonesigner will use the default and increment the number for subsequent signing sets.

-zskcount
The number of ZSK keys to generate and with which to sign the zone. The default is to use a single ZSK key.
-zskdirectory
The directory in which ZSK keys will be stored. The default is to store the keys in the directory in which zonesigner is executed.

This directory may not be the root directory.

-zsklife
The time between ZSK rollovers. This is measured in seconds.
-signset
The name of the ZSK signing set to use as the Current ZSK signing set. The zone is signed and the given signing set becomes the zone's new Current ZSK signing set. If the signing set does not exist, then this must be used in conjunction with either -genkeys or -genzsk.

The name may contain alphanumerics, underscores, hyphens, periods, and commas. The default signing set name is "zonesignset-N", where zone is the zone being signed and N is a number.

If -signset is not specified, then zonesigner will use the default and increment the number for subsequent signing sets.

-rollksk
Force a rollover of the KSK keys. The Current KSK keys are marked as Obsolete and the Published KSK keys are marked as Current. The zone is then signed with the new set of Current KSK keys. If the zone's keyrec does not list a Current or Published KSK, an error message is printed and zonesigner stops execution.

The zone's keyrec file is updated to show the new key state.

The keyrecs of the KSK keys are adjusted as follows:

     The Current KSK keys are marked as Obsolete.
     The Published KSK keys are marked as Current.
     The Obsolete KSK keys are moved to the archive directory.

If RFC5011 processing is enabled, then the KSK rollover sequence is modified as follows:

     The Current KSK keys are marked as Revoked.
     The Published KSK keys are marked as Current.
     The Revoked KSK keys are checked to see if they are still
     within their revocation period.  If not, they are marked
     as Obsolete.
     The Obsolete KSK keys are moved to the archive directory.

Warning: The timing of key-rolling is critical. Great care must be taken when using this option. In the future, rollerd will automate the KSK rollover process and may be used to safely take care of this aspect of DNSSEC management.

Warning: Using the -rollksk option should only be used if you know what you're doing.

Warning: This is may be a temporary method of KSK rollover. It may be changed in the future.

-rollzsk
Force a rollover of the ZSK keys using the Pre-Publish Key Rollover method. The rollover process adjusts the keys used to sign the specified zone, generates new keys, signs the zone with the appropriate keys, and updates the keyrec file. The Pre-Publish Key Rollover process is described in the DNSSEC Operational Practices document.

Three sets of ZSK keys are used in the rollover process: Current, Published, and New. Current ZSKs are those which are used to sign the zone. Published ZSKs are available in the zone data, and therefore in cached zone data, but are not yet used to sign the zone. New ZSKs are not available in zone data nor yet used to sign the zone, but are waiting in the wings for future use.

The keyrecs of the ZSK keys are adjusted as follows:

     The Current ZSK keys are marked as obsolete.
     The Published ZSK keys are marked as Current.
     The New ZSK keys, if they exist, are marked as Published.
     Another set of ZSK keys are generated, which will be
         marked as the New ZSK keys.
     The Published ZSK keys' zsklife field is copied to the
         new ZSK keys' keyrecs.
     The obsolete ZSK keys are moved to the archive directory.

The quick summary of proper ZSK rolling (which rollerd does for you if you use it):

     - wait 2 * max(TTL in zone)
     - run zonesigner using -usezskpub
     - wait 2 * max(TTL in zone)
     - run zonesigner using -rollzsk
     - wait 2 * max(TTL in zone)

Warning: The timing of key-rolling is critical. Great care must be taken when using this option. rollerd automates the rollover process and may be used to safely take care of this aspect of DNSSEC management. Using the -rollzsk option should only be used if you know what you're doing.

-intermediate
Filename to use for the temporary zone file. The zone file will be copied to this file and then the key names appended.
-zone
Name of the zone that will be signed. This zone name may be given with this option or as the first non-option command line argument.
-help
Display a usage message.
-Version
Display the version information for zonesigner and the DNSSEC-Tools package.
-verbose
Verbose output will be given. As more instances of -verbose are given on the command line, additional levels of verbosity are achieved. 
     level       output
     -----       ------
       1         operations being performed
                   (e.g., generating key files, signing zone) 
       2         details on operations and some operation results
                   (e.g., new key names, zone serial number)
       3         operations' parameters and additional details
                   (e.g., key lengths, encryption algorithm,
                   executed commands)

Higher levels of verbosity are cumulative. Specifying two instances of -verbose will get the output from the first and second levels of output.

-showkeycmd
Display the actual key-generation command (with options and arguments) that is executed. This is a small subset of verbose level 3 output.
-showsigncmd
Display the actual zone-signing command (with options and arguments) that is executed. This is a small subset of verbose level 3 output.

dnssec-keygen-specific Options

-algorithm
Cryptographic algorithm used to generate the zone's keys. The default value is RSASHA1. The option value is passed to dnssec-keygen as the -a flag. Consult dnssec-keygen's manual page to determine legal values.
-ksklength
Bit length of the zone's KSK key. The default is 2048.
-random
Source of randomness used to generate the zone's keys.        This is assumed to be
a file, for example /dev/urandom.
-zsklength
Bit length of the zone's ZSK key. The default is 1024.
-kgopts
Additional options for dnssec-keygen may be specified using this option. The additional options are passed as a single string value as an argument to the -kgopts option.
-usensec3
Signs the zone using NSEC3 (see RFC5155) proof-of-non-existence records rather than NSEC records. The keys used to sign the zone must support the use of NSEC3 or else zone-signing will fail. Zonesigner will automatically generate new keys of the correct type if one of the -genkeys or similar options is used.
-nsec3optout
When this flag and the -usensec3 flag are set, the zone will be signed using the Opt-Out support described in RFC5155. A quick summary is that only sub-domains with valid DS or public keys available will be signed and the rest will not be. This greatly reduces the computational and memory requirements of extremely large zones with lots of unsigned children.

dnssec-signzone-specific Options

-endtime
Time that the zone expires, measured in seconds. See the man page for dnssec-signzone for the valid format of this field. The default value is 2592000 seconds (30 days.)
-gends
Force dnssec-signzone to generate DS records for the zone. This option is translated into -g when passed to dnssec-signzone.

This option is obsolete. DS records are generated by default. Use the -nogends option if DS records should not be generated.

-ksdir
Specify a directory for storing keysets. This is passed to dnssec-signzone as the -d option.
-nogends
Prevent dnssec-signzone from generating DS records for the zone.
-szopts
Additional options for dnssec-signzone may be specified using this option. The additional options are passed as a single string value as an argument to the -szopts option.

Other Options

-zcopts
Additional options for named-checkzone may be specified using this option. The additional options are passed as a single string value as an argument to the -zcopts option.

EXAMPLES

Example 1.

In the first example, an existing keyrec file is used to assist in signing the example.com domain. Zone data are stored in example.com, and the keyrec is in example.krf. The final signed zone file will be db.example.com.signed. Using this execution:

     # zonesigner -krfile example.krf example.com db.example.com.signed

the following files are created:

     Kexample.com.+005+45842.private
     Kexample.com.+005+45842.key
     Kexample.com.+005+50186.private
     Kexample.com.+005+50186.key
     Kexample.com.+005+59143.private
     Kexample.com.+005+59143.key
 
     dsset-example.com.
     keyset-example.com.
 
     db.example.com.signed

The first six files are the KSK and ZSK keys required for the zone. The next two files are created by the zone-signing process. The last file is the final signed zone file.

Example 2.

In the second example, an existing keyrec file is used to assist in signing the example.com domain. Zone data are stored in example.com, and the keyrec is in example.krf. The generated keys, an intermediate zone file, and final signed zone file will use example.com as a base. Using this execution:

     # zonesigner -krfile example.krf -intermediate example.zs example.com

the following files are created:

     Kdb.example.com.+005+12354.key
     Kdb.example.com.+005+12354.private
     Kdb.example.com.+005+82197.key
     Kdb.example.com.+005+82197.private
     Kdb.example.com.+005+55888.key
     Kdb.example.com.+005+55888.private
 
     dsset-db.example.com.
     keyset-db.example.com.
 
     example.zs
     example.com.signed

The first six files are the KSK and ZSK keys required for the zone. The next two files are created by the zone-signing process. The second last file is an intermediate file that will be signed. The last file is file is the final signed zone.

Example 3.

In the third example, no keyrec file is specified for the signing of the example.com domain. In addition to files created as shown in previous examples, a new keyrec file is created. The new keyrec file uses the domain name as its base. Using this execution:

     # zonesigner example.com db.example.com

the following keyrec file is created:

     example.com.krf

The signed zone file is created in:

     db.example.com

Example 4.

This example shows a keyrec file generated by zonesigner.

The command executed is:

     # zonesigner example.com db.example.com

The generated keyrec file contains six keyrecs: a zone keyrec, two set keyrecs, one KSK keyrec, and two ZSK keyrecs.

     zone        "example.com"
         zonefile        "example.com"
         signedzone      "db.example.com"
         endtime         "+2592000"
         kskcur          "example.com.signset-24"
         kskdirectory    "."
         zskcur          "example.com.signset-42"
         zskpub          "example.com.signset-43"
         zskdirectory    "."
         keyrec_type     "zone"
         keyrec_signsecs "1115166642"
         keyrec_signdate "Wed May  4 00:30:42 2005"
 
     set         "example.com.signset-24"
         zonename        "example.com"
         keys            "Kexample.com.+005+24082"
         keyrec_setsecs  "1110000042"
         keyrec_setdate  "Sat Mar  5 05:20:42 2005"
 
     set         "example.com.signset-42"
         zonename        "example.com"
         keys            "Kexample.com.+005+53135"
         keyrec_setsecs  "1115166640"
         keyrec_setdate  "Wed May  4 00:30:40 2005"
 
     set         "example.com.signset-43"
         zonename        "example.com"
         keys            "Kexample.com.+005+13531"
         keyrec_setsecs  "1115166641"
         keyrec_setdate  "Wed May  4 00:30:41 2005"
 
     key         "Kexample.com.+005+24082"
         zonename        "example.com"
         keyrec_type     "kskcur"
         algorithm       "rsasha1"
         random          "/dev/urandom"
         keypath         "./Kexample.com.+005+24082.key"
         ksklength       "2048"
         ksklife         "15768000"
         keyrec_gensecs  "1110000042"
         keyrec_gendate  "Sat Mar  5 05:20:42 2005"
 
     key         "Kexample.com.+005+53135"
         zonename        "example.com"
         keyrec_type     "zskcur"
         algorithm       "rsasha1"
         random          "/dev/urandom"
         keypath         "./Kexample.com.+005+53135.key"
         zsklength       "1024"
         zsklife         "604800"
         keyrec_gensecs  "1115166638"
         keyrec_gendate  "Wed May  4 00:30:38 2005"
 
     key         "Kexample.com.+005+13531"
         zonename        "example.com"
         keyrec_type     "zskpub"
         algorithm       "rsasha1"
         random          "/dev/urandom"
         keypath         "./Kexample.com.+005+13531.key"
         zsklength       "1024"
         zsklife         "604800"
         keyrec_gensecs  "1115166638"
         keyrec_gendate  "Wed May  4 00:30:38 2005"

NOTES

1. One Zone in a keyrec File
There is a bug in the signing-set code that necessitates only storing one zone in a keyrec file.
2. SOA Serial Numbers
Serial numbers in SOA records are merely incremented in this version. Future plans are to allow for more flexible serial number manipulation.
Copyright 2004-2010 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details.

AUTHOR

Wayne Morrison, tewok@users.sourceforge.net

SEE ALSO

lskrf(1)

dnssec-keygen(8), dnssec-signzone(8)

Net::DNS::SEC::Tools::conf.pm(3), Net::DNS::SEC::Tools::defaults.pm(3), Net::DNS::SEC::Tools::keyrec.pm(3), Net::DNS::SEC::Tools::tooloptions.pm(3)

keyrec(5)