NAME
ods-ksmutil - OpenDNSSEC zone and key management
SYNOPSIS
ods-ksmutil setup
ods-ksmutil update kasp|zonelist|conf|all
ods-ksmutil zone add|delete|list ...
ods-ksmutil key generate|import|export|list|purge|rollover|ksk-
retire|ds-seen ...
ods-ksmutil rollover list ...
ods-ksmutil policy export ...
ods-ksmutil repository list ...
ods-ksmutil backup list|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.
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 respecive
configuration file, or all those files. The result is
comparable to the setup subcommand, except that management
information about OpenDNSSEC is not deleted.
ZONE MANAGEMENT SUBCOMMANDS
zone add --zone|-z zone [--policy|-p name] [--input|-i input]
[--output|-o output]
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 --input option specifies a non-standard location
for the unsigned zone (default is
/var/lib/opendnssec/unsigned/ZONE); the --output option
specifies a non-standard location for the signed zone (default
is /var/lib/opendnssec/signed/ZONE).
zone delete --zone|-z name
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.
zone list
List zones from the zonelist.xml. TODO:Not from the database?
KEY MANAGEMENT SUBCOMMANDS
key generate --policy|-p name --interval|-n interval
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.
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 [--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 --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]
key list --all [--verbose]
List information about keys in a particular zone, or all zones,
respectively. The --verbose option is used to list additional
information about each key.
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]
key rollover --policy|-p name [--keytype type]
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 (both are
rolled if nothing is specified) 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 --keytag|-x keytag
key ds-seen --cka_id|-k ckaid
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-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.
ods-ksmutil 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.
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 done --repository|-r name
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. This is
a necessary step for repositories that have the RequireBackup
flag set.
Note that the KASP Enforcer may take the initiative to generate
keys after the backup has started and before the backup is done.
In the current version of OpenDNSSEC, it is therefore needed to
stop the KASP Enforcer to be assured that all keys are backed
up. The sequence would therefore be:
1. Issue ods-control ksm stop
2. Make a backup of the repository
3. Issue ods-ksmutil backup done
4. Issue ods-control ksm start
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.
KEY STATES
GENERATED
The key has just been generated, but is not ready for use.
PUBLISHED
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.
RETIRED
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.
INTERVAL FORMAT
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.
TIME FORMATS
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-auditor(1), 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.