1.. 2 Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 4 This Source Code Form is subject to the terms of the Mozilla Public 5 License, v. 2.0. If a copy of the MPL was not distributed with this 6 file, You can obtain one at http://mozilla.org/MPL/2.0/. 7 8 See the COPYRIGHT file distributed with this work for additional 9 information regarding copyright ownership. 10 11.. 12 Copyright (C) Internet Systems Consortium, Inc. ("ISC") 13 14 This Source Code Form is subject to the terms of the Mozilla Public 15 License, v. 2.0. If a copy of the MPL was not distributed with this 16 file, You can obtain one at http://mozilla.org/MPL/2.0/. 17 18 See the COPYRIGHT file distributed with this work for additional 19 information regarding copyright ownership. 20 21 22.. highlight: console 23 24.. _man_dnssec-settime: 25 26dnssec-settime: set the key timing metadata for a DNSSEC key 27------------------------------------------------------------ 28 29Synopsis 30~~~~~~~~ 31 32:program:`dnssec-settime` [**-f**] [**-K** directory] [**-L** ttl] [**-P** date/offset] [**-P** sync date/offset] [**-A** date/offset] [**-R** date/offset] [**-I** date/offset] [**-D** 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] 33 34Description 35~~~~~~~~~~~ 36 37``dnssec-settime`` reads a DNSSEC private key file and sets the key 38timing metadata as specified by the ``-P``, ``-A``, ``-R``, ``-I``, and 39``-D`` options. The metadata can then be used by ``dnssec-signzone`` or 40other signing software to determine when a key is to be published, 41whether it should be used for signing a zone, etc. 42 43If none of these options is set on the command line, then 44``dnssec-settime`` simply prints the key timing metadata already stored 45in the key. 46 47When key metadata fields are changed, both files of a key pair 48(``Knnnn.+aaa+iiiii.key`` and ``Knnnn.+aaa+iiiii.private``) are 49regenerated. 50 51Metadata fields are stored in the private file. A 52human-readable description of the metadata is also placed in comments in 53the key file. The private file's permissions are always set to be 54inaccessible to anyone other than the owner (mode 0600). 55 56When working with state files, it is possible to update the timing metadata in 57those files as well with ``-s``. If this option is used you can also update key 58states with ``-d`` (DS), ``-k`` (DNSKEY), ``-r`` (RRSIG of KSK), or ``-z`` 59(RRSIG of ZSK). Allowed states are HIDDEN, RUMOURED, OMNIPRESENT, and 60UNRETENTIVE. 61 62You can also set the goal state of the key with ``-g``. This should be either 63HIDDEN or OMNIPRESENT (representing whether the key should be removed from the 64zone, or published). 65 66It is NOT RECOMMENDED to manipulate state files manually except for testing 67purposes. 68 69Options 70~~~~~~~ 71 72**-f** 73 Force an update of an old-format key with no metadata fields. Without 74 this option, ``dnssec-settime`` will fail when attempting to update a 75 legacy key. With this option, the key will be recreated in the new 76 format, but with the original key data retained. The key's creation 77 date will be set to the present time. If no other values are 78 specified, then the key's publication and activation dates will also 79 be set to the present time. 80 81**-K** directory 82 Sets the directory in which the key files are to reside. 83 84**-L** ttl 85 Sets the default TTL to use for this key when it is converted into a 86 DNSKEY RR. If the key is imported into a zone, this is the TTL that 87 will be used for it, unless there was already a DNSKEY RRset in 88 place, in which case the existing TTL would take precedence. If this 89 value is not set and there is no existing DNSKEY RRset, the TTL will 90 default to the SOA TTL. Setting the default TTL to ``0`` or ``none`` 91 removes it from the key. 92 93**-h** 94 Emit usage message and exit. 95 96**-V** 97 Prints version information. 98 99**-v** level 100 Sets the debugging level. 101 102**-E** engine 103 Specifies the cryptographic hardware to use, when applicable. 104 105 When BIND is built with OpenSSL PKCS#11 support, this defaults to the 106 string "pkcs11", which identifies an OpenSSL engine that can drive a 107 cryptographic accelerator or hardware service module. When BIND is 108 built with native PKCS#11 cryptography (--enable-native-pkcs11), it 109 defaults to the path of the PKCS#11 provider library specified via 110 "--with-pkcs11". 111 112Timing Options 113~~~~~~~~~~~~~~ 114 115Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the 116argument begins with a '+' or '-', it is interpreted as an offset from 117the present time. For convenience, if such an offset is followed by one 118of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the offset is 119computed in years (defined as 365 24-hour days, ignoring leap years), 120months (defined as 30 24-hour days), weeks, days, hours, or minutes, 121respectively. Without a suffix, the offset is computed in seconds. To 122unset a date, use 'none' or 'never'. 123 124**-P** date/offset 125 Sets the date on which a key is to be published to the zone. After 126 that date, the key will be included in the zone but will not be used 127 to sign it. 128 129**-P** sync date/offset 130 Sets the date on which CDS and CDNSKEY records that match this key 131 are to be published to the zone. 132 133**-A** date/offset 134 Sets the date on which the key is to be activated. After that date, 135 the key will be included in the zone and used to sign it. 136 137**-R** date/offset 138 Sets the date on which the key is to be revoked. After that date, the 139 key will be flagged as revoked. It will be included in the zone and 140 will be used to sign it. 141 142**-I** date/offset 143 Sets the date on which the key is to be retired. After that date, the 144 key will still be included in the zone, but it will not be used to 145 sign it. 146 147**-D** date/offset 148 Sets the date on which the key is to be deleted. After that date, the 149 key will no longer be included in the zone. (It may remain in the key 150 repository, however.) 151 152**-D** sync date/offset 153 Sets the date on which the CDS and CDNSKEY records that match this 154 key are to be deleted. 155 156**-S** predecessor key 157 Select a key for which the key being modified will be an explicit 158 successor. The name, algorithm, size, and type of the predecessor key 159 must exactly match those of the key being modified. The activation 160 date of the successor key will be set to the inactivation date of the 161 predecessor. The publication date will be set to the activation date 162 minus the prepublication interval, which defaults to 30 days. 163 164**-i** interval 165 Sets the prepublication interval for a key. If set, then the 166 publication and activation dates must be separated by at least this 167 much time. If the activation date is specified but the publication 168 date isn't, then the publication date will default to this much time 169 before the activation date; conversely, if the publication date is 170 specified but activation date isn't, then activation will be set to 171 this much time after publication. 172 173 If the key is being set to be an explicit successor to another key, 174 then the default prepublication interval is 30 days; otherwise it is 175 zero. 176 177 As with date offsets, if the argument is followed by one of the 178 suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the interval is 179 measured in years, months, weeks, days, hours, or minutes, 180 respectively. Without a suffix, the interval is measured in seconds. 181 182Key State Options 183~~~~~~~~~~~~~~~~~ 184 185Known key states are HIDDEN, RUMOURED, OMNIPRESENT and UNRETENTIVE. These should 186not be set manually except for testing purposes. 187 188``-s`` 189 When setting key timing data, also update the state file. 190 191``-g`` 192 Set the goal state for this key. Must be HIDDEN or OMNIPRESENT. 193 194``-d`` 195 Set the DS state for this key, and when it was last changed. 196 197``-k`` 198 Set the DNSKEY state for this key, and when it was last changed. 199 200``-r`` 201 Set the RRSIG (KSK) state for this key, and when it was last changed. 202 203``-z`` 204 205 Set the RRSIG (ZSK) state for this key, and when it was last changed. 206 207Printing Options 208~~~~~~~~~~~~~~~~ 209 210``dnssec-settime`` can also be used to print the timing metadata 211associated with a key. 212 213**-u** 214 Print times in UNIX epoch format. 215 216**-p** C/P/Psync/A/R/I/D/Dsync/all 217 Print a specific metadata value or set of metadata values. The ``-p`` 218 option may be followed by one or more of the following letters or 219 strings to indicate which value or values to print: ``C`` for the 220 creation date, ``P`` for the publication date, ``Psync`` for the CDS 221 and CDNSKEY publication date, ``A`` for the activation date, ``R`` 222 for the revocation date, ``I`` for the inactivation date, ``D`` for 223 the deletion date, and ``Dsync`` for the CDS and CDNSKEY deletion 224 date To print all of the metadata, use ``-p all``. 225 226See Also 227~~~~~~~~ 228 229:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, 230:rfc:`5011`. 231