-.\" 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
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
.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
.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
\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
<!--
- - 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
</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>
'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>
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
'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>
--- /dev/null
+.\" 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
--- /dev/null
+<!--
+ - 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>
projects / thirdparty / bind9.git / commitdiff
