300 lines
9.4 KiB
Plaintext
300 lines
9.4 KiB
Plaintext
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "DNSSEC-KEYMGR" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9"
|
|
.SH NAME
|
|
dnssec-keymgr \- ensure correct DNSKEY coverage based on a defined policy
|
|
.
|
|
.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
|
|
:program:\fBdnssec\-keymgr\fP [\fB\-K\fP\fIdirectory\fP] [\fB\-c\fP\fIfile\fP] [\fB\-f\fP]
|
|
[\fB\-k\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-z\fP] [\fB\-g\fP\fIpath\fP] [\fB\-s\fP\fIpath\fP]
|
|
[zone...]
|
|
.SH DESCRIPTION
|
|
.sp
|
|
\fBdnssec\-keymgr\fP is a high level Python wrapper to facilitate the key
|
|
rollover process for zones handled by BIND. It uses the BIND commands
|
|
for manipulating DNSSEC key metadata: \fBdnssec\-keygen\fP and
|
|
\fBdnssec\-settime\fP\&.
|
|
.sp
|
|
DNSSEC policy can be read from a configuration file (default
|
|
/etc/dnssec\-policy.conf), from which the key parameters, publication and
|
|
rollover schedule, and desired coverage duration for any given zone can
|
|
be determined. This file may be used to define individual DNSSEC
|
|
policies on a per\-zone basis, or to set a "default" policy used for all
|
|
zones.
|
|
.sp
|
|
When \fBdnssec\-keymgr\fP runs, it examines the DNSSEC keys for one or more
|
|
zones, comparing their timing metadata against the policies for those
|
|
zones. If key settings do not conform to the DNSSEC policy (for example,
|
|
because the policy has been changed), they are automatically corrected.
|
|
.sp
|
|
A zone policy can specify a duration for which we want to ensure the key
|
|
correctness (\fBcoverage\fP). It can also specify a rollover period
|
|
(\fBroll\-period\fP). If policy indicates that a key should roll over
|
|
before the coverage period ends, then a successor key will automatically
|
|
be created and added to the end of the key series.
|
|
.sp
|
|
If zones are specified on the command line, \fBdnssec\-keymgr\fP will
|
|
examine only those zones. If a specified zone does not already have keys
|
|
in place, then keys will be generated for it according to policy.
|
|
.sp
|
|
If zones are \fInot\fP specified on the command line, then \fBdnssec\-keymgr\fP
|
|
will search the key directory (either the current working directory or
|
|
the directory set by the \fB\-K\fP option), and check the keys for all the
|
|
zones represented in the directory.
|
|
.sp
|
|
Key times that are in the past will not be updated unless the \fB\-f\fP is
|
|
used (see below). Key inactivation and deletion times that are less than
|
|
five minutes in the future will be delayed by five minutes.
|
|
.sp
|
|
It is expected that this tool will be run automatically and unattended
|
|
(for example, by \fBcron\fP).
|
|
.SH OPTIONS
|
|
.sp
|
|
\fB\-c\fP \fIfile\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
If \fB\-c\fP is specified, then the DNSSEC policy is read from \fBfile\fP\&.
|
|
(If not specified, then the policy is read from
|
|
/etc/dnssec\-policy.conf; if that file doesnt exist, a built\-in global
|
|
default policy is used.)
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-f\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Force: allow updating of key events even if they are already in the
|
|
past. This is not recommended for use with zones in which keys have
|
|
already been published. However, if a set of keys has been generated
|
|
all of which have publication and activation dates in the past, but
|
|
the keys have not been published in a zone as yet, then this option
|
|
can be used to clean them up and turn them into a proper series of
|
|
keys with appropriate rollover intervals.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-g\fP \fIkeygen\-path\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Specifies a path to a \fBdnssec\-keygen\fP binary. Used for testing. See
|
|
also the \fB\-s\fP option.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-h\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Print the \fBdnssec\-keymgr\fP help summary and exit.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-K\fP \fIdirectory\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Sets the directory in which keys can be found. Defaults to the
|
|
current working directory.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-k\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Only apply policies to KSK keys. See also the \fB\-z\fP option.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-q\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Quiet: suppress printing of \fBdnssec\-keygen\fP and \fBdnssec\-settime\fP\&.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-s\fP \fIsettime\-path\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Specifies a path to a \fBdnssec\-settime\fP binary. Used for testing.
|
|
See also the \fB\-g\fP option.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-v\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Print the \fBdnssec\-keymgr\fP version and exit.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fB\-z\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Only apply policies to ZSK keys. See also the \fB\-k\fP option.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH POLICY CONFIGURATION
|
|
.sp
|
|
The dnssec\-policy.conf file can specify three kinds of policies:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
· \fIPolicy classes\fP (\fBpolicy\fP\fIname\fP\fB{ ... };\fP) can be
|
|
inherited by zone policies or other policy classes; these can be used
|
|
to create sets of different security profiles. For example, a policy
|
|
class \fBnormal\fP might specify 1024\-bit key sizes, but a class
|
|
\fBextra\fP might specify 2048 bits instead; \fBextra\fP would be used
|
|
for zones that had unusually high security needs.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
· \fIAlgorithm policies:\fP (\fBalgorithm\-policy\fP\fIalgorithm\fP\fB{ ...
|
|
};\fP ) override default per\-algorithm settings. For example, by
|
|
default, RSASHA256 keys use 2048\-bit key sizes for both KSK and ZSK.
|
|
This can be modified using \fBalgorithm\-policy\fP, and the new key
|
|
sizes would then be used for any key of type RSASHA256.
|
|
.sp
|
|
· \fIZone policies:\fP (\fBzone\fP\fIname\fP\fB{ ... };\fP ) set policy for a
|
|
single zone by name. A zone policy can inherit a policy class by
|
|
including a \fBpolicy\fP option. Zone names beginning with digits
|
|
(i.e., 0\-9) must be quoted. If a zone does not have its own policy
|
|
then the "default" policy applies.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Options that can be specified in policies:
|
|
.sp
|
|
\fBalgorithm\fP \fIname\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
The key algorithm. If no policy is defined, the default is RSASHA256.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBcoverage\fP \fIduration\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
The length of time to ensure that keys will be correct; no action
|
|
will be taken to create new keys to be activated after this time.
|
|
This can be represented as a number of seconds, or as a duration
|
|
using human\-readable units (examples: "1y" or "6 months"). A default
|
|
value for this option can be set in algorithm policies as well as in
|
|
policy classes or zone policies. If no policy is configured, the
|
|
default is six months.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBdirectory\fP \fIpath\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Specifies the directory in which keys should be stored.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBkey\-size\fP \fIkeytype\fP \fIsize\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Specifies the number of bits to use in creating keys. The keytype is
|
|
either "zsk" or "ksk". A default value for this option can be set in
|
|
algorithm policies as well as in policy classes or zone policies. If
|
|
no policy is configured, the default is 2048 bits for RSA keys.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBkeyttl\fP \fIduration\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
The key TTL. If no policy is defined, the default is one hour.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBpost\-publish\fP \fIkeytype\fP \fIduration\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
How long after inactivation a key should be deleted from the zone.
|
|
Note: If \fBroll\-period\fP is not set, this value is ignored. The
|
|
keytype is either "zsk" or "ksk". A default duration for this option
|
|
can be set in algorithm policies as well as in policy classes or zone
|
|
policies. The default is one month.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBpre\-publish\fP \fIkeytype\fP \fIduration\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
How long before activation a key should be published. Note: If
|
|
\fBroll\-period\fP is not set, this value is ignored. The keytype is
|
|
either "zsk" or "ksk". A default duration for this option can be set
|
|
in algorithm policies as well as in policy classes or zone policies.
|
|
The default is one month.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBroll\-period\fP \fIkeytype\fP \fIduration\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
How frequently keys should be rolled over. The keytype is either
|
|
"zsk" or "ksk". A default duration for this option can be set in
|
|
algorithm policies as well as in policy classes or zone policies. If
|
|
no policy is configured, the default is one year for ZSKs. KSKs do
|
|
not roll over by default.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBstandby\fP \fIkeytype\fP \fInumber\fP;
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Not yet implemented.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH REMAINING WORK
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
· Enable scheduling of KSK rollovers using the \fB\-P sync\fP and \fB\-D
|
|
sync\fP options to \fBdnssec\-keygen\fP and \fBdnssec\-settime\fP\&. Check the
|
|
parent zone (as in \fBdnssec\-checkds\fP) to determine when its safe for
|
|
the key to roll.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
· Allow configuration of standby keys and use of the REVOKE bit, for
|
|
keys that use RFC 5011 semantics.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fBdnssec\-coverage\fP(8), \fBdnssec\-keygen\fP(8),
|
|
\fBdnssec\-settime\fP(8), \fBdnssec\-checkds\fP(8)
|
|
.SH AUTHOR
|
|
Internet Systems Consortium
|
|
.SH COPYRIGHT
|
|
2020, Internet Systems Consortium
|
|
.\" Generated by docutils manpage writer.
|
|
.
|