xenial (1) ods-ksmutil.1.gz

Provided by: opendnssec-enforcer-mysql_1.4.9-2_amd64 bug

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.

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-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.