summaryrefslogtreecommitdiffstats
path: root/bin/dnssec/dnssec-settime.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--bin/dnssec/dnssec-settime.rst231
1 files changed, 231 insertions, 0 deletions
diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst
new file mode 100644
index 0000000..9f6c428
--- /dev/null
+++ b/bin/dnssec/dnssec-settime.rst
@@ -0,0 +1,231 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. highlight: console
+
+.. _man_dnssec-settime:
+
+dnssec-settime: set the key timing metadata for a DNSSEC key
+------------------------------------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`dnssec-settime` [**-f**] [**-K** directory] [**-L** ttl] [**-P** date/offset] [**-P** ds date/offset] [**-P** sync date/offset] [**-A** date/offset] [**-R** date/offset] [**-I** date/offset] [**-D** date/offset] [**-D** ds date/offset] [**-D** sync date/offset] [**-S** key] [**-i** interval] [**-h**] [**-V**] [**-v** level] [**-E** engine] {keyfile} [**-s**] [**-g** state] [**-d** state date/offset] [**-k** state date/offset] [**-r** state date/offset] [**-z** state date/offset]
+
+Description
+~~~~~~~~~~~
+
+``dnssec-settime`` reads a DNSSEC private key file and sets the key
+timing metadata as specified by the ``-P``, ``-A``, ``-R``, ``-I``, and
+``-D`` options. The metadata can then be used by ``dnssec-signzone`` or
+other signing software to determine when a key is to be published,
+whether it should be used for signing a zone, etc.
+
+If none of these options is set on the command line,
+``dnssec-settime`` simply prints the key timing metadata already stored
+in the key.
+
+When key metadata fields are changed, both files of a key pair
+(``Knnnn.+aaa+iiiii.key`` and ``Knnnn.+aaa+iiiii.private``) are
+regenerated.
+
+Metadata fields are stored in the private file. A
+human-readable description of the metadata is also placed in comments in
+the key file. The private file's permissions are always set to be
+inaccessible to anyone other than the owner (mode 0600).
+
+When working with state files, it is possible to update the timing metadata in
+those files as well with ``-s``. With this option, it is also possible to update key
+states with ``-d`` (DS), ``-k`` (DNSKEY), ``-r`` (RRSIG of KSK), or ``-z``
+(RRSIG of ZSK). Allowed states are HIDDEN, RUMOURED, OMNIPRESENT, and
+UNRETENTIVE.
+
+The goal state of the key can also be set with ``-g``. This should be either
+HIDDEN or OMNIPRESENT, representing whether the key should be removed from the
+zone or published.
+
+It is NOT RECOMMENDED to manipulate state files manually, except for testing
+purposes.
+
+Options
+~~~~~~~
+
+``-f``
+ This option forces an update of an old-format key with no metadata fields. Without
+ this option, ``dnssec-settime`` fails when attempting to update a
+ legacy key. With this option, the key is recreated in the new
+ format, but with the original key data retained. The key's creation
+ date is set to the present time. If no other values are
+ specified, then the key's publication and activation dates are also
+ set to the present time.
+
+``-K directory``
+ This option sets the directory in which the key files are to reside.
+
+``-L ttl``
+ This option sets the default TTL to use for this key when it is converted into a
+ DNSKEY RR. This is the TTL used when the key is imported into a zone,
+ unless there was already a DNSKEY RRset in
+ place, in which case the existing TTL takes precedence. If this
+ value is not set and there is no existing DNSKEY RRset, the TTL
+ defaults to the SOA TTL. Setting the default TTL to ``0`` or ``none``
+ removes it from the key.
+
+``-h``
+ This option emits a usage message and exits.
+
+``-V``
+ This option prints version information.
+
+``-v level``
+ This option sets the debugging level.
+
+``-E engine``
+ This option specifies the cryptographic hardware to use, when applicable.
+
+ 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 ``pkcs11``). When BIND is
+ built with native PKCS#11 cryptography (``--enable-native-pkcs11``), it
+ defaults to the path of the PKCS#11 provider library specified via
+ ``--with-pkcs11``.
+
+Timing Options
+~~~~~~~~~~~~~~
+
+Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the
+argument begins with a ``+`` or ``-``, it is interpreted as an offset from
+the present time. For convenience, if such an offset is followed by one
+of the suffixes ``y``, ``mo``, ``w``, ``d``, ``h``, or ``mi``, then the offset is
+computed in years (defined as 365 24-hour days, ignoring leap years),
+months (defined as 30 24-hour days), weeks, days, hours, or minutes,
+respectively. Without a suffix, the offset is computed in seconds. To
+explicitly prevent a date from being set, use ``none`` or ``never``.
+
+``-P date/offset``
+ This option sets the date on which a key is to be published to the zone. After
+ that date, the key is included in the zone but is not used
+ to sign it.
+
+``-P ds date/offset``
+ This option Sets the date on which DS records that match this key have been
+ seen in the parent zone.
+
+``-P sync date/offset``
+ This option sets the date on which CDS and CDNSKEY records that match this key
+ are to be published to the zone.
+
+``-A date/offset``
+ This option sets the date on which the key is to be activated. After that date,
+ the key is included in the zone and used to sign it.
+
+``-R date/offset``
+ This option sets the date on which the key is to be revoked. After that date, the
+ key is flagged as revoked. It is included in the zone and
+ is used to sign it.
+
+``-I date/offset``
+ This option sets the date on which the key is to be retired. After that date, the
+ key is still included in the zone, but it is not used to
+ sign it.
+
+``-D date/offset``
+ This option sets the date on which the key is to be deleted. After that date, the
+ key is no longer included in the zone. (However, it may remain in the key
+ repository.)
+
+``-D ds date/offset``
+ This option sets the date on which the DS records that match this key have
+ been seen removed from the parent zone.
+
+``-D sync date/offset``
+ This option sets the date on which the CDS and CDNSKEY records that match this
+ key are to be deleted.
+
+``-S predecessor key``
+ This option selects a key for which the key being modified is an explicit
+ successor. The name, algorithm, size, and type of the predecessor key
+ must exactly match those of the key being modified. The activation
+ date of the successor key is set to the inactivation date of the
+ predecessor. The publication date is set to the activation date
+ minus the prepublication interval, which defaults to 30 days.
+
+``-i interval``
+ This option sets the prepublication interval for a key. If set, then the
+ publication and activation dates must be separated by at least this
+ much time. If the activation date is specified but the publication
+ date is not, the publication date defaults to this much time
+ before the activation date; conversely, if the publication date is
+ specified but not the activation date, activation is set to
+ this much time after publication.
+
+ If the key is being created as an explicit successor to another key,
+ then the default prepublication interval is 30 days; otherwise it is
+ zero.
+
+ As with date offsets, if the argument is followed by one of the
+ suffixes ``y``, ``mo``, ``w``, ``d``, ``h``, or ``mi``, the interval is
+ measured in years, months, weeks, days, hours, or minutes,
+ respectively. Without a suffix, the interval is measured in seconds.
+
+Key State Options
+~~~~~~~~~~~~~~~~~
+
+To test dnssec-policy it may be necessary to construct keys with artificial
+state information; these options are used by the testing framework for that
+purpose, but should never be used in production.
+
+Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE.
+
+``-s``
+ This option indicates that when setting key timing data, the state file should also be updated.
+
+``-g state``
+ This option sets the goal state for this key. Must be HIDDEN or OMNIPRESENT.
+
+``-d state date/offset``
+ This option sets the DS state for this key as of the specified date, offset from the current date.
+
+``-k state date/offset``
+ This option sets the DNSKEY state for this key as of the specified date, offset from the current date.
+
+``-r state date/offset``
+ This option sets the RRSIG (KSK) state for this key as of the specified date, offset from the current date.
+
+``-z state date/offset``
+ This option sets the RRSIG (ZSK) state for this key as of the specified date, offset from the current date.
+
+Printing Options
+~~~~~~~~~~~~~~~~
+
+``dnssec-settime`` can also be used to print the timing metadata
+associated with a key.
+
+``-u``
+ This option indicates that times should be printed in Unix epoch format.
+
+``-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all``
+ This option prints a specific metadata value or set of metadata values.
+ The ``-p`` option may be followed by one or more of the following letters or
+ strings to indicate which value or values to print: ``C`` for the
+ creation date, ``P`` for the publication date, ``Pds` for the DS publication
+ date, ``Psync`` for the CDS and CDNSKEY publication date, ``A`` for the
+ activation date, ``R`` for the revocation date, ``I`` for the inactivation
+ date, ``D`` for the deletion date, ``Dds`` for the DS deletion date,
+ and ``Dsync`` for the CDS and CDNSKEY deletion date. To print all of the
+ metadata, use ``all``.
+
+See Also
+~~~~~~~~
+
+:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual,
+:rfc:`5011`.