NAME¶
ods-ksmutil - OpenDNSSEC zone and key management
SYNOPSIS¶
ods-ksmutil setup
ods-ksmutil [ start | stop | notify ]
ods-ksmutil update [ kasp | zonelist | conf | all ]
ods-ksmutil zone [ add | delete | list ] ...
ods-ksmutil zonelist [ import | export ]
ods-ksmutil key [ generate | import | export | list | purge | rollover |
ksk-retire | ds-seen | delete ] ...
ods-ksmutil rollover list ...
ods-ksmutil policy [ export | import | purge ] ...
ods-ksmutil repository list ...
ods-ksmutil backup [ list | prepare | commit | rollback | done ]
ods-ksmutil database backup ...
DESCRIPTION¶
ods-ksmutil manages the operation of the KASP Enforcer, which is the part
of OpenDNSSEC that triggers key generation and signing operations on domains
based on policies with user-defined timing and security requirements. Since
everything beyond this management utility is usually automatic,
ods-ksmutil is the primary tool for managing OpenDNSSEC. Among the
functions of
ods-ksmutil are key management, updates to the zone list
and manually rolling keys to recover from exceptional situations like key
loss.
To get started, a first invocation of
ods-ksmutil setup is needed; see
SETUP AND UPDATE COMMANDS below for details. After this is done, the rest of
the functionality of
ods-ksmutil becomes available.
The following sections discuss the subcommands in logical groups, detailing any
options that they support.
GENERIC OPTIONS¶
- -c configfile, --config configfile
- Change the conf.xml file that is used from the default.
- help
- This can be used as a subcommand to ods-ksmutil or it can be used
after a partial subcommand. In response, ods-ksmutil will give a
synopsis of how to continue the command.
- -V, --version
- Display version number
SETUP AND UPDATE SUBCOMMANDS¶
- setup
- Import conf.xml, kasp.xml and zonelist.xml into a database. This deletes
any current management information from the database with OpenDNSSEC
management information, including any references to keys. Updates to an
existing setup should therefore not normally run this subcommand, but
update instead.
- update kasp
- update zonelist
- update conf
- update all
- Update the database with the contents of the respective configuration
file, or all those files. The result is comparable to the setup
subcommand, except that management information about OpenDNSSEC is not
deleted.(Also note that update kasp does not remove any policies from the
database, policy purge can be used to remove unused policies).
ZONE MANAGEMENT SUBCOMMANDS¶
- zone add --zone|-z zone [--policy|-p name]
[--in-type|-j type] [--out-type|-q type]
[--input|-i input] [--output|-o output]
[--no-xml]
- Add a zone to both zonelist.xml and the database. This is equivalent to
manually editing zonelist.xml and then running the update zonelist
subcommand. The --zone option names the zone to add; the --policy option
names the policy to use instead of default; the --in-type and --out-type
specify the type of input and output adapters (should be DNS or File,
default is File); the --input option specifies a non-standard location for
the unsigned zone (default is /var/lib/opendnssec/unsigned/ZONE) or the
DNS input file(default is /etc/opendnssec/addns.xml); the --output option
specifies a non-standard location for the signed zone (default is
/var/lib/opendnssec/signed/ZONE) or the DNS output file(default is
/etc/opendnssec/addns.xml). The --no-xml flag stops the zonelist.xml file
from being updated. This is suitable for a batch mode where you will add
multiple zones and then just write zonelist once at the end.
- zone delete --zone|-z name [--no-xml]
- zone delete --all|-a
- Delete one zone (or all zones, respectively) from both zonelist.xml and
the database. This is equivalent to manually editing zonelist.xml and then
running the update zonelist subcommand. The --no-xml flag stops the
zonelist.xml file from being updated. This is suitable for a batch mode
where you will delete multiple zones and then just write zonelist once at
the end.
- zone list
- List zones from the zonelist.xml. TODO:Not from the database?
- zonelist export
- Export list of zones from the database in the same format as
zonelist.xml
- zonelist import
- Synchronise the database with the contents of zonelist.xml; identical to
"update zonelist"
KEY MANAGEMENT SUBCOMMANDS¶
- key generate --policy|-p name --interval|-n
interval [--zonetotal|-Z
zonetotal]
- Create enough keys for the named policy to last for the period of time
given by interval. See INTERVAL FORMAT for the format of timing
specifications.
If configured to, OpenDNSSEC will automatically create keys when the need
arises. This command can be used to pregenerate keys (maybe for the
expected lifetime of an HSM) to help with backup policies. It is also a
convenient method of pregenerating a set of keys to allow a disaster
recovery site to have a copy of the keys without needed to synchronise
keys generated on the fly.
By default the command generates keys for all the zones found on the
specified policy. If the optional parameter --zonetotal is specified then
keys will be generated for that total number of zones, regardless of how
many are actually currently on the policy.
- key import --algorithm|-g algname --bits|-b
bits --repository|-r repo --cka_id|-k
ckaid --zone|-z zone --keytype|-t
type --keystate|-e state --time|-w
time [--check-repository|-C checkrepository]
[--retire|-y time]
- Add a key which was created outside of the OpenDNSSEC code into the
database. In doing so, the further details involved in key management must
be specified in options.
The --algorithm option names the algorithm used with this key; the --bits
specifies the strength of this algorithm as a key size in bits.
The --repository option names the repository in which the key should be
stored; the --cka_id option specifies the name that will be used to
identify this key in that repository; the --zone option specifies the zone
for which this key is to be used; the --keytype option specifies whether
this key should serve as a KSK or a ZSK. See KEY TYPES below for an
introduction to these terms.
The --keystate option specifies the state in which the key will be after
import, and must be one of the options defined in the KEY STATES section
below. the --time option specifies the time that this key was created; the
--check-repository option specified that the key import should fail if no
matching key with the specified cka_id exists in the Repository. the
--retire option specifies the time that this key should be retired. These
last two options take the formats given in the TIME FORMATS section
below.
- key export --zone|-z name [--keystate|-e state]
[--keytype|-t type] [--ds]
- key export --all [--keystate|-e state] [--keytype|-t
type ] [--ds]
- Export the keys for a particular zone, or for all zones respectively, from
the database. The --ds option can be used to retrieve DS records for
upload to a registry instead of the full key; the --keystate option can be
used to limit the output to keys in a given state; the --keytype option
can be used to limit the output to keys of a given type. See the KEY
TYPES and KEY STATES sections below for a specification of possible
key types and states.
- key list [--zone name] [--verbose] [--keystate|--all|-e
state|-a] [--keytype type|-t
type]
- List information about keys in all zones, or in a particular zone. By
default keys in the GENERATE and DEAD state are not displayed.
The --verbose option is used to list additional information about each key.
The --keystate option can be used to limit the output to keys in a given
state. If the --all option is used then keys in all states (including
GENERATE and DEAD) are displayed. The --keytype option can be used to
limit the output to keys of a given type. See the KEY TYPES and KEY
STATES sections below for a specification of possible key types and
states.
- key purge --zone|-z name
- key purge --policy|-p name
- Remove any keys in the Dead state from the repository and from the
database of the KASP Enforcer. The options --zone and --policy are used to
limit this operation to a single named zone or policy, respectively.
- key rollover --zone|-z name --keytype type|-t
type
- key rollover --zone|-z name --all|-a
- key rollover --policy|-p name --keytype type|-t
type
- key rollover --policy|-p name --all|-a
- Rollover active keys on the named zone or policy, respectively. This
command is used to intiate manual rollovers; if it is not given,
OpenDNSSEC will automatically rollover keys when the need arises. (Or, in
the case of KSKs it will start the rollover process, to finish the KSK
rollover see ksk-roll below.)
The --keytype option specifies the type of key to roll. Alternatively the
--all option can be used which will roll both types of keys. After
running, the KASP Enforcer will be woken up so that the signer can be sent
the new information.
If the policy that the zone is on specifies that keys are shared then all
zones on that policy will be rolled. If appropriate, a backup of the
sqlite DB file is made.
If there are no keys ready to take over from the current key then the
rollover will not occur immediately, but will be put off until the is a
key in the ready state.
- key ksk-retire --zone|-z zone
- key ksk-retire --keytag|-x keytag
- key ksk-retire --cka_id|-k ckaid
- Indicate to OpenDNSSEC that a currently active key should be retired. If
key identifiers are not provided then the oldest key in the zone will be
retired.
If only one key is in the active state then this command will exit with an
error message, as completing would leave no active keys.
- key ds-seen --zone|-z zone --keytag|-x keytag
[--no-notify|-l] [--no-retire|-f]
- key ds-seen --zone|-z zone --cka_id|-k ckaid
[--no-notify|-l] [--no-retire|-f]
- Indicate to OpenDNSSEC that a submitted DS record has appeared in the
parent zone, and thereby trigger the completion of a KSK rollover. Note
that this action is not yet standardised, and can therefore not be solved
in a generic, automatic way. This command was designed for inclusion in
any personalised setup that may or may not be automated.
There are several ways to specify which DS is in DNS, and the options
reflect these alternatives. The --keytag option specifies the short
integer that serves as a DNSSEC handle to a key; the --cka_id option
refers to a key by way of its long hexadecimal identifier used to identify
the key in the repository.
An optional --no-notify flag can also be passed in, which prevents the
enforcer being notified of this change. If this flag is used then the
enforcer must be manually notified with the 'ods-enforcerd notify' command
or the changes will not take effect until the next scheduled run of the
enforcer.
An optional --no-retire flag can also be passed in, without this the
existing key is moved into the retired state at the same time as making
the new key active. If you wish to delay this step then pass in this flag
and use the ksk-retire command when needed.
- key delete --cka_id|-k ckaid [--no-hsm]
- Remove a named key from the system.
Keys in the GENERATE or DEAD state can be safely removed from the system as
they are not in use.
The --no-hsm flag can be provided if you want to leave the key material on
the HSM.
- rollover list
- List the expected dates and times of upcoming rollovers. This can be used
to get an idea of upcoming work, such as the non-standardised submission
of DS records to a registry.
POLICY ADMINISTRATION SUBCOMMANDS¶
- policy export [--policy|--all|-p|-a]
- Export a policy from the database in the same format as the kasp.xml
file.
- policy import
- Update the database with the contents of kasp.xml; identical to
"update kasp".
- policy purge
- * Experimental *
Remove any policies which have no zones associated with them. Note that this
command has only been tested in a lab environment and so caution is
recommended.
REPOSITORY AND BACKUP SUBCOMMANDS¶
- repository list
- List repositories from the database.
- backup list --repository|-r name
- List the backups that have been made on the given repository. The
--repository option specifies what repository to list.
- backup prepare --repository|-r name
- Start a two-phase key backup procedure. Prepare the keys generated up to
here for backup. Any keys generated automatically by OpenDNSSEC after this
command are not guaranteed to be backed up, and will therefore not be
taken into account when committing the prepared keys for use by
OpenDNSSEC. The next command is usually either backup commit or, in
case of failure of the key backup itself, backup rollback. This
sequence works reliably if the KASP Enforcer is running. If it is not, the
single-phase backup of backup done provides a one-phase backup
alternative.
- backup commit --repository|-r name
- Successfully end a two-phase key backup procedure. After a key backup has
succeeded, release all previously prepared keys for service by OpenDNSSEC.
Any keys that were generated since the last issued preparation will not be
released as it is uncertain whether these are actually backed up.
- backup rollback --repository|-r name
- Safely end a failed two-phase key backup procedure. After a key backup has
failed, rollback all previously prepapared keys to the state where they
are generated, but not yet available for service by OpenDNSSEC. After
fixing this problem, a new attempt to backup the keys can be made.
- backup done --repository|-r name [--force]
- *DEPRECATED*
Indicate that a backup of the given repository has been done, all non-backed
up keys will now be marked as backed up. The --repository option specifies
what repository to list.
Note that the KASP Enforcer may take the initiative to generate keys after
the backup has started and before the backup is done. This single-phase
backup command waives that, which is safe when the KASP Enforcer is not
running. If you intend to keep the Enforcer running, you will instead want
to use the two-phase backup prepare followed by either backup
commit or backup rollback.
- database backup [--output|-o output]
- Make a copy of the database of the KASP Enforcer (if using sqlite). This
command ensures that the database is in a consistent state by taking a
lock out first. The --output option specifies where the output should go;
if not specified, the output goes to the usual enforcer.db.backup
file.
PROCESS CONTROL SUBCOMMANDS¶
- start|stop|notify
- Start, stop or send "SIGHUP" to the ods-enforcerd process.
KEY STATES¶
- GENERATE
- The key has just been generated, but is not ready for use.
- PUBLISH
- The key has been published in the parent zone.
- READY
- The key is ready for use. E.g. according to settings in the policy the key
has been published for long enough to have propagated to all
resolvers.
- ACTIVE
- The key is actively being used to sign one or more zones.
- RETIRE
- The key has either reached the end of its scheduled life, or it has been
rolled prematurely. However, records signed with it may still be cached sp
the key is still being published.
- DEAD
- The key has been retired for long enough that its use is no longer cached,
so it has been removed from the zone.
KEY TYPES¶
Keys can be of two types: KSK or ZSK. These terms are explained in more detail
in opendnssec(1).
In DNS records, the KSK can usually be recognised by having its SEP (Secure
Entry Point) flag set. But please note that officially this is a mere hint.
When specifying an interval for a key generation run the ISO 8601 standard is
used, e.g. P2Y6M for 2 years and 6 months; or PT12H30M for 12 hours and 30
minutes. Note that a year is assumed to be 365 days and a month is assumed to
be 31 days.
When specifying a generation/retire time for a key being imported the following
formats are understood:
- YYYYMMDD[HH[MM[SS]]]
- (all numeric)
- D-MMM-YYYY[:| ]HH[:MM[:SS]]
- DD-MMM-YYYY[:| ]HH[:MM[:SS]]
- YYYY-MMM-DD[:| ]HH[:MM[:SS]]
- (alphabetic month)
- D-MM-YYYY[:| ]HH[:MM[:SS]]
- DD-MM-YYYY[:| ]HH[:MM[:SS]]
- YYYY-MM-DD[:| ]HH[:MM[:SS]]
- (numeric month)
FILES¶
- /etc/opendnssec/conf.xml
- The main configuration file for OpenDNSSEC.
- /etc/opendnssec/zonelist.xml
- The list of zones, as defined in conf.xml.
- /etc/opendnssec/kasp.xml
- The configuration of policies that define timing and security, as defined
in conf.xml.
- /var/lib/opendnssec/enforcer.db.backup
- A backup file of the database used by the KASP Enforcer.Note that this
does not include the keys, which are to be extracted from its own
repository.
- /var/lib/opendnssec/unsigned/
- The location that is usually configured in conf.xml to contain unsigned
zones.
- /var/lib/opendnssec/signed/
- The location that is usually configured in conf.xml to contain signed
zones.
SEE ALSO¶
ods-control(8),
ods-enforcerd(8),
ods-hsmspeed(1),
ods-hsmutil(1),
ods-kaspcheck(1),
ods-signer(8),
ods-signerd(8),
ods-timing(5),
opendnssec(7),
http://www.opendnssec.org/
AUTHOR¶
ods-ksmutil was written by Sion Lloyd and Nominet as part of the
OpenDNSSEC project.