1DNSSEC-SETTIME(1)                   BIND 9                   DNSSEC-SETTIME(1)
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).
82

TIMING OPTIONS

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

KEY STATE OPTIONS

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

PRINTING OPTIONS

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

SEE ALSO

219       dnssec-keygen(8),  dnssec-signzone(8),  BIND  9 Administrator Reference
220       Manual, RFC 5011.
221

AUTHOR

223       Internet Systems Consortium
224
226       2023, Internet Systems Consortium
227
228
229
230
2319.18.11                                                      DNSSEC-SETTIME(1)
Impressum