1ods-ksmutil(1) OpenDNSSEC ods-ksmutil ods-ksmutil(1)
2
6 ods-ksmutil - OpenDNSSEC zone and key management
7
9 ods-ksmutil setup
10 ods-ksmutil start|stop|notify
11 ods-ksmutil update kasp|zonelist|conf|all
12 ods-ksmutil zone add|delete|list ...
13 ods-ksmutil zonelist import|export
14 ods-ksmutil key gener‐
15 ate|import|export|list|purge|rollover|ksk-retire|ds-seen|delete ...
16 ods-ksmutil rollover list ...
17 ods-ksmutil policy export|import|purge ...
18 ods-ksmutil repository list ...
19 ods-ksmutil backup list|prepare|commit|rollback|done
20 ods-ksmutil database backup ...
21
23 ods-ksmutil manages the operation of the KASP Enforcer, which is the
24 part of OpenDNSSEC that triggers key generation and signing operations
25 on domains based on policies with user-defined timing and security
26 requirements. Since everything beyond this management utility is usu‐
27 ally automatic, ods-ksmutil is the primary tool for managing
28 OpenDNSSEC. Among the functions of ods-ksmutil are key management,
29 updates to the zone list and manually rolling keys to recover from
30 exceptional situations like key loss.
31 To get started, a first invocation of ods-ksmutil setup is needed; see
33 SETUP AND UPDATE COMMANDS below for details. After this is done, the
34 rest of the functionality of ods-ksmutil becomes available.
35 The following sections discuss the subcommands in logical groups,
37 detailing any options that they support.
38
40 -c configfile, --config configfile
41 Change the conf.xml file that is used from the default.
42 help This can be used as a subcommand to ods-ksmutil or it can be
44 used after a partial subcommand. In response, ods-ksmutil will
45 give a synopsis of how to continue the command.
46 -V, --version
48 Display version number
49
51 setup Import conf.xml, kasp.xml and zonelist.xml into a database.
52 This deletes any current management information from the data‐
53 base with OpenDNSSEC management information, including any ref‐
54 erences to keys. Updates to an existing setup should therefore
55 not normally run this subcommand, but update instead.
56 update kasp
58 update zonelist
60 update conf
62 update all
64 Update the database with the contents of the respective configu‐
65 ration file, or all those files. The result is comparable to
66 the setup subcommand, except that management information about
67 OpenDNSSEC is not deleted.(Also note that update kasp does not
68 remove any policies from the database, policy purge can be used
69 to remove unused policies).
70
72 zone add --zone|-z zone [--policy|-p name] [--in-type|-j type]
73 [--out-type|-q type] [--input|-i input] [--output|-o output] [--no-xml]
74 Add a zone to both zonelist.xml and the database. This is
75 equivalent to manually editing zonelist.xml and then running the
76 update zonelist subcommand. The --zone option names the zone to
77 add; the --policy option names the policy to use instead of
78 default; the --in-type and --out-type specify the type of input
79 and output adapters (should be DNS or File, default is File);
80 the --input option specifies a non-standard location for the
81 unsigned zone (default is /var/opendnssec/unsigned/ZONE) or the
82 DNS input file(default is /etc/opendnssec/addns.xml); the --out‐
83 put option specifies a non-standard location for the signed zone
84 (default is /var/opendnssec/signed/ZONE) or the DNS output
85 file(default is /etc/opendnssec/addns.xml). The --no-xml flag
86 stops the zonelist.xml file from being updated. This is suitable
87 for a batch mode where you will add multiple zones and then just
88 write zonelist once at the end.
89 zone delete --zone|-z name [--no-xml]
91 zone delete --all|-a
93 Delete one zone (or all zones, respectively) from both
94 zonelist.xml and the database. This is equivalent to manually
95 editing zonelist.xml and then running the update zonelist sub‐
96 command. The --no-xml flag stops the zonelist.xml file from
97 being updated. This is suitable for a batch mode where you will
98 delete multiple zones and then just write zonelist once at the
99 end.
100 zone list
102 List zones from the zonelist.xml. TODO:Not from the database?
103 zonelist export
105 Export list of zones from the database in the same format as
106 zonelist.xml
107 zonelist import
109 Synchronise the database with the contents of zonelist.xml;
110 identical to "update zonelist"
111
113 key generate --policy|-p name --interval|-n interval [--zonetotal|-Z
114 zonetotal]
115 Create enough keys for the named policy to last for the period
116 of time given by interval. See INTERVAL FORMAT for the format
117 of timing specifications.
118 If configured to, OpenDNSSEC will automatically create keys when
120 the need arises. This command can be used to pregenerate keys
121 (maybe for the expected lifetime of an HSM) to help with backup
122 policies. It is also a convenient method of pregenerating a set
123 of keys to allow a disaster recovery site to have a copy of the
124 keys without needed to synchronise keys generated on the fly.
125 By default the command generates keys for all the zones found on
127 the specified policy. If the optional parameter --zonetotal is
128 specified then keys will be generated for that total number of
129 zones, regardless of how many are actually currently on the pol‐
130 icy.
131 key import --algorithm|-g algname --bits|-b bits --repository|-r repo
133 --cka_id|-k ckaid --zone|-z zone --keytype|-t type --keystate|-e state
134 --time|-w time [--check-repository|-C checkrepository] [--retire|-y
135 time]
136 Add a key which was created outside of the OpenDNSSEC code into
137 the database. In doing so, the further details involved in key
138 management must be specified in options.
139 The --algorithm option names the algorithm used with this key;
141 the --bits specifies the strength of this algorithm as a key
142 size in bits.
143 The --repository option names the repository in which the key
145 should be stored; the --cka_id option specifies the name that
146 will be used to identify this key in that repository; the --zone
147 option specifies the zone for which this key is to be used; the
148 --keytype option specifies whether this key should serve as a
149 KSK or a ZSK. See KEY TYPES below for an introduction to these
150 terms.
151 The --keystate option specifies the state in which the key will
153 be after import, and must be one of the options defined in the
154 KEY STATES section below. the --time option specifies the time
155 that this key was created; the --check-repository option speci‐
156 fied that the key import should fail if no matching key with the
157 specified cka_id exists in the Repository. the --retire option
158 specifies the time that this key should be retired. These last
159 two options take the formats given in the TIME FORMATS section
160 below.
161 key export --zone|-z name [--keystate|-e state] [--keytype|-t type]
163 [--ds]
164 key export --all [--keystate|-e state] [--keytype|-t type] [--ds]
166 Export the keys for a particular zone, or for all zones respec‐
167 tively, from the database. The --ds option can be used to
168 retrieve DS records for upload to a registry instead of the full
169 key; the --keystate option can be used to limit the output to
170 keys in a given state; the --keytype option can be used to limit
171 the output to keys of a given type. See the KEY TYPES and KEY
172 STATES sections below for a specification of possible key types
173 and states.
174 key list [--zone name] [--verbose] [--keystate|--all|-e state|-a]
176 [--keytype type|-t type]
177 List information about keys in all zones, or in a particular
178 zone. By default keys in the GENERATE and DEAD state are not
179 displayed.
180 The --verbose option is used to list additional information
182 about each key.
183 The --keystate option can be used to limit the output to keys in
185 a given state. If the --all option is used then keys in all
186 states (including GENERATE and DEAD) are displayed. The --key‐
187 type option can be used to limit the output to keys of a given
188 type. See the KEY TYPES and KEY STATES sections below for a
189 specification of possible key types and states.
190 key purge --zone|-z name
192 key purge --policy|-p name
194 Remove any keys in the Dead state from the repository and from
195 the database of the KASP Enforcer. The options --zone and
196 --policy are used to limit this operation to a single named zone
197 or policy, respectively.
198 key rollover --zone|-z name --keytype type|-t type
200 key rollover --zone|-z name --all|-a
202 key rollover --policy|-p name --keytype type|-t type
204 key rollover --policy|-p name --all|-a
206 Rollover active keys on the named zone or policy, respectively.
207 This command is used to intiate manual rollovers; if it is not
208 given, OpenDNSSEC will automatically rollover keys when the need
209 arises. (Or, in the case of KSKs it will start the rollover
210 process, to finish the KSK rollover see ksk-roll below.)
211 The --keytype option specifies the type of key to roll. Alterna‐
213 tively the --all option can be used which will roll both types
214 of keys. After running, the KASP Enforcer will be woken up so
215 that the signer can be sent the new information.
216 If the policy that the zone is on specifies that keys are shared
218 then all zones on that policy will be rolled. If appropriate, a
219 backup of the sqlite DB file is made.
220 If there are no keys ready to take over from the current key
222 then the rollover will not occur immediately, but will be put
223 off until the is a key in the ready state.
224 key ksk-retire --zone|-z zone
227 key ksk-retire --keytag|-x keytag
229 key ksk-retire --cka_id|-k ckaid
231 Indicate to OpenDNSSEC that a currently active key should be
232 retired. If key identifiers are not provided then the oldest
233 key in the zone will be retired.
234 If only one key is in the active state then this command will
236 exit with an error message, as completing would leave no active
237 keys.
238 key ds-seen --zone|-z zone --keytag|-x keytag [--no-notify|-l]
241 [--no-retire|-f]
242 key ds-seen --zone|-z zone --cka_id|-k ckaid [--no-notify|-l]
244 [--no-retire|-f]
245 Indicate to OpenDNSSEC that a submitted DS record has appeared
246 in the parent zone, and thereby trigger the completion of a KSK
247 rollover. Note that this action is not yet standardised, and
248 can therefore not be solved in a generic, automatic way. This
249 command was designed for inclusion in any personalised setup
250 that may or may not be automated.
251 There are several ways to specify which DS is in DNS, and the
253 options reflect these alternatives. The --keytag option speci‐
254 fies the short integer that serves as a DNSSEC handle to a key;
255 the --cka_id option refers to a key by way of its long hexadeci‐
256 mal identifier used to identify the key in the repository.
257 An optional --no-notify flag can also be passed in, which pre‐
259 vents the enforcer being notified of this change. If this flag
260 is used then the enforcer must be manually notified with the
261 'ods-enforcerd notify' command or the changes will not take
262 effect until the next scheduled run of the enforcer.
263 An optional --no-retire flag can also be passed in, without this
265 the existing key is moved into the retired state at the same
266 time as making the new key active. If you wish to delay this
267 step then pass in this flag and use the ksk-retire command when
268 needed.
269 key delete --cka_id|-k ckaid [--no-hsm]
272 Remove a named key from the system.
273 Keys in the GENERATE or DEAD state can be safely removed from
275 the system as they are not in use.
276 The --no-hsm flag can be provided if you want to leave the key
278 material on the HSM.
279 rollover list
282 List the expected dates and times of upcoming rollovers. This
283 can be used to get an idea of upcoming work, such as the
284 non-standardised submission of DS records to a registry.
285
287 policy export [--policy|--all|-p|-a]
288 Export a policy from the database in the same format as the
289 kasp.xml file.
290 policy import
292 Update the database with the contents of kasp.xml; identical to
293 "update kasp".
294 policy purge
296 * Experimental *
297 Remove any policies which have no zones associated with them.
299 Note that this command has only been tested in a lab environment
300 and so caution is recommended.
301
303 repository list
304 List repositories from the database.
305 backup list --repository|-r name
307 List the backups that have been made on the given repository.
308 The --repository option specifies what repository to list.
309 backup prepare --repository|-r name
311 Start a two-phase key backup procedure. Prepare the keys gener‐
312 ated up to here for backup. Any keys generated automatically by
313 OpenDNSSEC after this command are not guaranteed to be backed
314 up, and will therefore not be taken into account when committing
315 the prepared keys for use by OpenDNSSEC. The next command is
316 usually either backup commit or, in case of failure of the key
317 backup itself, backup rollback. This sequence works reliably if
318 the KASP Enforcer is running. If it is not, the single-phase
319 backup of backup done provides a one-phase backup alternative.
320 backup commit --repository|-r name
322 Successfully end a two-phase key backup procedure. After a key
323 backup has succeeded, release all previously prepared keys for
324 service by OpenDNSSEC. Any keys that were generated since the
325 last issued preparation will not be released as it is uncertain
326 whether these are actually backed up.
327 backup rollback --repository|-r name
329 Safely end a failed two-phase key backup procedure. After a key
330 backup has failed, rollback all previously prepapared keys to
331 the state where they are generated, but not yet available for
332 service by OpenDNSSEC. After fixing this problem, a new attempt
333 to backup the keys can be made.
334 backup done --repository|-r name [--force]
336 *DEPRECATED*
337 Indicate that a backup of the given repository has been done,
339 all non-backed up keys will now be marked as backed up. The
340 --repository option specifies what repository to list.
341 Note that the KASP Enforcer may take the initiative to generate
343 keys after the backup has started and before the backup is done.
344 This single-phase backup command waives that, which is safe when
345 the KASP Enforcer is not running. If you intend to keep the
346 Enforcer running, you will instead want to use the two-phase
347 backup prepare followed by either backup commit or backup roll‐
348 back.
349 database backup [--output|-o output]
351 Make a copy of the database of the KASP Enforcer (if using
352 sqlite). This command ensures that the database is in a consis‐
353 tent state by taking a lock out first. The --output option
354 specifies where the output should go; if not specified, the out‐
355 put goes to the usual enforcer.db.backup file.
356
358 start|stop|notify
359 Start, stop or send "SIGHUP" to the ods-enforcerd process.
360
362 GENERATE
363 The key has just been generated, but is not ready for use.
364 PUBLISH
366 The key has been published in the parent zone.
367 READY The key is ready for use. E.g. according to settings in the pol‐
369 icy the key has been published for long enough to have propa‐
370 gated to all resolvers.
371 ACTIVE The key is actively being used to sign one or more zones.
373 RETIRE The key has either reached the end of its scheduled life, or it
375 has been rolled prematurely. However, records signed with it may
376 still be cached sp the key is still being published.
377 DEAD The key has been retired for long enough that its use is no
379 longer cached, so it has been removed from the zone.
380
382 Keys can be of two types: KSK or ZSK. These terms are explained in
383 more detail in opendnssec(1).
384 In DNS records, the KSK can usually be recognised by having its SEP
386 (Secure Entry Point) flag set. But please note that officially this is
387 a mere hint.
388
390 When specifying an interval for a key generation run the ISO 8601 stan‐
391 dard is used, e.g. P2Y6M for 2 years and 6 months; or PT12H30M for 12
392 hours and 30 minutes. Note that a year is assumed to be 365 days and a
393 month is assumed to be 31 days.
394
396 When specifying a generation/retire time for a key being imported the
397 following formats are understood:
398 YYYYMMDD[HH[MM[SS]]]
400 (all numeric)
401 D-MMM-YYYY[:| ]HH[:MM[:SS]]
403 DD-MMM-YYYY[:| ]HH[:MM[:SS]]
405 YYYY-MMM-DD[:| ]HH[:MM[:SS]]
407 (alphabetic month)
408 D-MM-YYYY[:| ]HH[:MM[:SS]]
410 DD-MM-YYYY[:| ]HH[:MM[:SS]]
412 YYYY-MM-DD[:| ]HH[:MM[:SS]]
414 (numeric month)
415
417 /etc/opendnssec/conf.xml
418 The main configuration file for OpenDNSSEC.
419 /etc/opendnssec/zonelist.xml
421 The list of zones, as defined in conf.xml.
422 /etc/opendnssec/kasp.xml
424 The configuration of policies that define timing and security,
425 as defined in conf.xml.
426 /var/opendnssec/enforcer.db.backup
428 A backup file of the database used by the KASP Enforcer.Note
429 that this does not include the keys, which are to be extracted
430 from its own repository.
431 /var/opendnssec/unsigned/
433 The location that is usually configured in conf.xml to contain
434 unsigned zones.
435 /var/opendnssec/signed/
437 The location that is usually configured in conf.xml to contain
438 signed zones.
439
441 ods-control(8), ods-enforcerd(8), ods-hsmspeed(1), ods-hsmutil(1),
442 ods-kaspcheck(1), ods-signer(8), ods-signerd(8), ods-timing(5),
443 opendnssec(7), http://www.opendnssec.org/
444
446 ods-ksmutil was written by Sion Lloyd and Nominet as part of the
447 OpenDNSSEC project.
448OpenDNSSEC February 2010 ods-ksmutil(1)