summaryrefslogtreecommitdiffstats
path: root/doc/man/dnssec-signzone.8in
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/dnssec-signzone.8in')
-rw-r--r--doc/man/dnssec-signzone.8in438
1 files changed, 438 insertions, 0 deletions
diff --git a/doc/man/dnssec-signzone.8in b/doc/man/dnssec-signzone.8in
new file mode 100644
index 0000000..d9599a4
--- /dev/null
+++ b/doc/man/dnssec-signzone.8in
@@ -0,0 +1,438 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "DNSSEC-SIGNZONE" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9"
+.SH NAME
+dnssec-signzone \- DNSSEC zone signing tool
+.SH SYNOPSIS
+.sp
+\fBdnssec\-signzone\fP [\fB\-a\fP] [\fB\-c\fP class] [\fB\-d\fP directory] [\fB\-D\fP] [\fB\-E\fP engine] [\fB\-e\fP end\-time] [\fB\-f\fP output\-file] [\fB\-g\fP] [\fB\-h\fP] [\fB\-i\fP interval] [\fB\-I\fP input\-format] [\fB\-j\fP jitter] [\fB\-K\fP directory] [\fB\-k\fP key] [\fB\-L\fP serial] [\fB\-M\fP maxttl] [\fB\-N\fP soa\-serial\-format] [\fB\-o\fP origin] [\fB\-O\fP output\-format] [\fB\-P\fP] [\fB\-Q\fP] [\fB\-q\fP] [\fB\-R\fP] [\fB\-S\fP] [\fB\-s\fP start\-time] [\fB\-T\fP ttl] [\fB\-t\fP] [\fB\-u\fP] [\fB\-v\fP level] [\fB\-V\fP] [\fB\-X\fP extended end\-time] [\fB\-x\fP] [\fB\-z\fP] [\fB\-3\fP salt] [\fB\-H\fP iterations] [\fB\-A\fP] {zonefile} [key...]
+.SH DESCRIPTION
+.sp
+\fBdnssec\-signzone\fP 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) is determined by the presence or absence of a \fBkeyset\fP
+file for each child zone.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \fB\-a\fP
+This option verifies all generated signatures.
+.TP
+.B \fB\-c class\fP
+This option specifies the DNS class of the zone.
+.TP
+.B \fB\-C\fP
+This option sets compatibility mode, in which a \fBkeyset\-zonename\fP file is generated in addition
+to \fBdsset\-zonename\fP when signing a zone, for use by older versions
+of \fBdnssec\-signzone\fP\&.
+.TP
+.B \fB\-d directory\fP
+This option indicates the directory where BIND 9 should look for \fBdsset\-\fP or \fBkeyset\-\fP files.
+.TP
+.B \fB\-D\fP
+This option indicates that only those record types automatically managed by
+\fBdnssec\-signzone\fP, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output.
+If smart signing (\fB\-S\fP) is used, DNSKEY records are also included.
+The resulting file can be included in the original zone file with
+\fB$INCLUDE\fP\&. This option cannot be combined with \fB\-O raw\fP,
+\fB\-O map\fP, or serial\-number updating.
+.TP
+.B \fB\-E engine\fP
+This option specifies the hardware to use for cryptographic
+operations, such as a secure key store used for signing, when applicable.
+.sp
+When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
+engine identifier that drives the cryptographic accelerator or
+hardware service module (usually \fBpkcs11\fP). When BIND is
+built with native PKCS#11 cryptography (\fB\-\-enable\-native\-pkcs11\fP), it
+defaults to the path of the PKCS#11 provider library specified via
+\fB\-\-with\-pkcs11\fP\&.
+.TP
+.B \fB\-g\fP
+This option indicates that DS records for child zones should be generated from a \fBdsset\-\fP or \fBkeyset\-\fP
+file. Existing DS records are removed.
+.TP
+.B \fB\-K directory\fP
+This option specifies the directory to search for DNSSEC keys. If not
+specified, it defaults to the current directory.
+.TP
+.B \fB\-k key\fP
+This option tells BIND 9 to treat the specified key as a key\-signing key, ignoring any key flags. This
+option may be specified multiple times.
+.TP
+.B \fB\-M maxttl\fP
+This option sets the maximum TTL for the signed zone. Any TTL higher than \fBmaxttl\fP
+in the input zone is reduced to \fBmaxttl\fP in the output. This
+provides certainty as to the largest possible TTL in the signed zone,
+which is useful to know when rolling keys. The maxttl is the longest
+possible time before signatures that have been retrieved by resolvers
+expire from resolver caches. Zones that are signed with this
+option should be configured to use a matching \fBmax\-zone\-ttl\fP in
+\fBnamed.conf\fP\&. (Note: This option is incompatible with \fB\-D\fP,
+because it modifies non\-DNSSEC data in the output zone.)
+.TP
+.B \fB\-s start\-time\fP
+This option specifies 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 \fB+N\fP, which is N seconds from the current
+time. If no \fBstart\-time\fP is specified, the current time minus 1
+hour (to allow for clock skew) is used.
+.TP
+.B \fB\-e end\-time\fP
+This option specifies the date and time when the generated RRSIG records expire. As
+with \fBstart\-time\fP, an absolute time is indicated in YYYYMMDDHHMMSS
+notation. A time relative to the start time is indicated with \fB+N\fP,
+which is N seconds from the start time. A time relative to the
+current time is indicated with \fBnow+N\fP\&. If no \fBend\-time\fP is
+specified, 30 days from the start time is the default.
+\fBend\-time\fP must be later than \fBstart\-time\fP\&.
+.TP
+.B \fB\-X extended end\-time\fP
+This option specifies the date and time when the generated RRSIG records for the
+DNSKEY RRset 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.
+.sp
+As with \fBend\-time\fP, an absolute time is indicated in
+YYYYMMDDHHMMSS notation. A time relative to the start time is
+indicated with \fB+N\fP, which is N seconds from the start time. A time
+relative to the current time is indicated with \fBnow+N\fP\&. If no
+\fBextended end\-time\fP is specified, the value of \fBend\-time\fP is used
+as the default. (\fBend\-time\fP, in turn, defaults to 30 days from the
+start time.) \fBextended end\-time\fP must be later than \fBstart\-time\fP\&.
+.TP
+.B \fB\-f output\-file\fP
+This option indicates the name of the output file containing the signed zone. The default
+is to append \fB\&.signed\fP to the input filename. If \fBoutput\-file\fP is
+set to \fB\-\fP, then the signed zone is written to the standard
+output, with a default output format of \fBfull\fP\&.
+.TP
+.B \fB\-h\fP
+This option prints a short summary of the options and arguments to
+\fBdnssec\-signzone\fP\&.
+.TP
+.B \fB\-V\fP
+This option prints version information.
+.TP
+.B \fB\-i interval\fP
+This option indicates that, when a previously signed zone is passed as input, records may be
+re\-signed. The \fBinterval\fP 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 is replaced.
+.sp
+The default cycle interval is one quarter of the difference between
+the signature end and start times. So if neither \fBend\-time\fP nor
+\fBstart\-time\fP is specified, \fBdnssec\-signzone\fP 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 are replaced.
+.TP
+.B \fB\-I input\-format\fP
+This option sets the format of the input zone file. Possible formats are \fBtext\fP
+(the default), \fBraw\fP, and \fBmap\fP\&. 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.
+This option is not useful for non\-dynamic zones.
+.TP
+.B \fB\-j jitter\fP
+When signing a zone with a fixed signature lifetime, all RRSIG
+records issued at the time of signing expire simultaneously. If the
+zone is incrementally signed, i.e., a previously signed zone is passed
+as input to the signer, all expired signatures must be regenerated
+at approximately the same time. The \fBjitter\fP option specifies a jitter
+window that is used to randomize the signature expire time, thus
+spreading incremental signature regeneration over time.
+.sp
+Signature lifetime jitter also, to some extent, benefits validators and
+servers by spreading out cache expiration, i.e., if large numbers of
+RRSIGs do not expire at the same time from all caches, there is
+less congestion than if all validators need to refetch at around the
+same time.
+.TP
+.B \fB\-L serial\fP
+When writing a signed zone to \(dqraw\(dq or \(dqmap\(dq format, this option sets the \(dqsource
+serial\(dq value in the header to the specified \fBserial\fP number. (This is
+expected to be used primarily for testing purposes.)
+.TP
+.B \fB\-n ncpus\fP
+This option specifies the number of threads to use. By default, one thread is
+started for each detected CPU.
+.TP
+.B \fB\-N soa\-serial\-format\fP
+This option sets the SOA serial number format of the signed zone. Possible formats are
+\fBkeep\fP (the default), \fBincrement\fP, \fBunixtime\fP, and
+\fBdate\fP\&.
+.INDENT 7.0
+.TP
+\fBkeep\fP
+This format indicates that the SOA serial number should not be modified.
+.TP
+\fBincrement\fP
+This format increments the SOA serial number using \fI\%RFC 1982\fP arithmetic.
+.TP
+\fBunixtime\fP
+This format sets the SOA serial number to the number of seconds
+since the beginning of the Unix epoch, unless the serial
+number is already greater than or equal to that value, in
+which case it is simply incremented by one.
+.TP
+\fBdate\fP
+This format sets the SOA serial number to today\(aqs date, in
+YYYYMMDDNN format, unless the serial number is already greater
+than or equal to that value, in which case it is simply
+incremented by one.
+.UNINDENT
+.TP
+.B \fB\-o origin\fP
+This option sets the zone origin. If not specified, the name of the zone file is
+assumed to be the origin.
+.TP
+.B \fB\-O output\-format\fP
+This option sets the format of the output file containing the signed zone. Possible
+formats are \fBtext\fP (the default), which is the standard textual
+representation of the zone; \fBfull\fP, which is text output in a
+format suitable for processing by external scripts; and \fBmap\fP,
+\fBraw\fP, and \fBraw=N\fP, which store the zone in binary formats
+for rapid loading by \fBnamed\fP\&. \fBraw=N\fP specifies the format
+version of the raw zone file: if N is 0, the raw file can be read by
+any version of \fBnamed\fP; if N is 1, the file can be read by release
+9.9.0 or higher. The default is 1.
+.TP
+.B \fB\-P\fP
+This option disables post\-sign verification tests.
+.sp
+The post\-sign verification tests ensure 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.
+.TP
+.B \fB\-Q\fP
+This option removes signatures from keys that are no longer active.
+.sp
+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 \fB\-Q\fP option forces
+\fBdnssec\-signzone\fP to remove signatures from keys that are no longer
+active. This enables ZSK rollover using the procedure described in
+\fI\%RFC 4641#4.2.1.1\fP (\(dqPre\-Publish Key Rollover\(dq).
+.TP
+.B \fB\-q\fP
+This option enables quiet mode, which suppresses unnecessary output. Without this option, when
+\fBdnssec\-signzone\fP is run it prints three pieces of information to standard output: the number of
+keys in use; the algorithms used to verify the zone was signed correctly and
+other status information; and the filename containing the signed
+zone. With the option that output is suppressed, leaving only the filename.
+.TP
+.B \fB\-R\fP
+This option removes signatures from keys that are no longer published.
+.sp
+This option is similar to \fB\-Q\fP, except it forces
+\fBdnssec\-signzone\fP to remove signatures from keys that are no longer
+published. This enables ZSK rollover using the procedure described in
+\fI\%RFC 4641#4.2.1.2\fP (\(dqDouble Signature Zone Signing Key
+Rollover\(dq).
+.TP
+.B \fB\-S\fP
+This option enables smart signing, which instructs \fBdnssec\-signzone\fP to search the key
+repository for keys that match the zone being signed, and to include
+them in the zone if appropriate.
+.sp
+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:
+.INDENT 7.0
+.INDENT 3.5
+If no timing metadata has been set for the key, the key is
+published in the zone and used to sign the zone.
+.sp
+If the key\(aqs publication date is set and is in the past, the key
+is published in the zone.
+.sp
+If the key\(aqs activation date is set and is in the past, the key is
+published (regardless of publication date) and used to sign the
+zone.
+.sp
+If the key\(aqs revocation date is set and is in the past, and the key
+is published, then the key is revoked, and the revoked key is used
+to sign the zone.
+.sp
+If either the key\(aqs unpublication or deletion date is set and
+in the past, the key is NOT published or used to sign the zone,
+regardless of any other metadata.
+.sp
+If the key\(aqs sync publication date is set and is in the past,
+synchronization records (type CDS and/or CDNSKEY) are created.
+.sp
+If the key\(aqs sync deletion date is set and is in the past,
+synchronization records (type CDS and/or CDNSKEY) are removed.
+.UNINDENT
+.UNINDENT
+.TP
+.B \fB\-T ttl\fP
+This option 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\(aqs SOA record. This option is ignored when
+signing without \fB\-S\fP, 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\(aq TTL values are set to match them, or if any of the
+imported DNSKEY records had a default TTL value. In the event of a
+conflict between TTL values in imported keys, the shortest one is
+used.
+.TP
+.B \fB\-t\fP
+This option prints statistics at completion.
+.TP
+.B \fB\-u\fP
+This option updates the 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 switched to NSEC or to NSEC3 with
+different parameters. Without this option, \fBdnssec\-signzone\fP
+retains the existing chain when re\-signing.
+.TP
+.B \fB\-v level\fP
+This option sets the debugging level.
+.TP
+.B \fB\-x\fP
+This option indicates that BIND 9 should only sign the DNSKEY, CDNSKEY, and CDS RRsets with key\-signing keys,
+and should omit signatures from zone\-signing keys. (This is similar to the
+\fBdnssec\-dnskey\-kskonly yes;\fP zone option in \fBnamed\fP\&.)
+.TP
+.B \fB\-z\fP
+This option indicates that BIND 9 should ignore the KSK flag on keys when determining what to sign. This causes
+KSK\-flagged keys to sign all records, not just the DNSKEY RRset.
+(This is similar to the \fBupdate\-check\-ksk no;\fP zone option in
+\fBnamed\fP\&.)
+.TP
+.B \fB\-3 salt\fP
+This option generates an NSEC3 chain with the given hex\-encoded salt. A dash
+(\-) can be used to indicate that no salt is to be used when
+generating the NSEC3 chain.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+\fB\-3 \-\fP is the recommended configuration. Adding salt provides no practical benefits.
+.UNINDENT
+.UNINDENT
+.TP
+.B \fB\-H iterations\fP
+This option indicates that, when generating an NSEC3 chain, BIND 9 should use this many iterations. The default
+is 10.
+.sp
+\fBWARNING:\fP
+.INDENT 7.0
+.INDENT 3.5
+Values greater than 0 cause interoperability issues and also increase the risk of CPU\-exhausting DoS attacks. The default value has not been changed because the best practices has changed only after BIND 9.16 reached Extended Support Version status.
+.UNINDENT
+.UNINDENT
+.TP
+.B \fB\-A\fP
+This option indicates that, when generating an NSEC3 chain, BIND 9 should set the OPTOUT flag on all NSEC3
+records and should not generate NSEC3 records for insecure delegations.
+.sp
+\fBWARNING:\fP
+.INDENT 7.0
+.INDENT 3.5
+Do not use this option unless all its implications are fully understood. This option is intended only for extremely large zones (comparable to \fBcom.\fP) with sparse secure delegations.
+.UNINDENT
+.UNINDENT
+.sp
+Using this option twice (i.e., \fB\-AA\fP) turns the OPTOUT flag off for
+all records. This is useful when using the \fB\-u\fP option to modify an
+NSEC3 chain which previously had OPTOUT set.
+.TP
+.B \fBzonefile\fP
+This option sets the file containing the zone to be signed.
+.TP
+.B \fBkey\fP
+This option specifies which keys should be used to sign the zone. If no keys are
+specified, the zone is examined for DNSKEY records at the
+zone apex. If these records are found and there are matching private keys in
+the current directory, they are used for signing.
+.UNINDENT
+.SH EXAMPLE
+.sp
+The following command signs the \fBexample.com\fP zone with the
+ECDSAP256SHA256 key generated by \fBdnssec\-keygen\fP
+(Kexample.com.+013+17247). Because the \fB\-S\fP option is not being used,
+the zone\(aqs keys must be in the master file (\fBdb.example.com\fP). This
+invocation looks for \fBdsset\fP files in the current directory, so that
+DS records can be imported from them (\fB\-g\fP).
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+% dnssec\-signzone \-g \-o example.com db.example.com \e
+Kexample.com.+013+17247
+db.example.com.signed
+%
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the above example, \fBdnssec\-signzone\fP creates the file
+\fBdb.example.com.signed\fP\&. This file should be referenced in a zone
+statement in the \fBnamed.conf\fP file.
+.sp
+This example re\-signs a previously signed zone with default parameters.
+The private keys are assumed to be in the current directory.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+% cp db.example.com.signed db.example.com
+% dnssec\-signzone \-o example.com db.example.com
+db.example.com.signed
+%
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fBdnssec\-keygen(8)\fP, BIND 9 Administrator Reference Manual, \fI\%RFC 4033\fP,
+\fI\%RFC 4641\fP\&.
+.SH AUTHOR
+Internet Systems Consortium
+.SH COPYRIGHT
+2023, Internet Systems Consortium
+.\" Generated by docutils manpage writer.
+.