FreeBSD Manual Pages

home | help

KEYMGR(8) Knot DNS KEYMGR(8)

NAME
keymgr - Knot DNS key management utility

SYNOPSIS
keymgr [config_option] [options] zone_name command

keymgr [config_option] [options] keystore_id command

keymgr [config_option] [-j] -l

keymgr -t parameter...

DESCRIPTION
The keymgr utility serves for manual key management in Knot DNS server.

Functions for DNSSEC keys and KASP (Key And Signature Policy) management
are provided.

The DNSSEC and KASP configuration is stored in a so called KASP database.
The database is backed by LMDB.

Parameters
zone_name
Name of the zone the command is executed for.

Config options
-c, --config file
Use a textual configuration file (default is /usr/lo-
cal/etc/knot/knot.conf).

-C, --confdb directory
Use a binary configuration database directory (default is /usr/lo-
cal/var/lib/knot/confdb). The default configuration database, if
exists, has a preference to the default configuration file.

-D, --dir path
Use specified KASP database path and default configuration.

Options
-t, --tsig tsig_name [tsig_algorithm [tsig_bits]]
Generates a TSIG key for the given name. Optionally the key algo-
rithm can be specified by its name (default: hmac-sha256) and a bit
length of the key (default: optimal length given by algorithm). The
generated TSIG key is only displayed on stdout: the command does not
create a file, nor include the key in a keystore.

-e, --extended
Extended output (listing of keys with full description).

-j, --json
Print the zones or keys (not TSIG keys) in JSON format.

-l, --list
Print the list of zones that have at least one key stored in the
configured KASP database.

-x, --mono
Don't generate colorized output.

-X, --color
Force colorized output in the normal mode.

-h, --help
Print the program help.

-V, --version
Print the program version. The option -VV makes the program print
the compile time configuration summary.

NOTE:
Keymgr runs with the same user privileges as configured for knotd. For
example, if keymgr is run as root, but the configured user is knot, it
won't be able to read files (PEM files, KASP database, ...) readable
only by root.

Commands
list [timestamp_format]
Prints the list of key IDs and parameters of keys belonging to the
zone.

generate [arguments...]
Generates new DNSSEC key and stores it in KASP database. Prints the
key ID. This action takes some number of arguments (see below).
Values for unspecified arguments are taken from corresponding policy
(if -c or -C options used) or from Knot policy defaults.

import-bind BIND_key_file
Imports a BIND-style key into KASP database (converting it to PEM
format). Takes one argument: path to BIND key file (private or pub-
lic, but both MUST exist).

import-pub BIND_pubkey_file
Imports a public key into KASP database. This key won't be rolled
over nor used for signing. Takes one argument: path to BIND public
key file.

import-pem PEM_file [arguments...]
Imports a DNSSEC key from PEM file. The key parameters (same as for
the generate action) need to be specified (mainly algorithm,
timers...) because they are not contained in the PEM format.

import-pkcs11 key_id [arguments...]
Imports a DNSSEC key from PKCS #11 storage. The key parameters (same
as for the generate action) need to be specified (mainly algorithm,
timers...) because they are not available. In fact, no key data is
imported, only KASP database metadata is created.

nsec3-salt [new_salt]
Prints the current NSEC3 salt used for signing. If new_salt is spec-
ified, the salt is overwritten. The salt is printed and expected in
hexadecimal, or dash if empty.

master-serial [new_serial]
Print SOA serial of the remote master stored in KASP database when
using on-secondary DNSSEC signing. If new_serial is specified, the
serial is overwritten (not recommended).

set key_spec [arguments...]
Changes a timing argument (or ksk/zsk) of an existing key to a new
value. Key_spec is either the key tag or a prefix of the key ID,
with an optional [id=|keytag=] prefix; arguments are like for gener-
ate, but just the related ones.

ds [key_spec]
Generate DS record (all digest algorithms together) for specified
key. Key_spec is like for set, if unspecified, all KSKs are used.

dnskey [key_spec]
Generate DNSKEY record for specified key. Key_spec is like for ds,
if unspecified, all KSKs are used.

delete key_spec
Remove the specified key from zone. If the key was not shared, it is
also deleted from keystore.

share key_ID zone_from
Import a key (specified by full key ID) from another zone as shared.
After this, the key is owned by both zones equally.

Keystore commands
keystore-test
Conduct some tests on the specified keystore. For each algorithm,
key generation, import, removal, and use (signing and verification)
are tested. Use a configured keystore_id or - for the default.

keystore-bench [num_threads]
Conduct a signing benchmark on the specified keystore. Random
blocks of data are signed by the selected number of threads (default
is 1) in a loop, and the average number of signing operations per
second for each algorithm is returned. Use a configured keystore_id
or - for the default.

Commands related to Offline KSK feature
pregenerate [timestamp-from] timestamp-to
Pre-generate ZSKs for use with offline KSK, for the specified period
starting from now or specified time. This function also applies to
non-offline KSK keys.

show-offline [timestamp-from] [timestamp-to]
Print pre-generated offline key-related records for specified time
interval. If timestamp_to is omitted, it will be to infinity. If
timestamp-from is omitted, it will start from the beginning.

del-offline timestamp-from timestamp-to
Delete pre-generated offline key-related records in specified time
interval.

del-all-old
Delete old keys that are in state 'removed'. This function also ap-
plies to non-offline KSK keys.

generate-ksr [timestamp-from] timestamp-to
Print to stdout KeySigningRequest based on pre-generated ZSKs for
specified time period. If timestamp-from is omitted, timestamp of
the last offline records set is used or now if no records available.

sign-ksr ksr_file
Read KeySigningRequest from a text file, sign it using local keyset
and print SignedKeyResponse to stdout.

validate-skr skr_file
Read SignedKeyResponse from a text file and validate the RRSIGs in
it if not corrupt.

import-skr skr_file
Read SignedKeyResponse from a text file and import the signatures
for later use in zone. If some signatures have already been im-
ported, they will be deleted for the period from beginning of the
SKR to infinity.

Generate arguments
Arguments are separated by space, each of them is in format 'name=value'. A
(bool) argument accepts values yes or no. If the value is omitted, it's in-
terpreted as yes.

algorithm
Either an algorithm number (e.g. 14) or algorithm name (e.g. ecd-
sap256sha256).

size Key length in bits.

ksk (bool) The key will be used for signing DNSKEY rrset. The generated
key will also have the Secure Entry Point flag set to 1.

zsk (bool) The key will be used for signing zone (except DNSKEY rrset).
This flag can be set concurrently with the ksk flag (for a CSK key).

sep (bool) Overrides the standard setting of the Secure Entry Point
flag.

for-later
(bool) The key will be determined for later use. It means once a new
key ought to be generated, this one will be used instead if the key
type and algorithm match.

The following arguments are timestamps of key lifetime (see DNSSEC key
states):

pre_active
Key started to be used for signing, not published (only for algo-
rithm rollover).

publish
Key published.

ready Key is waiting for submission (only for KSK).

active
Key used for signing.

retire_active
Key still used for signing, but another key is active (only for KSK
or algorithm rollover).

retire
Key still published (only if ZSK), but no longer used for signing.

post_active
Key no longer published, but still used for signing (only for algo-
rithm rollover).

revoke
Key revoked according to RFC 5011 trust anchor roll-over.

remove
Key deleted.

Timestamps
0 Zero timestamp means infinite future.

UNIX_time
Positive number of seconds since 1970 UTC.

YYYYMMDDHHMMSS
Date and time in this format without any punctuation.

relative_timestamp
A sign character (+, -), a number, and an optional time unit (y, mo,
d, h, mi, s). The default unit is one second. E.g. +1mi, -2mo.

Output timestamp formats
(none)
The timestamps are printed as UNIX timestamp.

human The timestamps are printed relatively to now using time units (e.g.
-2y5mo, +1h13s).

iso The timestamps are printed in the ISO8601 format (e.g.
2016-12-31T23:59:00).

EXIT VALUES
Exit status of 0 means successful operation. Any other exit status indi-
cates an error.

EXAMPLES
1. Generate new TSIG key:

$ keymgr -t my_name hmac-sha384

2. Generate new DNSSEC key:

$ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \
ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y

3. Import a DNSSEC key from BIND:

$ keymgr example.com. import-bind ~/bind/Kharbinge4d5.+007+63089.key

4. Import a CSK DNSSEC key from a PEM file:

$ keymgr example.com. import-pem 085d3890e8c22d854586678d9263933f2d02d795.pem ksk=yes zsk=yes

5. Configure key timing:

$ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi

6. Share a KSK from another zone:

$ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another-zone.com.

SEE ALSO
RFC 6781 - DNSSEC Operational Practices. RFC 7583 - DNSSEC Key Rollover
Timing Considerations.

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

AUTHOR
CZ.NIC, z.s.p.o. and contributors <https://www.knot-dns.cz/>

3.5.6 2026-07-20 KEYMGR(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=keymgr&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages