keymgr – DNSSEC key management utility

Synopsis

keymgr [global-options] [command...] [arguments...]

keymgr [global-options] [command...] help

Description

The keymgr utility serves for DNSSEC keys and KASP (Key And Signature Policy) management in Knot DNS server. The configuration is stored in a so called KASP database. The database is simply a directory on the file-system containing files in the JSON format.

The operations are organized into commands and subcommands. The command specifies the operation to be performed with the KASP database. It is usually followed by named arguments. A special command help can be used to list available subcommands at that position. Listing of available command arguments is not supported yet.

The command and argument names are parsed in a smart way. Only a beginning of the name can be specified and will be recognized. The specified part must be unique amongst the other names.

Global options

–dir path
The location of the KASP database to work with. Defaults to current working directory.

Main commands

init
Initialize new KASP database.
zone ...
Operations with zones in the database. A zone holds assigned signing configuration and signing metadata.
policy ...
Operations with KASP policies. The policy holds parameters that define the way how a zone is signed.
keystore ...
Operations with private key store content. The private key store holds private key material separately from zone metadata.

zone commands

zone add zone-name [policy policy-name|none]
Add a zone into the database. The policy defaults to none, meaning that no automatic key management is to be performed.
zone list [pattern]
List zones in the database matching the pattern as a substring.
zone remove zone-name [force]
Remove a zone from the database. If some keys are currently active, the force argument must be specified.
zone set zone-name [policy policy-name|none]
Change zone configuration. At the moment, only a policy can be changed.
zone show zone-name
Show zone details.
zone key list zone-name
List key IDs and tags of zone keys.
zone key show zone-name key
Show zone key details. The key can be a key tag or a key ID prefix.
zone key generate zone-name [key-parameter...]
Generate a new key for a zone.
zone key import zone-name key-file
Import an existing key in the legacy format. The key-file suffix .private or .key is not required. A public key without a matching private key cannot be imported.
zone key set zone-name key [key-parameter...]
Change a key parameter. Only key timing parameters can be changed.

Available key-parameters:

algorithm id
Algorithm number or IANA mnemonic.
size bits
Size of the key in bits.
ksk
Set the DNSKEY SEP (Secure Entry Point) flag.
publish time
The time the key is publish as a DNSKEY record.
active time
The time the key is started to be used for signing.
retire time
The time the key is stopped to be used for signing.
remove time
The time the key’s DNSKEY is removed from the zone.

The time accepts YYYYMMDDHHMMSS format, unix timestamp, or offset from the current time. For the offset, add + or - prefix and optionally a suffix mi, h, d, w, mo, or y. If no suffix is specified, the offset is in seconds.

policy commands

policy list
List policies in the database.
policy show policy-name
Show policy details.
policy add policy-name [policy-parameter...]
Add a new policy into the database.
policy set policy-name [policy-parameter...]
Change policy configuration.
policy remove policy-name
Remove a policy from the database. Note, the utility does not check if the policy is used.

Available policy-parameters:

algorithm id
DNSKEY algorithm number or IANA mnemonic.
dnskey-ttl seconds
TTL value for DNSKEY records. Note, the value is temporarily overridden by the SOA TTL.
ksk-size bits
Set size of the KSK in bits.
zsk-size bits
Set size of the ZSK in bits.
zsk-lifetime seconds
Interval after which the ZSK rollover will be initiated.
rrsig-lifetime seconds
Lifetime of issued RRSIGs.
rrsig-refresh seconds
How long before RRSIG expiration it will be refreshed.
nsec3 enable
Specifies if NSEC3 will be used instead of NSEC. Note, currently unused (the setting is derived from NSEC3PARAM presence in the zone).
soa-min-ttl seconds
SOA Minimum TTL field. Note, Knot DNS overwrites the value with the real used value.
zone-max-ttl seconds
Max TTL in the zone. Note, Knot DNS will determine the value automatically in the future.
delay secones
Zone signing and data propagation delay. The value is added for safety to timing of all rollover steps.

keystore commands

The key store functionality is limited at the moment. Only one instance of file-based key store is supported. This command is subject to change.

keystore list
List private keys in the key store.

Examples

  1. Initialize new KASP database, add a policy named default with default parameters, and add a zone example.com. The zone will use the created policy:

    $ keymgr init
    $ keymgr policy add default
    $ keymgr zone add example.com policy default
    
  2. List zones containing .com substring:

    $ keymgr zone list .com
    
  3. Add a testing policy lab with rapid key rollovers. Apply the policy to an existing zone:

    $ keymgr policy add lab rrsig-lifetime 300 rrsig-refresh 150 zsk-lifetime 600 delay 10
    $ keymgr zone set example.com policy lab
    
  4. Add an existing and already secured zone. Let the keys be managed by the KASP. Make sure to import all used keys. Also the used algorithm must match with the one configured in the policy:

    $ keymgr zone add example.com policy default
    $ keymgr zone key import example.com Kexample.com+010+12345.private
    $ keymgr zone key import example.com Kexample.com+010+67890.private
    
  5. Disable automatic key management for a secured zone:

    $ keymgr zone set example.com policy none
    
  6. Add a zone to be signed with manual key maintenance. Generate one ECDSA signing key. The Single-Type Signing scheme will be used:

    $ keymgr zone add example.com policy none
    $ keymgr zone key gen example.com algo 13 size 256
    
  7. Add a zone to be signed with manual key maintenance. Generate two RSA-SHA-256 signing keys. The first key will be used as a KSK, the second one as a ZSK:

    $ keymgr zone add example.com policy none
    $ keymgr zone key generate example.com algorithm rsasha256 size 2048 ksk
    $ keymgr zone key generate example.com algorithm rsasha256 size 1024
    

See Also

RFC 6781 - DNSSEC Operational Practices.

knot.conf(5), knotc(8), knotd(8).