dnssec-keymgr.html revision 7e71f05d8643aca84914437c900cb716444507e4
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User - Copyright (C) 2016 Internet Systems Consortium, Inc. ("ISC")
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - This Source Code Form is subject to the terms of the Mozilla Public
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - License, v. 2.0. If a copy of the MPL was not distributed with this
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - file, You can obtain one at http://mozilla.org/MPL/2.0/.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<a name="man.dnssec-keymgr"></a><div class="titlepage"></div>
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<p><span class="application">dnssec-keymgr</span> — Ensures correct DNSKEY coverage for a zone based on a defined policy</p>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User<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">-f</code>] [<code class="option">-k</code>] [<code class="option">-q</code>] [<code class="option">-v</code>] [<code class="option">-z</code>] [<code class="option">-g <em class="replaceable"><code>path</code></em></code>] [<code class="option">-r <em class="replaceable"><code>path</code></em></code>] [<code class="option">-s <em class="replaceable"><code>path</code></em></code>] [zone...]</p></div>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User <span class="command"><strong>dnssec-keymgr</strong></span> is a high level Python wrapper
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User to facilitate the key rollover process for zones handled by
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User BIND. It uses the BIND commands for manipulating DNSSEC key
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User metadata: <span class="command"><strong>dnssec-keygen</strong></span> and
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User <span class="command"><strong>dnssec-settime</strong></span>.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User DNSSEC policy can be read from a configuration file (default
7e71f05d8643aca84914437c900cb716444507e4Tinderbox User <code class="filename">/etc/dnssec-policy.conf</code>), from which the key
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User parameters, publication and rollover schedule, and desired
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User coverage duration for any given zone can be determined. This
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User file may be used to define individual DNSSEC policies on a
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User per-zone basis, or to set a default policy used for all zones.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User When <span class="command"><strong>dnssec-keymgr</strong></span> runs, it examines the DNSSEC
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User keys for one or more zones, comparing their timing metadata against
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User the policies for those zones. If key settings do not conform to the
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User DNSSEC policy (for example, because the policy has been changed),
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User they are automatically corrected.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User A zone policy can specify a duration for which we want to
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User ensure the key correctness (<code class="option">coverage</code>). It can
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User also specify a rollover period (<code class="option">roll-period</code>).
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User If policy indicates that a key should roll over before the
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User coverage period ends, then a successor key will automatically be
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User created and added to the end of the key series.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User If zones are specified on the command line,
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User <span class="command"><strong>dnssec-keymgr</strong></span> will examine only those zones.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User If a specified zone does not already have keys in place, then
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User keys will be generated for it according to policy.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User If zones are <span class="emphasis"><em>not</em></span> specified on the command
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User line, then <span class="command"><strong>dnssec-keymgr</strong></span> will search the
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User key directory (either the current working directory or the directory
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User set by the <code class="option">-K</code> option), and check the keys for
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User all the zones represented in the directory.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User It is expected that this tool will be run automatically and
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User unattended (for example, by <span class="command"><strong>cron</strong></span>).
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<div class="variablelist"><dl class="variablelist">
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term">-c <em class="replaceable"><code>file</code></em></span></dt>
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User If <code class="option">-c</code> is specified, then the DNSSEC
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User policy is read from <code class="option">file</code>. (If not
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User specified, then the policy is read from
7e71f05d8643aca84914437c900cb716444507e4Tinderbox User <code class="filename">/etc/dnssec-policy.conf</code>; if that file
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User doesn't exist, a built-in global default policy is used.)
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Force: allow updating of key events even if they are
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User already in the past. This is not recommended for use with
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User zones in which keys have already been published. However,
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User if a set of keys has been generated all of which have
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User publication and activation dates in the past, but the
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User keys have not been published in a zone as yet, then this
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User option can be used to clean them up and turn them into a
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User proper series of keys with appropriate rollover intervals.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User<dt><span class="term">-g <em class="replaceable"><code>keygen-path</code></em></span></dt>
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Specifies a path to a <span class="command"><strong>dnssec-keygen</strong></span> binary.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Used for testing.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User See also the <code class="option">-s</code> option.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Print the <span class="command"><strong>dnssec-keymgr</strong></span> help summary
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Sets the directory in which keys can be found. Defaults to the
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User current working directory.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Only apply policies to KSK keys.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User See also the <code class="option">-z</code> option.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Quiet: suppress printing of <span class="command"><strong>dnssec-keygen</strong></span>
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User and <span class="command"><strong>dnssec-settime</strong></span>.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User<dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Specifies a path to a file containing random data.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User This is passed to the <span class="command"><strong>dnssec-keygen</strong></span> binary
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User using its <code class="option">-r</code> option.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User<dt><span class="term">-s <em class="replaceable"><code>settime-path</code></em></span></dt>
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Specifies a path to a <span class="command"><strong>dnssec-settime</strong></span> binary.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Used for testing.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User See also the <code class="option">-g</code> option.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Print the <span class="command"><strong>dnssec-keymgr</strong></span> version and exit.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Only apply policies to ZSK keys.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User See also the <code class="option">-k</code> option.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<a name="id-1.9"></a><h2>POLICY CONFIGURATION</h2>
7e71f05d8643aca84914437c900cb716444507e4Tinderbox User The <code class="filename">dnssec-policy.conf</code> file can specify three kinds
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User <span class="emphasis"><em>Policy classes</em></span>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User (<code class="option">policy <em class="replaceable"><code>name</code></em> { ... };</code>)
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User can be inherited by zone policies or other policy classes; these
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User can be used to create sets of different security profiles. For
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User example, a policy class <strong class="userinput"><code>normal</code></strong> might specify
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User 1024-bit key sizes, but a class <strong class="userinput"><code>extra</code></strong> might
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User specify 2048 bits instead; <strong class="userinput"><code>extra</code></strong> would be
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User used for zones that had unusually high security needs.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Algorithm policies:
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User (<code class="option">algorithm-policy <em class="replaceable"><code>algorithm</code></em> { ... };</code> )
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User override default per-algorithm settings. For example, by default,
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User RSASHA256 keys use 2048-bit key sizes for both KSK and ZSK. This
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User can be modified using <span class="command"><strong>algorithm-policy</strong></span>, and the
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User new key sizes would then be used for any key of type RSASHA256.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Zone policies:
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User (<code class="option">zone <em class="replaceable"><code>name</code></em> { ... };</code> )
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User set policy for a single zone by name. A zone policy can inherit
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User a policy class by including a <code class="option">policy</code> option.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Options that can be specified in policies:
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<div class="variablelist"><dl class="variablelist">
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>algorithm</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User The key algorithm. If no policy is defined, the default is
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>coverage</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User The length of time to ensure that keys will be correct; no action
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User will be taken to create new keys to be activated after this time.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User This can be represented as a number of seconds, or as a duration using
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User human-readable units (examples: "1y" or "6 months").
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User A default value for this option can be set in algorithm policies
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User as well as in policy classes or zone policies.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User If no policy is configured, the default is six months.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>directory</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Specifies the directory in which keys should be stored.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>key-size</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Specifies the number of bits to use in creating keys.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Takes two arguments: keytype (eihter "zsk" or "ksk") and size.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User A default value for this option can be set in algorithm policies
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User as well as in policy classes or zone policies. If no policy is
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User configured, the default is 1024 bits for DSA keys and 2048 for
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>keyttl</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User The key TTL. If no policy is defined, the default is one hour.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>post-publish</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User How long after inactivation a key should be deleted from the zone.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Note: If <code class="option">roll-period</code> is not set, this value is
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User ignored. Takes two arguments: keytype (eihter "zsk" or "ksk") and a
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User duration. A default value for this option can be set in algorithm
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User policies as well as in policy classes or zone policies. The default
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User is one month.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>pre-publish</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User How long before activation a key should be published. Note: If
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User <code class="option">roll-period</code> is not set, this value is ignored.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Takes two arguments: keytype (either "zsk" or "ksk") and a duration.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User A default value for this option can be set in algorithm policies
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User as well as in policy classes or zone policies. The default is
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>roll-period</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User How frequently keys should be rolled over.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Takes two arguments: keytype (eihter "zsk" or "ksk") and a duration.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User A default value for this option can be set in algorithm policies
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User as well as in policy classes or zone policies. If no policy is
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User configured, the default is one year for ZSK's. KSK's do not
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User roll over by default.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term"><span class="command"><strong>standby</strong></span></span></dt>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Not yet implemented.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Enable scheduling of KSK rollovers using the <code class="option">-P sync</code>
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User and <code class="option">-D sync</code> options to
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User <span class="command"><strong>dnssec-keygen</strong></span> and
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User <span class="command"><strong>dnssec-settime</strong></span>. Check the parent zone
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User (as in <span class="command"><strong>dnssec-checkds</strong></span>) to determine when it's
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User safe for the key to roll.
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User Allow configuration of standby keys and use of the REVOKE bit,
05da080bbd0c35705081c034cbb1985c274c2656Tinderbox User for keys that use RFC 5011 semantics.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User <span class="citerefentry"><span class="refentrytitle">dnssec-coverage</span>(8)</span>,
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>,
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User <span class="citerefentry"><span class="refentrytitle">dnssec-settime</span>(8)</span>,
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User <span class="citerefentry"><span class="refentrytitle">dnssec-checkds</span>(8)</span>