.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "ZONESIGNER 1" .TH ZONESIGNER 1 2023-07-29 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME zonesigner \- Generates encryption keys and signs a DNS zone .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& zonesigner [options] \& \& # 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 .Ve .SH DESCRIPTION .IX Header "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. .PP The \fBzonesigner\fR\-specific zone-signing records are kept in \fIkeyrec\fR files. Using \fIkeyrec\fR files, defined and maintained by DNSSEC-Tools, \fBzonesigner\fR 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. .SH "QUICK START" .IX Header "QUICK START" The following are examples that will allow a quick start on using \&\fBzonesigner\fR: .IP "first run on example.com" 4 .IX Item "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 \fBexample.com\fR and the signed zone file will be named \fBexample.com.signed\fR. .Sp .Vb 1 \& zonesigner \-genkeys \-endtime +2678400 example.com .Ve .IP "subsequent runs on example.com" 4 .IX Item "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. .Sp .Vb 1 \& zonesigner example.com .Ve .SH "USING ZONESIGNER" .IX Header "USING ZONESIGNER" \&\fBzonesigner\fR is used in this way: .PP .Vb 1 \& zonesigner [options] .Ve .PP The \fIzone-file\fR argument is required. .PP \&\fIzone-file\fR is the name of the zone file from which a signed zone file will be created. If the \fB\-zone\fR option is not given, then \fIzone-file\fR will be used as the name of the zone that will be signed. Generated keys are given this name as their base. .PP Once \fBzonesigner\fR has created a set of keys for a zone and signed the zone, it may be used to re-sign the as the zonefile changes. When run without any options, \fBzonesigner\fR will consult the zone's keyrec to find the appropriate set of keys and will then sign the specified zone with them. .PP The zone file is modified to have \fBinclude\fR 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. .PP An intermediate file is used in signing the zone. \fIzone-file\fR is copied to the intermediate file and is modified in preparation of signing the zone file. Several \f(CW$INCLUDE\fR lines will be added at the end of the file and the SOA serial number will be incremented. .PP \&\fIsigned-zone\fR is the name of the signed zone file. If it is not given on the command line, the default signed zone filename is the \fIzone-file\fR appended with ".signed". Thus, executing \fBzonesigner example.com\fR will result in the signed zone being stored in \fIexample.com.signed\fR. .PP Unless the \fB\-genkeys\fR, \fB\-genksk\fR, \fB\-genzsk\fR, or \fB\-newpubksk\fR options are specified, the last keys generated for a particular zone will be used in subsequent \fBzonesigner\fR executions. DS records will be included in signing operations unless the \fB\-nogends\fR option is used. .PP \&\fBzonesigner\fR can be used with a rollover manager, such as \fBrollerd\fR, to provide automated management of a zone, its keys, and the signing of the zone. If a \fBrollerd\fR\-managed zonefile changes while \fBrollerd\fR is waiting for a zone rollover to begin or a rollover phase to complete, \fBzonesigner\fR may be used to sign the zone with the proper set of keys; \fBrollerd\fR will not be disrupted by this. .SH "KEYREC FILES" .IX Header "KEYREC FILES" \&\fIkeyrec\fR files retain information about previous key-generation and zone-signing operations. If a \fIkeyrec\fR file is not specified (by way of the \&\fB\-krfile\fR option), then a default \fIkeyrec\fR 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 \fB.krf\fR. If the \fB\-nokrfile\fR option is given, then no \fIkeyrec\fR file will be consulted or saved. .PP Each \fIkeyrec\fR contains a set of "key/value" entries, one per line. Example 4 below contains the contents of a sample \fIkeyrec\fR file. .PP \&\fIkeyrec\fR files contain three types of entries: zone \fIkeyrec\fRs, set \&\fIkeyrec\fRs, and key \fIkeyrec\fRs. Zone \fIkeyrec\fRs 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 \&\fIkeyrec\fRs.) Set \fIkeyrec\fRs contain lists of key \fIkeyrec\fR names used for a specific purpose, such as the current ZSK keys or the published ZSK keys. Key \&\fIkeyrec\fRs contain information about the generated keys themselves, such as encryption algorithm, key length, and key lifetime. .PP As a zone proceeds through key rollover, new cryptographic keys will be generated for the zone. The various key parameters (e.g., key length and crypto algorithm) will be the same as the parameters previously used to generate keys for that zone. The \fBkeymod\fR command allows these key parameters to be modified as needs change. If a particular parameter is changed, such as the KSK length changing from 1024 to 2048, then \fIfuture\fR keys will reflect that change; current and past keys will not be modified. .SS "Keyrec Files and RFC5011 KSK Revocation" .IX Subsection "Keyrec Files and RFC5011 KSK Revocation" If RFC5011 processing is enabled, there is special handling of the zone's set \&\fIkeyrec\fR of revoked KSK keys. The "kskrev" field in the zone's \fIkeyrec\fR points to a set \fIkeyrec\fR, marked as being of type "kskrev". This set \&\fIkeyrec\fR, in turn, points to a number of other set \fIkeyrec\fRs, 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 \fIkeyrec\fRs. 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 \fIkeyrec\fRs are all removed from the chain of active, revoked \fIkeyrec\fRs. 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. .SH ENTROPY .IX Header "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 \fBzonesigner\fR 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 \fBentropy_msg\fR configuration file parameter. .SH "DETERMINING OPTION VALUES" .IX Header "DETERMINING OPTION VALUES" \&\fBzonesigner\fR checks four places in order to determine option values. In descending order of precedence, these places are: .PP .Vb 1 \& command line options \& \& keyrec file \& \& DNSSEC\-Tools configuration file \& \& zonesigner defaults .Ve .PP Each is checked until a value is found. That value is then used for that \&\fBzonesigner\fR execution and the value is stored in the \fIkeyrec\fR file. .SS Example .IX Subsection "Example" For example, the KSK length has the following values: .PP .Vb 1 \& \-ksklength command line option: 8192 \& \& keyrec file: 1024 \& \& DNSSEC\-Tools configuration file: 512 \& \& zonesigner defaults: 2048 .Ve .PP If all are present, then the KSK length will be 8192. .PP If the \fB\-ksklength\fR command line option wasn't given, the KSK length will be 1024. .PP If the KSK length wasn't given in the configuration file, it will be 8192. .PP If the KSK length wasn't in the \fIkeyrec\fR file or the configuration file, the KSK length will be 8192. .PP If the \fB\-ksklength\fR command line option wasn't given and the KSK length wasn't in the configuration file, it'll be 1024. .PP If the command line option wasn't given, the KSK length wasn't in the \&\fIkeyrec\fR file, and it wasn't in the configuration file, then the KSK length will be 512. .SH OPTIONS .IX Header "OPTIONS" Three types of options may be given, based on the command for which they are intended. These commands are \fBdnssec-keygen\fR, \fBdnssec-signzone\fR, and \&\fBzonesigner\fR. .SS "\fBzonesigner\fP\-specific Options" .IX Subsection "zonesigner-specific Options" .IP \fB\-archivedir\fR 4 .IX Item "-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 \&\fB\-nosave\fR option was \fBnot\fR given, then \fBzonesigner\fR will leave the keys in the current directory. .Sp 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. .Sp This directory \fBmay not\fR be the root directory. .IP \fB\-droprevoked\fR 4 .IX Item "-droprevoked" Explicitly obsolete currently revoked KSKs and remove them from the signing set before resigning. This is mutually exclusive from \fB\-nodroprevoked\fR. If neither \fB\-droprevoked\fR nor \fB\-nodroprevoked\fR are given, then \&\fB\-droprevoked\fR functionality is assumed.. .IP \fB\-dsdir\fR 4 .IX Item "-dsdir" Specify a directory for storing dssets. This directory will be created if it does not exist. .Sp The directory must be writable and \fBmay not\fR be the root directory. .IP \fB\-genkeys\fR 4 .IX Item "-genkeys" Generate new KSKs and ZSKs for the zone. .IP \fB\-genksk\fR 4 .IX Item "-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. .IP \fB\-genzsk\fR 4 .IX Item "-genzsk" Generate new ZSKs for the zone. By default, the last ZSKs generated for this zone will be used. .IP \fB\-help\fR 4 .IX Item "-help" Display a usage message. .IP \fB\-intermediate\fR 4 .IX Item "-intermediate" Filename to use for the temporary zone file. The zone file will be copied to this file and then the key names appended. .IP \fB\-keydirectory\fR 4 .IX Item "-keydirectory" The directory in which KSK and ZSK keys will be stored. The default is to store the keys in the directory in which \fBzonesigner\fR is executed. .Sp This directory \fBmay not\fR be the root directory. .IP \fB\-krfile\fR 4 .IX Item "-krfile" \&\fIkeyrec\fR file to use in processing options. See the man page for \&\fBNet::DNS::SEC::Tools::tooloptions.pm\fR for more details about this file. .IP \fB\-ksignset\fR 4 .IX Item "-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 \fB\-genkeys\fR or \fB\-genksk\fR. The name may contain alphanumerics, underscores, hyphens, periods, and commas. .Sp The name may contain alphanumerics, underscores, hyphens, periods, and commas. The default signing set name is "\fIzone\fR\-signset\-\fIN\fR", where \fIzone\fR is the zone being signed and \fIN\fR is a number. .Sp If \fB\-ksignset\fR is not specified, then \fBzonesigner\fR will use the default and increment the number for subsequent signing sets. .IP \fB\-kskcount\fR 4 .IX Item "-kskcount" The number of KSK keys to generate and with which to sign the zone. The default is to use a single KSK key. .IP \fB\-kskdirectory\fR 4 .IX Item "-kskdirectory" The directory in which KSK keys will be stored. The default is to store the keys in the directory in which \fBzonesigner\fR is executed. .Sp This directory \fBmay not\fR be the root directory. .IP \fB\-ksklife\fR 4 .IX Item "-ksklife" The time between KSK rollovers. This is measured in seconds. .IP \fB\-newpubksk\fR 4 .IX Item "-newpubksk" Generate new Published KSKs for the zone. Any existing Published KSKs will be marked as obsolete. .IP \fB\-nodroprevoked\fR 4 .IX Item "-nodroprevoked" Explicitly turn off obsoleting currently revoked KSKs and remove them from the signing set before resigning. This is mutually exclusive from \&\fB\-droprevoked\fR. If neither \fB\-droprevoked\fR nor \fB\-nodroprevoked\fR are given, then \&\fB\-droprevoked\fR functionality is assumed.. .IP \fB\-nokrfile\fR 4 .IX Item "-nokrfile" No \fIkeyrec\fR file will be consulted or created. .IP \fB\-norfc5011\fR 4 .IX Item "-norfc5011" Disable RFC5011 KSK revocation when rolling or replacing existing KSK key sets. By default, \fBzonesigner\fR performs RFC5011 KSK revocation and this option supersedes this behavior and any option setting within the \fIkeyrec\fR file. .IP \fB\-nosave\fR 4 .IX Item "-nosave" Do not save obsolete keys to the key archive directory. The default behavior is to save obsolete keys. .IP \fB\-phase\fR 4 .IX Item "-phase" Specify an rollover option based on the rollover phase, as opposed to using the option naming the specific action to be performed. The purpose of this option is to bring clarity and greater understanding to how \fBzonesigner\fR is used in the rollover process. .Sp The following are the mappings between the \fB\-phase\fR options and the action options. .Sp .Vb 6 \& Phase Option Action\-based Option \& \-phase ksk2 \-newpubksk \& \-phase ksk4 \-rollksk \& \-phase zsk2 \-usezskpub \& \-phase zsk4b \-rollzsk \& \-phase zsk4b (no option) .Ve .Sp \&\fBWarning\fR: The \fB\-phase\fR option should only be used if you know what you're doing. .IP \fB\-rollksk\fR 4 .IX Item "-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 \fIkeyrec\fR does not list a Current or Published KSK, an error message is printed and \fBzonesigner\fR stops execution. .Sp The zone's \fIkeyrec\fR file is updated to show the new key state. .Sp The \fIkeyrec\fRs of the KSK keys are adjusted as follows: .Sp .Vb 3 \& 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. .Ve .Sp If RFC5011 processing is enabled, then the KSK rollover sequence is modified as follows: .Sp .Vb 6 \& 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. .Ve .Sp \&\fBWarning\fR: The timing of key-rolling is critical. Great care must be taken when using this option. In the future, \fBrollerd\fR will automate the KSK rollover process and may be used to safely take care of this aspect of DNSSEC management. .Sp \&\fBWarning\fR: Using the \fB\-rollksk\fR option should only be used if you know what you're doing. .Sp \&\fBWarning\fR: This is may be a \fItemporary\fR method of KSK rollover. It \fImay\fR be changed in the future. .IP \fB\-rollmgr\fR 4 .IX Item "-rollmgr" The zone's rollover manager. This indicates that the zone is under control of a rollover manager. If a user wishes to sign a zone in the middle of a rollover wait phase, this field helps \fBzonesigner\fR and the rollover manager to determine how best to handle the zone-signing operation. .IP \fB\-rollzsk\fR 4 .IX Item "-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 \&\fIkeyrec\fR file. The Pre-Publish Key Rollover process is described in the DNSSEC Operational Practices document. .Sp 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. .Sp The \fIkeyrec\fRs of the ZSK keys are adjusted as follows: .Sp .Vb 8 \& 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\*(Aq zsklife field is copied to the \& new ZSK keys\*(Aq keyrecs. \& The obsolete ZSK keys are moved to the archive directory. .Ve .Sp The quick summary of proper ZSK rolling (which \fBrollerd\fR does for you if you use it): .Sp .Vb 5 \& \- 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) .Ve .Sp \&\fBWarning\fR: The timing of key-rolling is critical. Great care must be taken when using this option. \fBrollerd\fR automates the rollover process and may be used to safely take care of this aspect of DNSSEC management. Using the \&\fB\-rollzsk\fR option should only be used if you know what you're doing. .IP \fB\-showkeycmd\fR 4 .IX Item "-showkeycmd" Display the actual key-generation command (with options and arguments) that is executed. This is a small subset of verbose level 3 output. .IP \fB\-showsigncmd\fR 4 .IX Item "-showsigncmd" Display the actual zone-signing command (with options and arguments) that is executed. This is a small subset of verbose level 3 output. .IP \fB\-signonly\fR 4 .IX Item "-signonly" Sign the zone without performing any key generation or key rollover operations. The keys used in the most recent \fBzonesigner\fR signing of this zone will be the keys used for this signing. .IP \fB\-signset\fR 4 .IX Item "-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 \fB\-genkeys\fR or \fB\-genzsk\fR. .Sp The name may contain alphanumerics, underscores, hyphens, periods, and commas. The default signing set name is "\fIzone\fRsignset\-\fIN\fR", where \fIzone\fR is the zone being signed and \fIN\fR is a number. .Sp If \fB\-signset\fR is not specified, then \fBzonesigner\fR will use the default and increment the number for subsequent signing sets. .IP \fB\-threshold\fR 4 .IX Item "-threshold" Sign the zone if a threshold condition is met. Depending on how the threshold is specified, it may be relative to the last time the zone was signed or to the zone's expiration date. .Sp \&\fIthreshold-time\fR is the threshold value, given as a numeric value, with an optional unit specifier. The unit may be 's', 'm', 'h', or 'd', for seconds, minutes, hours, or days. If the unit is not given, then the value is in seconds. The threshold value must have either the '\-' prefix or the '+' prefix to indicate which threshold to measure. The threshold value \fI+10d\fR refers to ten days prior to a zone's expiration date. .Sp If the '\-' prefix is used, then the zone will be re-signed if \fBzonesigner\fR is executed no more than \fIthreshold-time\fR after the last time the zone was signed. \fIthreshold-time\fR is determined by subtracting the threshold value from the upcoming midnight. If this would put the threshold time in the future, then it is calculated from the current time. .Sp If the '+' prefix is used, then the zone will be re-signed if \fBzonesigner\fR is executed no more than \fIthreshold-time\fR before the zone's expiration date. \&\fIthreshold-time\fR is determined by subtracting the threshold value from the previous midnight. If this would put \fIthreshold-time\fR in the past, then it is calculated from the current time. .IP \fB\-useboth\fR 4 .IX Item "-useboth" Use the existing Current \fBand\fR Published ZSKs to sign the zone. .IP \fB\-usezskpub\fR 4 .IX Item "-usezskpub" Use the existing Published ZSKs to sign the zone. .IP \fB\-Version\fR 4 .IX Item "-Version" Display the version information for \fBzonesigner\fR and the DNSSEC-Tools package. .IP \fB\-verbose\fR 4 .IX Item "-verbose" Verbose output will be given. As more instances of \fB\-verbose\fR are given on the command line, additional levels of verbosity are achieved. .Sp .Vb 9 \& 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\*(Aq parameters and additional details \& (e.g., key lengths, encryption algorithm, \& executed commands) .Ve .Sp Higher levels of verbosity are cumulative. Specifying two instances of \&\fB\-verbose\fR will get the output from the first and second levels of output. .IP \fB\-xc\fR 4 .IX Item "-xc" Display a message associated with a \fBzonesigner\fR exit value. This option is intended for use by those programs who wish for \fBzonesigner\fR to run silently, but need a description for why \fBzonesigner\fR has exited with an error. .Sp The following are the exit codes and their associated messages. .RS 4 .IP "0 \- successful execution" 4 .IX Item "0 - successful execution" .PD 0 .IP "1 \- \-rfc5011 and \-norfc5011 may not be specified together" 4 .IX Item "1 - -rfc5011 and -norfc5011 may not be specified together" .IP "2 \- \-droprevoked and \-nodroprevoked may not be specified together" 4 .IX Item "2 - -droprevoked and -nodroprevoked may not be specified together" .IP "3 \- \-keydirectory and \-kskdirectory may not be specified together" 4 .IX Item "3 - -keydirectory and -kskdirectory may not be specified together" .IP "4 \- \-keydirectory and \-zskdirectory may not be specified together" 4 .IX Item "4 - -keydirectory and -zskdirectory may not be specified together" .IP "5 \- KSK count must be positive" 4 .IX Item "5 - KSK count must be positive" .IP "6 \- ZSK count must be positive" 4 .IX Item "6 - ZSK count must be positive" .IP "7 \- no key archive directory was specified" 4 .IX Item "7 - no key archive directory was specified" .IP "8 \- key archive directory is not a directory" 4 .IX Item "8 - key archive directory is not a directory" .IP "9 \- key archive directory must not be /" 4 .IX Item "9 - key archive directory must not be /" .IP "10 \- \-savekeys and \-nosave may not be specified together" 4 .IX Item "10 - -savekeys and -nosave may not be specified together" .IP "11 \- either a KSK or a ZSK directory was incorrectly specified" 4 .IX Item "11 - either a KSK or a ZSK directory was incorrectly specified" .IP "12 \- either a specified KSK or a specified ZSK directory is not a directory" 4 .IX Item "12 - either a specified KSK or a specified ZSK directory is not a directory" .IP "13 \- neither the KSK nor the ZSK directory may be the root directory" 4 .IX Item "13 - neither the KSK nor the ZSK directory may be the root directory" .IP "14 \- zone file, output file, and intermediate file must all have distinct names" 4 .IX Item "14 - zone file, output file, and intermediate file must all have distinct names" .IP "15 \- zone file does not exist" 4 .IX Item "15 - zone file does not exist" .IP "16 \- zone file is empty" 4 .IX Item "16 - zone file is empty" .IP "17 \- zone file already signed" 4 .IX Item "17 - zone file already signed" .IP "18 \- specified signing set does not exist" 4 .IX Item "18 - specified signing set does not exist" .IP "19 \- specified Current ZSK signing set does not exist" 4 .IX Item "19 - specified Current ZSK signing set does not exist" .IP "20 \- specified Published ZSK signing set does not exist" 4 .IX Item "20 - specified Published ZSK signing set does not exist" .IP "21 \- specified new signing-set name already exists" 4 .IX Item "21 - specified new signing-set name already exists" .IP "22 \- specified KSK signing set already exists" 4 .IX Item "22 - specified KSK signing set already exists" .IP "23 \- no KSK signing set was specified" 4 .IX Item "23 - no KSK signing set was specified" .IP "24 \- specified Current KSK signing set does not exist" 4 .IX Item "24 - specified Current KSK signing set does not exist" .IP "25 \- specified Published KSK signing set does not exist" 4 .IX Item "25 - specified Published KSK signing set does not exist" .IP "26 \- unable to generate KSK key file" 4 .IX Item "26 - unable to generate KSK key file" .IP "27 \- ZSK keyrec does not exist in keyrec file" 4 .IX Item "27 - ZSK keyrec does not exist in keyrec file" .IP "28 \- unable to generate ZSK key file" 4 .IX Item "28 - unable to generate ZSK key file" .IP "29 \- unable to archive keys because key archive directory is not a directory" 4 .IX Item "29 - unable to archive keys because key archive directory is not a directory" .IP "30 \- KSK repository is not a directory" 4 .IX Item "30 - KSK repository is not a directory" .IP "31 \- ZSK repository is not a directory" 4 .IX Item "31 - ZSK repository is not a directory" .IP "32 \- unable to update serial number in zonefile" 4 .IX Item "32 - unable to update serial number in zonefile" .IP "33 \- zone file's modified contents are empty" 4 .IX Item "33 - zone file's modified contents are empty" .IP "34 \- unable to sign zone" 4 .IX Item "34 - unable to sign zone" .IP "35 \- no Published KSKs have been created" 4 .IX Item "35 - no Published KSKs have been created" .IP "36 \- zone has no Published ZSKs to rollover to Current ZSKs" 4 .IX Item "36 - zone has no Published ZSKs to rollover to Current ZSKs" .IP "37 \- no keys defined for a particular signing set for zone" 4 .IX Item "37 - no keys defined for a particular signing set for zone" .IP "38 \- no keyrec exists for required signing set" 4 .IX Item "38 - no keyrec exists for required signing set" .IP "39 \- error in keyrec file \-\- a particular signing set keyrec is not a set keyrec" 4 .IX Item "39 - error in keyrec file -- a particular signing set keyrec is not a set keyrec" .IP "40 \- specified signing set does not contain any keys" 4 .IX Item "40 - specified signing set does not contain any keys" .IP "41 \- no key keyrec exists for a particular key" 4 .IX Item "41 - no key keyrec exists for a particular key" .IP "42 \- keyrec of specified key has an unexpected type" 4 .IX Item "42 - keyrec of specified key has an unexpected type" .IP "43 \- usage message printed" 4 .IX Item "43 - usage message printed" .IP "44 \- invalid exit code given to \-xc" 4 .IX Item "44 - invalid exit code given to -xc" .IP "45 \- named-checkzone returned an error" 4 .IX Item "45 - named-checkzone returned an error" .IP "46 \- unable to create dsset archive directory" 4 .IX Item "46 - unable to create dsset archive directory" .IP "47 \- dsset archive directory is not a directory" 4 .IX Item "47 - dsset archive directory is not a directory" .IP "48 \- dsset archive directory is not writable" 4 .IX Item "48 - dsset archive directory is not writable" .IP "49 \- dsset archive directory must not be /" 4 .IX Item "49 - dsset archive directory must not be /" .IP "50 \- invalid threshold" 4 .IX Item "50 - invalid threshold" .IP "51 \- invalid format end-date" 4 .IX Item "51 - invalid format end-date" .RE .RS 4 .PD .Sp An error message will be printed if an invalid exit code is given. .RE .IP \fB\-Cthulhu\fR 4 .IX Item "-Cthulhu" This option is for internal use only and should never be used by a user. If this warning is ignored, then undefined, unnameable eldritch horrors may be visited upon your zone files. Do not use. .IP \fB\-zone\fR 4 .IX Item "-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. In the second case, if the argument contains directory separators, then final element of the path will be used for the zone name. .IP \fB\-zskcount\fR 4 .IX Item "-zskcount" The number of ZSK keys to generate and with which to sign the zone. The default is to use a single ZSK key. .IP \fB\-zskdirectory\fR 4 .IX Item "-zskdirectory" The directory in which ZSK keys will be stored. The default is to store the keys in the directory in which \fBzonesigner\fR is executed. .Sp This directory \fBmay not\fR be the root directory. .IP \fB\-zsklife\fR 4 .IX Item "-zsklife" The time between ZSK rollovers. This is measured in seconds. .SS "\fBdnssec-keygen\fP\-specific Options" .IX Subsection "dnssec-keygen-specific Options" .IP \fB\-algorithm\fR 4 .IX Item "-algorithm" Cryptographic algorithm used to generate the zone's keys. The default value is RSASHA1. The option value is passed to \fBdnssec-keygen\fR as the \fB\-a\fR flag. Consult \fBdnssec-keygen\fR's manual page to determine legal values. .IP \fB\-kgopts\fR 4 .IX Item "-kgopts" Additional options for \fBdnssec-keygen\fR may be specified using this option. The additional options are passed as a single string value as an argument to the \fB\-kgopts\fR option. .IP \fB\-ksklength\fR 4 .IX Item "-ksklength" Bit length of the zone's KSK key. The default is 2048. .IP \fB\-nsec3optout\fR 4 .IX Item "-nsec3optout" When this flag and the \fI\-usensec3\fR 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. .IP \fB\-random\fR 4 .IX Item "-random" Source of randomness used to generate the zone's keys. This is assumed to be a file, for example \fB/dev/urandom\fR. .IP \fB\-usensec3\fR 4 .IX Item "-usensec3" Signs the zone using \fINSEC3\fR (see RFC5155) proof-of-non-existence records rather than \fINSEC\fR 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 \&\fI\-genkeys\fR or similar options is used. .IP \fB\-zsklength\fR 4 .IX Item "-zsklength" Bit length of the zone's ZSK key. The default is 1024. .SS "\fBdnssec-signzone\fP\-specific Options" .IX Subsection "dnssec-signzone-specific Options" .IP \fB\-endtime\fR 4 .IX Item "-endtime" Time that the zone expires, as measured from the current time. If given as a number, it is a count of seconds. If it is given as a number followed by 's', \&'m', 'h', or 'd', then it is the number of seconds, minutes, hours, or days. The default value is 2764800 seconds (32 days.) .IP \fB\-gends\fR 4 .IX Item "-gends" Force \fBdnssec-signzone\fR to generate DS records for the zone. This option is translated into \fB\-g\fR when passed to \fBdnssec-signzone\fR. .Sp This option is obsolete. DS records are generated by default. Use the \&\fB\-nogends\fR option if DS records should not be generated. .IP \fB\-ksdir\fR 4 .IX Item "-ksdir" Specify a directory for storing keysets. This is passed to \fBdnssec-signzone\fR as the \fB\-d\fR option. .IP \fB\-nogends\fR 4 .IX Item "-nogends" Prevent \fBdnssec-signzone\fR from generating DS records for the zone. .IP \fB\-szopts\fR 4 .IX Item "-szopts" Additional options for \fBdnssec-signzone\fR may be specified using this option. The additional options are passed as a single string value as an argument to the \fB\-szopts\fR option. .Sp The default value for this option is "\-i local", set in \fBdefaults.pm\fR. This value has been found to greatly improve the amount of time it takes \&\fBnamed-checkzone\fR to run. .SS "Other Options" .IX Subsection "Other Options" .IP \fB\-zcopts\fR 4 .IX Item "-zcopts" Additional options for \fBnamed-checkzone\fR may be specified using this option. The additional options are passed as a single string value as an argument to the \fB\-zcopts\fR option. .SH EXAMPLES .IX Header "EXAMPLES" Example 1. .PP In the first example, an existing \fIkeyrec\fR file is used to assist in signing the example.com domain. Zone data are stored in \fBexample.com\fR, and the keyrec is in \fBexample.krf\fR. The final signed zone file will be \&\fBdb.example.com.signed\fR. Using this execution: .PP .Vb 1 \& # zonesigner \-krfile example.krf example.com db.example.com.signed .Ve .PP the following files are created: .PP .Vb 6 \& 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 .Ve .PP 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. .PP Example 2. .PP In the second example, an existing \fIkeyrec\fR file is used to assist in signing the example.com domain. Zone data are stored in \fBexample.com\fR, and the keyrec is in \fBexample.krf\fR. The generated keys, an intermediate zone file, and final signed zone file will use \fBexample.com\fR as a base. Using this execution: .PP .Vb 1 \& # zonesigner \-krfile example.krf \-intermediate example.zs example.com .Ve .PP the following files are created: .PP .Vb 6 \& 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 .Ve .PP 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. .PP Example 3. .PP In the third example, no \fIkeyrec\fR file is specified for the signing of the example.com domain. In addition to files created as shown in previous examples, a new \fIkeyrec\fR file is created. The new \fIkeyrec\fR file uses the domain name as its base. Using this execution: .PP .Vb 1 \& # zonesigner example.com db.example.com .Ve .PP the following \fIkeyrec\fR file is created: .PP .Vb 1 \& example.com.krf .Ve .PP The signed zone file is created in: .PP .Vb 1 \& db.example.com .Ve .PP Example 4. .PP This example shows a \fIkeyrec\fR file generated by \fBzonesigner\fR. .PP The command executed is: .PP .Vb 1 \& # zonesigner example.com db.example.com .Ve .PP The generated \fIkeyrec\fR file contains six \fIkeyrec\fRs: a zone \fIkeyrec\fR, two set \fIkeyrec\fRs, one KSK \fIkeyrec\fR, and two ZSK \fIkeyrec\fRs. .PP .Vb 12 \& zone "example.com" \& zonefile "example.com" \& signedzone "db.example.com" \& endtime "+2764800" \& 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" .Ve .SH NOTES .IX Header "NOTES" .IP "1. One Zone in a \fIkeyrec\fR File" 4 .IX Item "1. One Zone in a keyrec File" There is a bug in the signing-set code that necessitates only storing one zone in a \fIkeyrec\fR file. .IP "2. SOA Serial Numbers" 4 .IX Item "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. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2004\-2014 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details. .SH AUTHOR .IX Header "AUTHOR" Wayne Morrison, tewok@tislabs.com .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBkeymod\|(8)\fR, \&\fBlskrf\|(1)\fR, \&\fBrollerd\|(1)\fR .PP \&\fBdnssec\-keygen\|(8)\fR, \&\fBdnssec\-signzone\|(8)\fR .PP \&\fBNet::DNS::SEC::Tools::conf.pm\|(3)\fR, \&\fBNet::DNS::SEC::Tools::defaults.pm\|(3)\fR, \&\fBNet::DNS::SEC::Tools::keyrec.pm\|(3)\fR, \&\fBNet::DNS::SEC::Tools::tooloptions.pm\|(3)\fR .PP \&\fBkeyrec\|(5)\fR