Provided by: knot_2.1.1-1build1_amd64 
NAME
keymgr - DNSSEC key management utility
SYNOPSIS
keymgr [global-options] [command...] [arguments...]
keymgr [global-options] [command...] help
DESCRIPTION
The keymgr utility serves for key management in Knot DNS server.
Primarily functions for DNSSEC keys and KASP (Key And Signature Policy) management are provided. However
the utility also provides functions for TSIG key generation.
The DNSSEC and KASP configuration is stored in a so called KASP database. The database is simply a
directory in the file-system containing files in the JSON format.
The operations are organized into commands and subcommands. A command specifies the operation to be
performed with the KASP database. It is usually followed by named arguments. The special command help can
be used to list available subcommands in that area. The listing of available command arguments is not
supported yet.
Command and argument names are parsed in a smart way. Only a beginning of a name can be entered and it
will be recognized. The specified part of a name 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 or upgrade existing one. The command is idempotent and therefore it
is safe to be run multiple times.
The command creates a default policy and default key store (both named default). In case of
upgrade, existing objects are checked and any missing attributes are filled in.
zone ...
Operations with zones in the database. A zone holds assigned signing configuration and signing
metadata.
policy ...
Operations with KASP policies. A policy holds parameters that define the way how a zone is signed.
keystore ...
Operations with key stores configured for the KASP database. A private key store holds private key
material for zone signing separately from the zone metadata.
tsig ...
Operations with TSIG keys.
zone commands
zone add zone-name [policy policy-name]
Add a zone into the database. The policy defaults to 'default'.
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]
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 ds zone-name key
Show DS records for a zone key. 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 published 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
Size of the KSK.
zsk-size bits
Size of the ZSK.
zsk-lifetime seconds
Period between ZSK publication and the next rollover initiation.
rrsig-lifetime seconds
Validity period of issued signatures.
rrsig-refresh seconds
Period before signature expiration when the signature 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 seconds
Zone signing and data propagation delay. The value is added for safety to timing of all
rollover steps.
manual enable
Enable manual key management. If enabled, no keys will be generated or rolled automatically.
keystore name
Name of the key store to be used for private key material.
keystore commands
keystore list
List names of configured key stores.
keystore show name
Show configuration of a key store named name and list key IDs of private key material present in
that key store.
keystore add name [backend backend] [config config]
Configure new key store. The name is a unique key store identifier. The backend and
backend-specific configuration string config determine where the private key material will be
physically stored.
Supported key store backends:
pkcs8 (default)
The backend stores private key material in unencrypted X.509 PEM files in a directory specified
as the backend configuration string. The path can be specified relatively to the KASP database
location.
pkcs11 The backend stores private key material in a cryptographic token accessible via the PKCS #11
interface. The configuration string consists of a token PKCS #11 URL and PKCS #11 module path
separated by the space character.
The format of the PKCS #11 URL is described in RFC 7512. If the token is protected by a PIN,
make sure to include pin-value or pin-source attribute in the URL.
The PKCS #11 module path can be an absolute path or just a module name. In the later case, the
module is looked up in the default modules location.
tsig commands
tsig generate name [algorithm id] [size bits]
Generate new TSIG key and print it on the standard output. The algorithm defaults to hmac-sha256.
The default key size is determined optimally based on the selected algorithm.
The generated key is printed out in the server configuration format to allow direct inclusion into
the server configuration. The first line of the output contains a comment with the key in the
one-line key format accepted by client utilities.
EXAMPLES
1. Initialize a new KASP database and add a zone example.com with the default policy assigned:
$ 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. For this purpose, create a policy named 'manual'
with otherwise default signing parameters:
$ keymgr policy add manual manual true
$ keymgr zone set example.com policy manual
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 policy add manual manual true
$ keymgr zone add example.com policy manual
$ 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 policy add manual manual true
$ keymgr zone add example.com policy manual
$ keymgr zone key generate example.com algorithm rsasha256 size 2048 ksk
$ keymgr zone key generate example.com algorithm rsasha256 size 1024
8. Generate a TSIG key named operator.key:
$ keymgr tsig generate operator.key algorithm hmac-sha512
9. Add a new key store named hsm and backed by the SoftHSM PKCS #11 module, then add a new policy named
secure with default parameters using this key store, and finally add the zone example.com which will
use this policy:
$ keymgr keystore add hsm backend pkcs11 \
config "pkcs11:token=knot;pin-value=1234 libsofthsm2.so"
$ keymgr policy add secure keystore hsm
$ keymgr zone add example.com policy secure
SEE ALSO
RFC 6781 - DNSSEC Operational Practices.
knot.conf(5), knotc(8), knotd(8).
AUTHOR
CZ.NIC Labs <http://www.knot-dns.cz>
COPYRIGHT
Copyright 2010–2016, CZ.NIC, z.s.p.o.