keymgr(8)
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
-c, --config file
Use a textual configuration file to get the KASP database
location.
-C, --confdb directory
Use a binary configuration database directory to get the KASP
database location.
-d, --dir path
Use a specified KASP database path to work with.
-h, --help
Print the program help.
-l, --legacy
Enable legacy mode. Zone, policy, and keystore configuration is
stored in KASP database (not in server configuration).
-V, --version
Print the program version.
KASP database location
The location of the KASP database is determined as follows:
1. The path specified with --dir.
2. The path read from the server configuration specified with --confdb
or --config.
3. The path read from the server default configuration database.
4. The path read from the server default configuration file.
In legacy mode, the path is determined as follows:
1. The path specified with --dir.
2. The path specified in the KEYMGR_DIR environment variable.
3. The current working dir.
Main commands
tsig ...
Operations with TSIG keys.
zone ...
Operations with zones in the database. A zone holds assigned
signing configuration and signing metadata.
Main commands (legacy)
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.
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 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.
zone commands
zone key list zone-name [filter]
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.
zone commands (legacy)
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.
policy commands (legacy)
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.
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.
nsec3-iterations iterations
Specifies the number of additional iterations in NSEC3
computation.
nsec3-salt-length bytes
Specifies salt length for NSEC3 computation.
nsec3-salt-lifetime seconds
Period after which a new NSEC3 salt is generated.
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 (legacy)
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.
EXAMPLES
1. Generate two RSA-SHA-256 signing keys. The first key will be used as
a KSK, the second one as a ZSK:
$ keymgr zone key generate example.com algorithm rsasha256 size 2048 ksk
$ keymgr zone key generate example.com algorithm rsasha256 size 1024
2. Import a key in legacy format. The used algorithm must match with
the one configured in the policy:
$ keymgr zone key import example.com Kexample.com+010+12345.private
3. Generate a TSIG key named operator.key:
$ keymgr tsig generate operator.key algorithm hmac-sha512
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.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
