1DNSSEC-SETTIME(8)                   BIND 9                   DNSSEC-SETTIME(8)
2
3
4

NAME

6       dnssec-settime - set the key timing metadata for a DNSSEC key
7

SYNOPSIS

9       dnssec-settime  [-f]  [-K  directory]  [-L ttl] [-P date/offset] [-P ds
10       date/offset] [-P sync date/offset] [-A  date/offset]  [-R  date/offset]
11       [-I   date/offset]  [-D  date/offset]  [-D  ds  date/offset]  [-D  sync
12       date/offset] [-S key] [-i interval] [-h] [-V] [-v  level]  [-E  engine]
13       {keyfile} [-s] [-g state] [-d state date/offset] [-k state date/offset]
14       [-r state date/offset] [-z state date/offset]
15

DESCRIPTION

17       dnssec-settime reads a DNSSEC private key file and sets the key  timing
18       metadata  as specified by the -P, -A, -R, -I, and -D options. The meta‐
19       data can then be used by dnssec-signzone or other signing  software  to
20       determine  when a key is to be published, whether it should be used for
21       signing a zone, etc.
22
23       If none of these options is set on  the  command  line,  dnssec-settime
24       simply prints the key timing metadata already stored in the key.
25
26       When  key  metadata  fields  are  changed,  both  files  of  a key pair
27       (Knnnn.+aaa+iiiii.key and Knnnn.+aaa+iiiii.private) are regenerated.
28
29       Metadata fields are stored in the private file.  A  human-readable  de‐
30       scription  of  the metadata is also placed in comments in the key file.
31       The private file's permissions are always set  to  be  inaccessible  to
32       anyone other than the owner (mode 0600).
33
34       When  working  with  state  files,  it is possible to update the timing
35       metadata in those files as well with -s.  With this option, it is  also
36       possible  to  update key states with -d (DS), -k (DNSKEY), -r (RRSIG of
37       KSK), or -z (RRSIG of ZSK). Allowed states are HIDDEN, RUMOURED,  OMNI‐
38       PRESENT, and UNRETENTIVE.
39
40       The  goal  state of the key can also be set with -g. This should be ei‐
41       ther HIDDEN or OMNIPRESENT, representing whether the key should be  re‐
42       moved from the zone or published.
43
44       It  is  NOT  RECOMMENDED to manipulate state files manually, except for
45       testing purposes.
46

OPTIONS

48       -f     This option forces an update of an old-format key with no  meta‐
49              data  fields. Without this option, dnssec-settime fails when at‐
50              tempting to update a legacy key. With this option,  the  key  is
51              recreated  in the new format, but with the original key data re‐
52              tained. The key's creation date is set to the present  time.  If
53              no  other  values  are specified, then the key's publication and
54              activation dates are also set to the present time.
55
56       -K directory
57              This option sets the directory in which the key files are to re‐
58              side.
59
60       -L ttl This  option sets the default TTL to use for this key when it is
61              converted into a DNSKEY RR. This is the TTL used when the key is
62              imported into a zone, unless there was already a DNSKEY RRset in
63              place, in which case the existing TTL takes precedence. If  this
64              value  is not set and there is no existing DNSKEY RRset, the TTL
65              defaults to the SOA TTL. Setting the default TTL to  0  or  none
66              removes it from the key.
67
68       -h     This option emits a usage message and exits.
69
70       -V     This option prints version information.
71
72       -v level
73              This option sets the debugging level.
74
75       -E engine
76              This  option  specifies  the cryptographic hardware to use, when
77              applicable.
78
79              When BIND 9 is built with OpenSSL, this needs to be set  to  the
80              OpenSSL engine identifier that drives the cryptographic acceler‐
81              ator or hardware service module (usually pkcs11). When  BIND  is
82              built with native PKCS#11 cryptography (--enable-native-pkcs11),
83              it defaults to the path of the PKCS#11 provider  library  speci‐
84              fied via --with-pkcs11.
85

TIMING OPTIONS

87       Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the
88       argument begins with a + or -, it is interpreted as an offset from  the
89       present  time. For convenience, if such an offset is followed by one of
90       the suffixes y, mo, w, d, h, or mi, then  the  offset  is  computed  in
91       years  (defined  as 365 24-hour days, ignoring leap years), months (de‐
92       fined as 30 24-hour days), weeks,  days,  hours,  or  minutes,  respec‐
93       tively. Without a suffix, the offset is computed in seconds. To explic‐
94       itly prevent a date from being set, use none or never.
95
96       -P date/offset
97              This option sets the date on which a key is to be  published  to
98              the  zone.  After that date, the key is included in the zone but
99              is not used to sign it.
100
101       -P ds date/offset
102              This option Sets the date on which DS records  that  match  this
103              key have been seen in the parent zone.
104
105       -P sync date/offset
106              This  option sets the date on which CDS and CDNSKEY records that
107              match this key are to be published to the zone.
108
109       -A date/offset
110              This option sets the date on which the key is to  be  activated.
111              After  that  date,  the  key is included in the zone and used to
112              sign it.
113
114       -R date/offset
115              This option sets the date on which the key is to be revoked. Af‐
116              ter  that date, the key is flagged as revoked. It is included in
117              the zone and is used to sign it.
118
119       -I date/offset
120              This option sets the date on which the key is to be retired. Af‐
121              ter  that date, the key is still included in the zone, but it is
122              not used to sign it.
123
124       -D date/offset
125              This option sets the date on which the key is to be deleted. Af‐
126              ter  that date, the key is no longer included in the zone. (How‐
127              ever, it may remain in the key repository.)
128
129       -D ds date/offset
130              This option sets the date on which the  DS  records  that  match
131              this key have been seen removed from the parent zone.
132
133       -D sync date/offset
134              This  option  sets the date on which the CDS and CDNSKEY records
135              that match this key are to be deleted.
136
137       -S predecessor key
138              This option selects a key for which the key being modified is an
139              explicit  successor.  The name, algorithm, size, and type of the
140              predecessor key must exactly match those of the key being  modi‐
141              fied. The activation date of the successor key is set to the in‐
142              activation date of the predecessor. The publication date is  set
143              to  the activation date minus the prepublication interval, which
144              defaults to 30 days.
145
146       -i interval
147              This option sets the prepublication interval for a key. If  set,
148              then  the  publication and activation dates must be separated by
149              at least this much time. If the activation date is specified but
150              the  publication  date  is not, the publication date defaults to
151              this much time before the activation date;  conversely,  if  the
152              publication date is specified but not the activation date, acti‐
153              vation is set to this much time after publication.
154
155              If the key is being created as an explicit successor to  another
156              key, then the default prepublication interval is 30 days; other‐
157              wise it is zero.
158
159              As with date offsets, if the argument is followed by one of  the
160              suffixes  y,  mo,  w,  d,  h, or mi, the interval is measured in
161              years, months, weeks, days,  hours,  or  minutes,  respectively.
162              Without a suffix, the interval is measured in seconds.
163

KEY STATE OPTIONS

165       To  test dnssec-policy it may be necessary to construct keys with arti‐
166       ficial state information; these options are used by the testing  frame‐
167       work for that purpose, but should never be used in production.
168
169       Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE.
170
171       -s     This  option  indicates  that  when setting key timing data, the
172              state file should also be updated.
173
174       -g state
175              This option sets the goal state for this key. Must be HIDDEN  or
176              OMNIPRESENT.
177
178       -d state date/offset
179              This  option  sets the DS state for this key as of the specified
180              date, offset from the current date.
181
182       -k state date/offset
183              This option sets the DNSKEY state for this key as of the  speci‐
184              fied date, offset from the current date.
185
186       -r state date/offset
187              This  option  sets  the RRSIG (KSK) state for this key as of the
188              specified date, offset from the current date.
189
190       -z state date/offset
191              This option sets the RRSIG (ZSK) state for this key  as  of  the
192              specified date, offset from the current date.
193

PRINTING OPTIONS

195       dnssec-settime can also be used to print the timing metadata associated
196       with a key.
197
198       -u     This option indicates that times should be printed in Unix epoch
199              format.
200
201       -p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all
202              This  option prints a specific metadata value or set of metadata
203              values.  The -p option may be followed by one  or  more  of  the
204              following  letters  or strings to indicate which value or values
205              to print: C for the creation date, P for the  publication  date,
206              Pds`  for  the  DS  publication  date,  ``Psync  for the CDS and
207              CDNSKEY publication date, A for the activation date, R  for  the
208              revocation date, I for the inactivation date, D for the deletion
209              date, Dds for the DS deletion date, and Dsync for  the  CDS  and
210              CDNSKEY deletion date. To print all of the metadata, use all.
211

SEE ALSO

213       dnssec-keygen(8),  dnssec-signzone(8),  BIND  9 Administrator Reference
214       Manual, RFC 5011.
215

AUTHOR

217       Internet Systems Consortium
218
220       2021, Internet Systems Consortium
221
222
223
224
2259.16.23-RH                                                   DNSSEC-SETTIME(8)
Impressum