Add .8 and .html files for dnssec-keymgr
This commit is contained in:
Tinderbox User
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