Add .8 and .html files for dnssec-keymgr
This commit is contained in:
Tinderbox User
@@ -1,4 +1,4 @@
|
||||
.\" Copyright (C) 2013-2015 Internet Systems Consortium, Inc. ("ISC")
|
||||
.\" Copyright (C) 2013-2016 Internet Systems Consortium, Inc. ("ISC")
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and/or distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
@@ -47,7 +47,7 @@
|
||||
dnssec-coverage \- checks future DNSKEY coverage for a zone
|
||||
.SH "SYNOPSIS"
|
||||
.HP \w'\fBdnssec\-coverage\fR\ 'u
|
||||
\fBdnssec\-coverage\fR [\fB\-K\ \fR\fB\fIdirectory\fR\fR] [\fB\-l\ \fR\fB\fIlength\fR\fR] [\fB\-f\ \fR\fB\fIfile\fR\fR] [\fB\-d\ \fR\fB\fIDNSKEY\ TTL\fR\fR] [\fB\-m\ \fR\fB\fImax\ TTL\fR\fR] [\fB\-r\ \fR\fB\fIinterval\fR\fR] [\fB\-c\ \fR\fB\fIcompilezone\ path\fR\fR] [\fB\-k\fR] [\fB\-z\fR] [zone]
|
||||
\fBdnssec\-coverage\fR [\fB\-K\ \fR\fB\fIdirectory\fR\fR] [\fB\-l\ \fR\fB\fIlength\fR\fR] [\fB\-f\ \fR\fB\fIfile\fR\fR] [\fB\-d\ \fR\fB\fIDNSKEY\ TTL\fR\fR] [\fB\-m\ \fR\fB\fImax\ TTL\fR\fR] [\fB\-r\ \fR\fB\fIinterval\fR\fR] [\fB\-c\ \fR\fB\fIcompilezone\ path\fR\fR] [\fB\-k\fR] [\fB\-z\fR] [zone...]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBdnssec\-coverage\fR
|
||||
@@ -95,11 +95,13 @@ Sets the value to be used as the maximum TTL for the zone or zones being analyze
|
||||
.sp
|
||||
The length of the TTL can be set in seconds, or in larger units of time by adding a suffix: \*(Aqmi\*(Aq for minutes, \*(Aqh\*(Aq for hours, \*(Aqd\*(Aq for days, \*(Aqw\*(Aq for weeks, \*(Aqmo\*(Aq for months, \*(Aqy\*(Aq for years\&.
|
||||
.sp
|
||||
This option is mandatory unless the
|
||||
This option is not necessary if the
|
||||
\fB\-f\fR
|
||||
has been used to specify a zone file\&. (If
|
||||
has been used to specify a zone file\&. If
|
||||
\fB\-f\fR
|
||||
has been specified, this option may still be used; it will override the value found in the file\&.)
|
||||
has been specified, this option may still be used; it will override the value found in the file\&.
|
||||
.sp
|
||||
If this option is not used and the maximum TTL cannot be retrieved from a zone file, a warning is generated and a default value of 1 week is used\&.
|
||||
.RE
|
||||
.PP
|
||||
\-d \fIDNSKEY TTL\fR
|
||||
@@ -108,12 +110,14 @@ Sets the value to be used as the DNSKEY TTL for the zone or zones being analyzed
|
||||
.sp
|
||||
The length of the TTL can be set in seconds, or in larger units of time by adding a suffix: \*(Aqmi\*(Aq for minutes, \*(Aqh\*(Aq for hours, \*(Aqd\*(Aq for days, \*(Aqw\*(Aq for weeks, \*(Aqmo\*(Aq for months, \*(Aqy\*(Aq for years\&.
|
||||
.sp
|
||||
This option is mandatory unless the
|
||||
This option is not necessary if
|
||||
\fB\-f\fR
|
||||
has been used to specify a zone file, or a default key TTL was set with the
|
||||
has been used to specify a zone file from which the TTL of the DNSKEY RRset can be read, or if a default key TTL was set using ith the
|
||||
\fB\-L\fR
|
||||
to
|
||||
\fBdnssec\-keygen\fR\&. (If either of those is true, this option may still be used; it will override the value found in the zone or key file\&.)
|
||||
\fBdnssec\-keygen\fR\&. If either of those is true, this option may still be used; it will override the values found in the zone file or the key file\&.
|
||||
.sp
|
||||
If this option is not used and the key TTL cannot be retrieved from the zone file or the key file, then a warning is generated and a default value of 1 day is used\&.
|
||||
.RE
|
||||
.PP
|
||||
\-r \fIresign interval\fR
|
||||
@@ -156,5 +160,5 @@ binary\&. Used for testing\&.
|
||||
\fBInternet Systems Consortium, Inc\&.\fR
|
||||
.SH "COPYRIGHT"
|
||||
.br
|
||||
Copyright \(co 2013-2015 Internet Systems Consortium, Inc. ("ISC")
|
||||
Copyright \(co 2013-2016 Internet Systems Consortium, Inc. ("ISC")
|
||||
.br
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
- Copyright (C) 2013-2015 Internet Systems Consortium, Inc. ("ISC")
|
||||
- Copyright (C) 2013-2016 Internet Systems Consortium, Inc. ("ISC")
|
||||
-
|
||||
- Permission to use, copy, modify, and/or distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
@@ -27,7 +27,7 @@
|
||||
</div>
|
||||
<div class="refsynopsisdiv">
|
||||
<h2>Synopsis</h2>
|
||||
<div class="cmdsynopsis"><p><code class="command">dnssec-coverage</code> [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-l <em class="replaceable"><code>length</code></em></code>] [<code class="option">-f <em class="replaceable"><code>file</code></em></code>] [<code class="option">-d <em class="replaceable"><code>DNSKEY TTL</code></em></code>] [<code class="option">-m <em class="replaceable"><code>max TTL</code></em></code>] [<code class="option">-r <em class="replaceable"><code>interval</code></em></code>] [<code class="option">-c <em class="replaceable"><code>compilezone path</code></em></code>] [<code class="option">-k</code>] [<code class="option">-z</code>] [zone]</p></div>
|
||||
<div class="cmdsynopsis"><p><code class="command">dnssec-coverage</code> [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-l <em class="replaceable"><code>length</code></em></code>] [<code class="option">-f <em class="replaceable"><code>file</code></em></code>] [<code class="option">-d <em class="replaceable"><code>DNSKEY TTL</code></em></code>] [<code class="option">-m <em class="replaceable"><code>max TTL</code></em></code>] [<code class="option">-r <em class="replaceable"><code>interval</code></em></code>] [<code class="option">-c <em class="replaceable"><code>compilezone path</code></em></code>] [<code class="option">-k</code>] [<code class="option">-z</code>] [zone...]</p></div>
|
||||
</div>
|
||||
<div class="refsection">
|
||||
<a name="id-1.7"></a><h2>DESCRIPTION</h2>
|
||||
@@ -104,10 +104,15 @@
|
||||
'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
|
||||
</p>
|
||||
<p>
|
||||
This option is mandatory unless the <code class="option">-f</code> has
|
||||
been used to specify a zone file. (If <code class="option">-f</code> has
|
||||
This option is not necessary if the <code class="option">-f</code> has
|
||||
been used to specify a zone file. If <code class="option">-f</code> has
|
||||
been specified, this option may still be used; it will override
|
||||
the value found in the file.)
|
||||
the value found in the file.
|
||||
</p>
|
||||
<p>
|
||||
If this option is not used and the maximum TTL cannot be retrieved
|
||||
from a zone file, a warning is generated and a default value of
|
||||
1 week is used.
|
||||
</p>
|
||||
</dd>
|
||||
<dt><span class="term">-d <em class="replaceable"><code>DNSKEY TTL</code></em></span></dt>
|
||||
@@ -116,11 +121,10 @@
|
||||
Sets the value to be used as the DNSKEY TTL for the zone or
|
||||
zones being analyzed when determining whether there is a
|
||||
possibility of validation failure. When a key is rolled (that
|
||||
is, replaced with a new key), there must be enough time
|
||||
for the old DNSKEY RRset to have expired from resolver caches
|
||||
before the new key is activated and begins generating
|
||||
signatures. If that condition does not apply, a warning
|
||||
will be generated.
|
||||
is, replaced with a new key), there must be enough time for the
|
||||
old DNSKEY RRset to have expired from resolver caches before
|
||||
the new key is activated and begins generating signatures. If
|
||||
that condition does not apply, a warning will be generated.
|
||||
</p>
|
||||
<p>
|
||||
The length of the TTL can be set in seconds, or in larger units
|
||||
@@ -128,12 +132,18 @@
|
||||
'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
|
||||
</p>
|
||||
<p>
|
||||
This option is mandatory unless the <code class="option">-f</code> has
|
||||
been used to specify a zone file, or a default key TTL was
|
||||
set with the <code class="option">-L</code> to
|
||||
<span class="command"><strong>dnssec-keygen</strong></span>. (If either of those is true,
|
||||
this option may still be used; it will override the value found
|
||||
in the zone or key file.)
|
||||
This option is not necessary if <code class="option">-f</code> has
|
||||
been used to specify a zone file from which the TTL
|
||||
of the DNSKEY RRset can be read, or if a default key TTL was
|
||||
set using ith the <code class="option">-L</code> to
|
||||
<span class="command"><strong>dnssec-keygen</strong></span>. If either of those is true,
|
||||
this option may still be used; it will override the values
|
||||
found in the zone file or the key file.
|
||||
</p>
|
||||
<p>
|
||||
If this option is not used and the key TTL cannot be retrieved
|
||||
from the zone file or the key file, then a warning is generated
|
||||
and a default value of 1 day is used.
|
||||
</p>
|
||||
</dd>
|
||||
<dt><span class="term">-r <em class="replaceable"><code>resign interval</code></em></span></dt>
|
||||
|
||||
310
bin/python/dnssec-keymgr.8
Normal file
310
bin/python/dnssec-keymgr.8
Normal file
@@ -0,0 +1,310 @@
|
||||
.\" Copyright (C) 2016 Internet Systems Consortium, Inc. ("ISC")
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and/or distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
|
||||
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
||||
.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
||||
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
|
||||
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
||||
.\" PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.hy 0
|
||||
.ad l
|
||||
'\" t
|
||||
.\" Title: dnssec-keymgr
|
||||
.\" Author:
|
||||
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
|
||||
.\" Date: 2016-04-03
|
||||
.\" Manual: BIND9
|
||||
.\" Source: ISC
|
||||
.\" Language: English
|
||||
.\"
|
||||
.TH "DNSSEC\-KEYMGR" "8" "2016\-04\-03" "ISC" "BIND9"
|
||||
.\" -----------------------------------------------------------------
|
||||
.\" * Define some portability stuff
|
||||
.\" -----------------------------------------------------------------
|
||||
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.\" http://bugs.debian.org/507673
|
||||
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
||||
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.ie \n(.g .ds Aq \(aq
|
||||
.el .ds Aq '
|
||||
.\" -----------------------------------------------------------------
|
||||
.\" * set default formatting
|
||||
.\" -----------------------------------------------------------------
|
||||
.\" disable hyphenation
|
||||
.nh
|
||||
.\" disable justification (adjust text to left margin only)
|
||||
.ad l
|
||||
.\" -----------------------------------------------------------------
|
||||
.\" * MAIN CONTENT STARTS HERE *
|
||||
.\" -----------------------------------------------------------------
|
||||
.SH "NAME"
|
||||
dnssec-keymgr \- Ensures correct DNSKEY coverage for a zone based on a defined policy
|
||||
.SH "SYNOPSIS"
|
||||
.HP \w'\fBdnssec\-keymgr\fR\ 'u
|
||||
\fBdnssec\-keymgr\fR [\fB\-K\ \fR\fB\fIdirectory\fR\fR] [\fB\-c\ \fR\fB\fIfile\fR\fR] [\fB\-d\ \fR\fB\fItime\fR\fR] [\fB\-k\fR] [\fB\-z\fR] [\fB\-g\ \fR\fB\fIpath\fR\fR] [\fB\-s\ \fR\fB\fIpath\fR\fR] [zone...]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBdnssec\-keymgr\fR
|
||||
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\fR
|
||||
and
|
||||
\fBdnssec\-settime\fR\&.
|
||||
.PP
|
||||
DNSSEC policy can be read from a configuration file (default
|
||||
/etc/dnssec\&.policy), 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\&.
|
||||
.PP
|
||||
When
|
||||
\fBdnssec\-keymgr\fR
|
||||
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\&.
|
||||
.PP
|
||||
A zone policy can specify a duration for which we want to ensure the key correctness (\fBcoverage\fR)\&. It can also specify a rollover period (\fBroll\-period\fR)\&. 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\&.
|
||||
.PP
|
||||
If zones are specified on the command line,
|
||||
\fBdnssec\-keymgr\fR
|
||||
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\&.
|
||||
.PP
|
||||
If zones are
|
||||
\fInot\fR
|
||||
specified on the command line, then
|
||||
\fBdnssec\-keymgr\fR
|
||||
will search the key directory (either the current working directory or the directory set by the
|
||||
\fB\-K\fR
|
||||
option), and check the keys for all the zones represented in the directory\&.
|
||||
.PP
|
||||
It is expected that this tool will be run automatically and unattended (for example, by
|
||||
\fBcron\fR)\&.
|
||||
.SH "OPTIONS"
|
||||
.PP
|
||||
\-c \fIfile\fR
|
||||
.RS 4
|
||||
If
|
||||
\fB\-c\fR
|
||||
is specified, then the DNSSEC policy is read from
|
||||
\fBfile\fR\&. (If not specified, then the policy is read from
|
||||
/etc/policy\&.conf; if that file doesn\*(Aqt exist, a built\-in global default policy is used\&.)
|
||||
.RE
|
||||
.PP
|
||||
\-f
|
||||
.RS 4
|
||||
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\&.
|
||||
.RE
|
||||
.PP
|
||||
\-g \fIkeygen path\fR
|
||||
.RS 4
|
||||
Specifies a path to a
|
||||
\fBdnssec\-keygen\fR
|
||||
binary\&. Used for testing\&. See also the
|
||||
\fB\-s\fR
|
||||
option\&.
|
||||
.RE
|
||||
.PP
|
||||
\-K \fIdirectory\fR
|
||||
.RS 4
|
||||
Sets the directory in which keys can be found\&. Defaults to the current working directory\&.
|
||||
.RE
|
||||
.PP
|
||||
\-k
|
||||
.RS 4
|
||||
Only apply policies to KSK keys\&. See also the
|
||||
\fB\-z\fR
|
||||
option\&.
|
||||
.RE
|
||||
.PP
|
||||
\-q
|
||||
.RS 4
|
||||
Quiet: suppress printing of
|
||||
\fBdnssec\-keygen\fR
|
||||
and
|
||||
\fBdnssec\-settime\fR\&.
|
||||
.RE
|
||||
.PP
|
||||
\-s \fIsettime path\fR
|
||||
.RS 4
|
||||
Specifies a path to a
|
||||
\fBdnssec\-settime\fR
|
||||
binary\&. Used for testing\&. See also the
|
||||
\fB\-g\fR
|
||||
option\&.
|
||||
.RE
|
||||
.PP
|
||||
\-z
|
||||
.RS 4
|
||||
Only apply policies to ZSK keys\&. See also the
|
||||
\fB\-k\fR
|
||||
option\&.
|
||||
.RE
|
||||
.SH "POLICY CONFIGURATION"
|
||||
.PP
|
||||
The
|
||||
policy\&.conf
|
||||
file can specify three kinds of policies:
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
.sp -1
|
||||
.IP \(bu 2.3
|
||||
.\}
|
||||
\fIPolicy classes\fR
|
||||
(\fBpolicy \fR\fB\fIname\fR\fR\fB { \&.\&.\&. };\fR)
|
||||
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\fR might specify
|
||||
1024\-bit key sizes, but a class \fBextra\fR might
|
||||
specify 2048 bits instead; \fBextra\fR would be
|
||||
used for zones that had unusually high security needs\&.
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
.sp -1
|
||||
.IP \(bu 2.3
|
||||
.\}
|
||||
Algorithm policies:
|
||||
(\fBalgorithm\-policy \fR\fB\fIalgorithm\fR\fR\fB { \&.\&.\&. };\fR )
|
||||
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\fR, and the
|
||||
new key sizes would then be used for any key of type RSASHA256\&.
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
.sp -1
|
||||
.IP \(bu 2.3
|
||||
.\}
|
||||
Zone policies:
|
||||
(\fBzone \fR\fB\fIname\fR\fR\fB { \&.\&.\&. };\fR )
|
||||
set policy for a single zone by name\&. A zone policy can inherit
|
||||
a policy class by including a \fBpolicy\fR option\&.
|
||||
.RE
|
||||
.PP
|
||||
Options that can be specified in policies:
|
||||
.PP
|
||||
\fBalgorithm\fR
|
||||
.RS 4
|
||||
The key algorithm\&. If no policy is defined, the default is
|
||||
RSASHA256\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBcoverage\fR
|
||||
.RS 4
|
||||
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\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBdirectory\fR
|
||||
.RS 4
|
||||
Specifies the directory in which keys should be stored\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBkey\-size\fR
|
||||
.RS 4
|
||||
Specifies the number of bits to use in creating keys\&.
|
||||
Takes two arguments: keytype (eihter "zsk" or "ksk") and size\&.
|
||||
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 1024 bits for DSA keys and 2048 for
|
||||
RSA\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBkeyttl\fR
|
||||
.RS 4
|
||||
The key TTL\&. If no policy is defined, the default is one hour\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBpost\-publish\fR
|
||||
.RS 4
|
||||
How long after inactivation a key should be deleted from the zone\&.
|
||||
Note: If \fBroll\-period\fR is not set, this value is
|
||||
ignored\&. Takes two arguments: keytype (eihter "zsk" or "ksk") and a
|
||||
duration\&. A default value for this option can be set in algorithm
|
||||
policies as well as in policy classes or zone policies\&. The default
|
||||
is one month\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBpre\-publish\fR
|
||||
.RS 4
|
||||
How long before activation a key should be published\&. Note: If
|
||||
\fBroll\-period\fR is not set, this value is ignored\&.
|
||||
Takes two arguments: keytype (either "zsk" or "ksk") and a duration\&.
|
||||
A default value for this option can be set in algorithm policies
|
||||
as well as in policy classes or zone policies\&. The default is
|
||||
one month\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBroll\-period\fR
|
||||
.RS 4
|
||||
How frequently keys should be rolled over\&.
|
||||
Takes two arguments: keytype (eihter "zsk" or "ksk") and a duration\&.
|
||||
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 one year for ZSK\*(Aqs\&. KSK\*(Aqs do not
|
||||
roll over by default\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBstandby\fR
|
||||
.RS 4
|
||||
Not yet implemented\&.
|
||||
.RE
|
||||
.SH "REMAINING WORK"
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
.sp -1
|
||||
.IP \(bu 2.3
|
||||
.\}
|
||||
Enable scheduling of KSK rollovers using the \fB\-P sync\fR
|
||||
and \fB\-D sync\fR options to
|
||||
\fBdnssec\-keygen\fR and
|
||||
\fBdnssec\-settime\fR\&. Check the parent zone
|
||||
(as in \fBdnssec\-checkds\fR) to determine when it\*(Aqs
|
||||
safe for the key to roll\&.
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
.sp -1
|
||||
.IP \(bu 2.3
|
||||
.\}
|
||||
Allow configuration of standby keys and use of the REVOKE bit,
|
||||
for keys that use RFC 5011 semantics\&.
|
||||
.RE
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBdnssec-coverage\fR(8),
|
||||
\fBdnssec-keygen\fR(8),
|
||||
\fBdnssec-settime\fR(8),
|
||||
\fBdnssec-checkds\fR(8)
|
||||
.SH "AUTHOR"
|
||||
.PP
|
||||
\fBInternet Systems Consortium, Inc\&.\fR
|
||||
.SH "COPYRIGHT"
|
||||
.br
|
||||
Copyright \(co 2016 Internet Systems Consortium, Inc. ("ISC")
|
||||
.br
|
||||
267
bin/python/dnssec-keymgr.html
Normal file
267
bin/python/dnssec-keymgr.html
Normal file
@@ -0,0 +1,267 @@
|
||||
<!--
|
||||
- Copyright (C) 2016 Internet Systems Consortium, Inc. ("ISC")
|
||||
-
|
||||
- Permission to use, copy, modify, and/or distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
|
||||
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
||||
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
||||
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
|
||||
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
||||
- PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>dnssec-keymgr</title>
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
|
||||
<a name="man.dnssec-keymgr"></a><div class="titlepage"></div>
|
||||
<div class="refnamediv">
|
||||
<h2>Name</h2>
|
||||
<p><span class="application">dnssec-keymgr</span> — Ensures correct DNSKEY coverage for a zone based on a defined policy</p>
|
||||
</div>
|
||||
<div class="refsynopsisdiv">
|
||||
<h2>Synopsis</h2>
|
||||
<div class="cmdsynopsis"><p><code class="command">dnssec-keymgr</code> [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-c <em class="replaceable"><code>file</code></em></code>] [<code class="option">-d <em class="replaceable"><code>time</code></em></code>] [<code class="option">-k</code>] [<code class="option">-z</code>] [<code class="option">-g <em class="replaceable"><code>path</code></em></code>] [<code class="option">-s <em class="replaceable"><code>path</code></em></code>] [zone...]</p></div>
|
||||
</div>
|
||||
<div class="refsection">
|
||||
<a name="id-1.7"></a><h2>DESCRIPTION</h2>
|
||||
<p>
|
||||
<span class="command"><strong>dnssec-keymgr</strong></span>
|
||||
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:
|
||||
<span class="command"><strong>dnssec-keygen</strong></span> and
|
||||
<span class="command"><strong>dnssec-settime</strong></span>.
|
||||
</p>
|
||||
<p>
|
||||
DNSSEC policy can be read from a configuration file (default
|
||||
<code class="filename">/etc/dnssec.policy</code>), 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.
|
||||
</p>
|
||||
<p>
|
||||
When <span class="command"><strong>dnssec-keymgr</strong></span> 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.
|
||||
</p>
|
||||
<p>
|
||||
A zone policy can specify a duration for which we want to
|
||||
ensure the key correctness (<code class="option">coverage</code>). It can
|
||||
also specify a rollover period (<code class="option">roll-period</code>).
|
||||
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.
|
||||
</p>
|
||||
<p>
|
||||
If zones are specified on the command line,
|
||||
<span class="command"><strong>dnssec-keymgr</strong></span> 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.
|
||||
</p>
|
||||
<p>
|
||||
If zones are <span class="emphasis"><em>not</em></span> specified on the command
|
||||
line, then <span class="command"><strong>dnssec-keymgr</strong></span> will search the
|
||||
key directory (either the current working directory or the directory
|
||||
set by the <code class="option">-K</code> option), and check the keys for
|
||||
all the zones represented in the directory.
|
||||
</p>
|
||||
<p>
|
||||
It is expected that this tool will be run automatically and
|
||||
unattended (for example, by <span class="command"><strong>cron</strong></span>).
|
||||
</p>
|
||||
</div>
|
||||
<div class="refsection">
|
||||
<a name="id-1.8"></a><h2>OPTIONS</h2>
|
||||
<div class="variablelist"><dl class="variablelist">
|
||||
<dt><span class="term">-c <em class="replaceable"><code>file</code></em></span></dt>
|
||||
<dd><p>
|
||||
If <code class="option">-c</code> is specified, then the DNSSEC
|
||||
policy is read from <code class="option">file</code>. (If not
|
||||
specified, then the policy is read from
|
||||
<code class="filename">/etc/policy.conf</code>; if that file
|
||||
doesn't exist, a built-in global default policy is used.)
|
||||
</p></dd>
|
||||
<dt><span class="term">-f</span></dt>
|
||||
<dd><p>
|
||||
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.
|
||||
</p></dd>
|
||||
<dt><span class="term">-g <em class="replaceable"><code>keygen path</code></em></span></dt>
|
||||
<dd><p>
|
||||
Specifies a path to a <span class="command"><strong>dnssec-keygen</strong></span> binary.
|
||||
Used for testing.
|
||||
See also the <code class="option">-s</code> option.
|
||||
</p></dd>
|
||||
<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
|
||||
<dd><p>
|
||||
Sets the directory in which keys can be found. Defaults to the
|
||||
current working directory.
|
||||
</p></dd>
|
||||
<dt><span class="term">-k</span></dt>
|
||||
<dd><p>
|
||||
Only apply policies to KSK keys.
|
||||
See also the <code class="option">-z</code> option.
|
||||
</p></dd>
|
||||
<dt><span class="term">-q</span></dt>
|
||||
<dd><p>
|
||||
Quiet: suppress printing of <span class="command"><strong>dnssec-keygen</strong></span>
|
||||
and <span class="command"><strong>dnssec-settime</strong></span>.
|
||||
</p></dd>
|
||||
<dt><span class="term">-s <em class="replaceable"><code>settime path</code></em></span></dt>
|
||||
<dd><p>
|
||||
Specifies a path to a <span class="command"><strong>dnssec-settime</strong></span> binary.
|
||||
Used for testing.
|
||||
See also the <code class="option">-g</code> option.
|
||||
</p></dd>
|
||||
<dt><span class="term">-z</span></dt>
|
||||
<dd><p>
|
||||
Only apply policies to ZSK keys.
|
||||
See also the <code class="option">-k</code> option.
|
||||
</p></dd>
|
||||
</dl></div>
|
||||
</div>
|
||||
<div class="refsection">
|
||||
<a name="id-1.9"></a><h2>POLICY CONFIGURATION</h2>
|
||||
<p>
|
||||
The <code class="filename">policy.conf</code> file can specify three kinds
|
||||
of policies:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||||
<li class="listitem">
|
||||
<span class="emphasis"><em>Policy classes</em></span>
|
||||
(<code class="option">policy <em class="replaceable"><code>name</code></em> { ... };</code>)
|
||||
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 <strong class="userinput"><code>normal</code></strong> might specify
|
||||
1024-bit key sizes, but a class <strong class="userinput"><code>extra</code></strong> might
|
||||
specify 2048 bits instead; <strong class="userinput"><code>extra</code></strong> would be
|
||||
used for zones that had unusually high security needs.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Algorithm policies:
|
||||
(<code class="option">algorithm-policy <em class="replaceable"><code>algorithm</code></em> { ... };</code> )
|
||||
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 <span class="command"><strong>algorithm-policy</strong></span>, and the
|
||||
new key sizes would then be used for any key of type RSASHA256.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Zone policies:
|
||||
(<code class="option">zone <em class="replaceable"><code>name</code></em> { ... };</code> )
|
||||
set policy for a single zone by name. A zone policy can inherit
|
||||
a policy class by including a <code class="option">policy</code> option.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Options that can be specified in policies:
|
||||
</p>
|
||||
<div class="variablelist"><dl class="variablelist">
|
||||
<dt><span class="term"><span class="command"><strong>algorithm</strong></span></span></dt>
|
||||
<dd>
|
||||
The key algorithm. If no policy is defined, the default is
|
||||
RSASHA256.
|
||||
</dd>
|
||||
<dt><span class="term"><span class="command"><strong>coverage</strong></span></span></dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
<dt><span class="term"><span class="command"><strong>directory</strong></span></span></dt>
|
||||
<dd>
|
||||
Specifies the directory in which keys should be stored.
|
||||
</dd>
|
||||
<dt><span class="term"><span class="command"><strong>key-size</strong></span></span></dt>
|
||||
<dd>
|
||||
Specifies the number of bits to use in creating keys.
|
||||
Takes two arguments: keytype (eihter "zsk" or "ksk") and size.
|
||||
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 1024 bits for DSA keys and 2048 for
|
||||
RSA.
|
||||
</dd>
|
||||
<dt><span class="term"><span class="command"><strong>keyttl</strong></span></span></dt>
|
||||
<dd>
|
||||
The key TTL. If no policy is defined, the default is one hour.
|
||||
</dd>
|
||||
<dt><span class="term"><span class="command"><strong>post-publish</strong></span></span></dt>
|
||||
<dd>
|
||||
How long after inactivation a key should be deleted from the zone.
|
||||
Note: If <code class="option">roll-period</code> is not set, this value is
|
||||
ignored. Takes two arguments: keytype (eihter "zsk" or "ksk") and a
|
||||
duration. A default value for this option can be set in algorithm
|
||||
policies as well as in policy classes or zone policies. The default
|
||||
is one month.
|
||||
</dd>
|
||||
<dt><span class="term"><span class="command"><strong>pre-publish</strong></span></span></dt>
|
||||
<dd>
|
||||
How long before activation a key should be published. Note: If
|
||||
<code class="option">roll-period</code> is not set, this value is ignored.
|
||||
Takes two arguments: keytype (either "zsk" or "ksk") and a duration.
|
||||
A default value for this option can be set in algorithm policies
|
||||
as well as in policy classes or zone policies. The default is
|
||||
one month.
|
||||
</dd>
|
||||
<dt><span class="term"><span class="command"><strong>roll-period</strong></span></span></dt>
|
||||
<dd>
|
||||
How frequently keys should be rolled over.
|
||||
Takes two arguments: keytype (eihter "zsk" or "ksk") and a duration.
|
||||
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 one year for ZSK's. KSK's do not
|
||||
roll over by default.
|
||||
</dd>
|
||||
<dt><span class="term"><span class="command"><strong>standby</strong></span></span></dt>
|
||||
<dd>
|
||||
Not yet implemented.
|
||||
</dd>
|
||||
</dl></div>
|
||||
</div>
|
||||
<div class="refsection">
|
||||
<a name="id-1.10"></a><h2>REMAINING WORK</h2>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||||
<li class="listitem">
|
||||
Enable scheduling of KSK rollovers using the <code class="option">-P sync</code>
|
||||
and <code class="option">-D sync</code> options to
|
||||
<span class="command"><strong>dnssec-keygen</strong></span> and
|
||||
<span class="command"><strong>dnssec-settime</strong></span>. Check the parent zone
|
||||
(as in <span class="command"><strong>dnssec-checkds</strong></span>) to determine when it's
|
||||
safe for the key to roll.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Allow configuration of standby keys and use of the REVOKE bit,
|
||||
for keys that use RFC 5011 semantics.
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<div class="refsection">
|
||||
<a name="id-1.11"></a><h2>SEE ALSO</h2>
|
||||
<p>
|
||||
<span class="citerefentry"><span class="refentrytitle">dnssec-coverage</span>(8)</span>,
|
||||
<span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>,
|
||||
<span class="citerefentry"><span class="refentrytitle">dnssec-settime</span>(8)</span>,
|
||||
<span class="citerefentry"><span class="refentrytitle">dnssec-checkds</span>(8)</span>
|
||||
</p>
|
||||
</div>
|
||||
</div></body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user