.\" Man page generated from reStructuredText.
.
.TH "KEYMGR" "8" "" "2.3.2" "Knot DNS"
.SH NAME
keymgr \-  DNSSEC key management utility
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBkeymgr\fP [\fIglobal\-options\fP] [\fIcommand\fP\&...] [\fIarguments\fP\&...]
.sp
\fBkeymgr\fP [\fIglobal\-options\fP] [\fIcommand\fP\&...] \fBhelp\fP
.SH DESCRIPTION
.sp
The \fBkeymgr\fP utility serves for key management in Knot DNS server.
.sp
Primarily functions for DNSSEC keys and KASP (Key And Signature Policy)
management are provided. However the utility also provides functions for
TSIG key generation.
.sp
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.
.sp
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 \fBhelp\fP can be used to list
available subcommands in that area. The listing of available command arguments
is not supported yet.
.sp
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.
.SS Global options
.INDENT 0.0
.TP
\fB\-c\fP, \fB\-\-config\fP \fIfile\fP
Use a textual configuration file to get the KASP database location.
.TP
\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP
Use a binary configuration database directory to get the KASP database location.
.TP
\fB\-d\fP, \fB\-\-dir\fP \fIpath\fP
Use a specified KASP database path to work with.
.TP
\fB\-h\fP, \fB\-\-help\fP
Print the program help.
.TP
\fB\-l\fP, \fB\-\-legacy\fP
Enable legacy mode. Zone, policy, and keystore configuration is stored
in KASP database (not in server configuration).
.TP
\fB\-V\fP, \fB\-\-version\fP
Print the program version.
.UNINDENT
.SS KASP database location
.sp
The location of the KASP database is determined as follows:
.INDENT 0.0
.IP 1. 3
The path specified with \fB\-\-dir\fP\&.
.IP 2. 3
The path read from the server configuration specified with \fB\-\-confdb\fP or
\fB\-\-config\fP\&.
.IP 3. 3
The path read from the server default configuration database.
.IP 4. 3
The path read from the server default configuration file.
.UNINDENT
.sp
In legacy mode, the path is determined as follows:
.INDENT 0.0
.IP 1. 3
The path specified with \fB\-\-dir\fP\&.
.IP 2. 3
The path specified in the \fBKEYMGR_DIR\fP environment variable.
.IP 3. 3
The current working dir.
.UNINDENT
.SS Main commands
.INDENT 0.0
.TP
\fBtsig\fP ...
Operations with TSIG keys.
.TP
\fBzone\fP ...
Operations with zones in the database. A zone holds assigned signing
configuration and signing metadata.
.UNINDENT
.SS Main commands (legacy)
.INDENT 0.0
.TP
\fBinit\fP
Initialize new KASP database or upgrade existing one. The command is
idempotent and therefore it is safe to be run multiple times.
.sp
The command creates a default policy and default key store (both named
\fIdefault\fP). In case of upgrade, existing objects are checked and any missing
attributes are filled in.
.TP
\fBpolicy\fP ...
Operations with KASP policies. A policy holds parameters that define the
way how a zone is signed.
.TP
\fBkeystore\fP ...
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.
.UNINDENT
.SS tsig commands
.INDENT 0.0
.TP
\fBtsig\fP \fBgenerate\fP \fIname\fP [\fBalgorithm\fP \fIid\fP] [\fBsize\fP \fIbits\fP]
Generate new TSIG key and print it on the standard output. The algorithm
defaults to \fIhmac\-sha256\fP\&. The default key size is determined optimally based
on the selected algorithm.
.sp
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.
.UNINDENT
.SS zone commands
.INDENT 0.0
.TP
\fBzone\fP \fBkey\fP \fBlist\fP \fIzone\-name\fP [\fBfilter\fP]
List key IDs and tags of zone keys.
.TP
\fBzone\fP \fBkey\fP \fBshow\fP \fIzone\-name\fP \fIkey\fP
Show zone key details. The \fIkey\fP can be a key tag or a key ID prefix.
.TP
\fBzone\fP \fBkey\fP \fBds\fP \fIzone\-name\fP \fIkey\fP
Show DS records for a zone key. The \fIkey\fP can be a key tag or a key ID prefix.
.TP
\fBzone\fP \fBkey\fP \fBgenerate\fP \fIzone\-name\fP [\fIkey\-parameter\fP\&...]
Generate a new key for a zone.
.TP
\fBzone\fP \fBkey\fP \fBimport\fP \fIzone\-name\fP \fIkey\-file\fP
Import an existing key in the legacy format. The \fIkey\-file\fP suffix
\fB\&.private\fP or \fB\&.key\fP is not required. A public key without
a matching private key cannot be imported.
.TP
\fBzone\fP \fBkey\fP \fBset\fP \fIzone\-name\fP \fIkey\fP [\fIkey\-parameter\fP\&...]
Change a key parameter. Only key timing parameters can be changed.
.UNINDENT
.sp
Available \fIkey\-parameter\fPs:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
\fBalgorithm\fP \fIid\fP
Algorithm number or IANA mnemonic.
.TP
\fBsize\fP \fIbits\fP
Size of the key in bits.
.TP
\fBksk\fP
Set the DNSKEY SEP (Secure Entry Point) flag.
.TP
\fBpublish\fP \fItime\fP
The time the key is published as a DNSKEY record.
.TP
\fBactive\fP \fItime\fP
The time the key is started to be used for signing.
.TP
\fBretire\fP \fItime\fP
The time the key is stopped to be used for signing.
.TP
\fBremove\fP \fItime\fP
The time the key\(aqs DNSKEY is removed from the zone.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fItime\fP accepts YYYYMMDDHHMMSS format, unix timestamp, or offset from the
current time. For the offset, add \fB+\fP or \fB\-\fP prefix and optionally a
suffix \fBmi\fP, \fBh\fP, \fBd\fP, \fBw\fP, \fBmo\fP, or \fBy\fP\&. If no suffix is specified,
the offset is in seconds.
.SS zone commands (legacy)
.INDENT 0.0
.TP
\fBzone\fP \fBadd\fP \fIzone\-name\fP [\fBpolicy\fP \fIpolicy\-name\fP]
Add a zone into the database. The policy defaults to \(aqdefault\(aq.
.TP
\fBzone\fP \fBlist\fP [\fIpattern\fP]
List zones in the database matching the \fIpattern\fP as a substring.
.TP
\fBzone\fP \fBremove\fP \fIzone\-name\fP [\fBforce\fP]
Remove a zone from the database. If some keys are currently active, the
\fBforce\fP argument must be specified.
.TP
\fBzone\fP \fBset\fP \fIzone\-name\fP [\fBpolicy\fP \fIpolicy\-name\fP]
Change zone configuration. At the moment, only a policy can be changed.
.TP
\fBzone\fP \fBshow\fP \fIzone\-name\fP
Show zone details.
.UNINDENT
.SS policy commands (legacy)
.INDENT 0.0
.TP
\fBpolicy\fP \fBlist\fP
List policies in the database.
.TP
\fBpolicy\fP \fBshow\fP \fIpolicy\-name\fP
Show policy details.
.TP
\fBpolicy\fP \fBadd\fP \fIpolicy\-name\fP [\fIpolicy\-parameter\fP\&...]
Add a new policy into the database.
.TP
\fBpolicy\fP \fBset\fP \fIpolicy\-name\fP [\fIpolicy\-parameter\fP\&...]
Change policy configuration.
.TP
\fBpolicy\fP \fBremove\fP \fIpolicy\-name\fP
Remove a policy from the database.
\fBNote\fP, the utility does not check if the policy is used.
.UNINDENT
.sp
Available \fIpolicy\-parameter\fPs:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
\fBalgorithm\fP \fIid\fP
DNSKEY algorithm number or IANA mnemonic.
.TP
\fBdnskey\-ttl\fP \fIseconds\fP
TTL value for DNSKEY records.
.TP
\fBksk\-size\fP \fIbits\fP
Size of the KSK.
.TP
\fBzsk\-size\fP \fIbits\fP
Size of the ZSK.
.TP
\fBzsk\-lifetime\fP \fIseconds\fP
Period between ZSK publication and the next rollover initiation.
.TP
\fBrrsig\-lifetime\fP \fIseconds\fP
Validity period of issued signatures.
.TP
\fBrrsig\-refresh\fP \fIseconds\fP
Period before signature expiration when the signature will be refreshed.
.TP
\fBnsec3\fP \fIenable\fP
Specifies if NSEC3 will be used instead of NSEC.
.TP
\fBnsec3\-iterations\fP \fIiterations\fP
Specifies the number of additional iterations in NSEC3 computation.
.TP
\fBnsec3\-salt\-length\fP \fIbytes\fP
Specifies salt length for NSEC3 computation.
.TP
\fBnsec3\-salt\-lifetime\fP \fIseconds\fP
Period after which a new NSEC3 salt is generated.
.TP
\fBsoa\-min\-ttl\fP \fIseconds\fP
SOA Minimum TTL field.
\fBNote\fP, Knot DNS overwrites the value with the real used value.
.TP
\fBzone\-max\-ttl\fP \fIseconds\fP
Max TTL in the zone.
\fBNote\fP, Knot DNS will determine the value automatically in the future.
.TP
\fBdelay\fP \fIseconds\fP
Zone signing and data propagation delay. The value is added for safety to
timing of all rollover steps.
.TP
\fBmanual\fP \fIenable\fP
Enable manual key management. If enabled, no keys will be generated or
rolled automatically.
.TP
\fBkeystore\fP \fIname\fP
Name of the key store to be used for private key material.
.UNINDENT
.UNINDENT
.UNINDENT
.SS keystore commands (legacy)
.INDENT 0.0
.TP
\fBkeystore\fP \fBlist\fP
List names of configured key stores.
.TP
\fBkeystore\fP \fBshow\fP \fIname\fP
Show configuration of a key store named \fIname\fP and list key IDs of private
key material present in that key store.
.TP
\fBkeystore\fP \fBadd\fP \fIname\fP [\fBbackend\fP \fIbackend\fP] [\fBconfig\fP \fIconfig\fP]
Configure new key store. The \fIname\fP is a unique key store identifier. The
\fIbackend\fP and backend\-specific configuration string \fIconfig\fP determine where
the private key material will be physically stored.
.UNINDENT
.sp
Supported key store backends:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
\fBpkcs8\fP (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.
.TP
\fBpkcs11\fP
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.
.sp
The format of the PKCS #11 URL is described in \fI\%RFC 7512\fP\&. If the token
is protected by a PIN, make sure to include \fIpin\-value\fP or \fIpin\-source\fP
attribute in the URL.
.sp
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.
.UNINDENT
.UNINDENT
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.IP 1. 3
Generate two RSA\-SHA\-256 signing keys. The first key will be used as a KSK,
the second one as a ZSK:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ keymgr zone key generate example.com algorithm rsasha256 size 2048 ksk
$ keymgr zone key generate example.com algorithm rsasha256 size 1024
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Import a key in legacy format. The used algorithm must match with the one
configured in the policy:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ keymgr zone key import example.com Kexample.com+010+12345.private
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Generate a TSIG key named \fIoperator.key\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ keymgr tsig generate operator.key algorithm hmac\-sha512
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fI\%RFC 6781\fP \- DNSSEC Operational Practices.
.sp
\fBknot.conf(5)\fP,
\fBknotc(8)\fP,
\fBknotd(8)\fP\&.
.SH AUTHOR
CZ.NIC Labs <http://www.knot-dns.cz>
.SH COPYRIGHT
Copyright 2010–2016, CZ.NIC, z.s.p.o.
.\" Generated by docutils manpage writer.
.