d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
46bb3884a0738664862e3a36b7848aa374aebd45Tinderbox User - Copyright (C) 2016, 2017 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>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="application">dnssec-keymgr</span>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User — Ensures correct DNSKEY coverage for a zone based on a defined policy
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>]
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User [<code class="option">-c <em class="replaceable"><code>file</code></em></code>]
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User [<code class="option">-g <em class="replaceable"><code>path</code></em></code>]
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User [<code class="option">-r <em class="replaceable"><code>path</code></em></code>]
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User [<code class="option">-s <em class="replaceable"><code>path</code></em></code>]
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>).
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <div class="variablelist"><dl class="variablelist">
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User<dt><span class="term">-c <em class="replaceable"><code>file</code></em></span></dt>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User If <code class="option">-c</code> is specified, then the DNSSEC
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User policy is read from <code class="option">file</code>. (If not
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User specified, then the policy is read from
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User <code class="filename">/etc/dnssec-policy.conf</code>; if that file
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User doesn't exist, a built-in global default policy is used.)
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Force: allow updating of key events even if they are
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User already in the past. This is not recommended for use with
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User zones in which keys have already been published. However,
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User if a set of keys has been generated all of which have
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User publication and activation dates in the past, but the
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User keys have not been published in a zone as yet, then this
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User option can be used to clean them up and turn them into a
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Specifies a path to a <span class="command"><strong>dnssec-keygen</strong></span> binary.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Used for testing.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User See also the <code class="option">-s</code> option.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Sets the directory in which keys can be found. Defaults to the
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User current working directory.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Only apply policies to KSK keys.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User See also the <code class="option">-z</code> option.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Quiet: suppress printing of <span class="command"><strong>dnssec-keygen</strong></span>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Specifies a path to a file containing random data.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User This is passed to the <span class="command"><strong>dnssec-keygen</strong></span> binary
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Specifies a path to a <span class="command"><strong>dnssec-settime</strong></span> binary.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Used for testing.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Only apply policies to ZSK keys.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox 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.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Zone names beginning with digits (i.e., 0-9) must be quoted.
17e9d6023e9fec06511e93303836ec0f106379d2Tinderbox User Options that can be specified in policies:
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox 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
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User will be taken to create new keys to be activated after this time.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User configured, the default is one year for ZSK's. KSK's do not
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox 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.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Enable scheduling of KSK rollovers using the <code class="option">-P sync</code>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User and <code class="option">-D sync</code> options to
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User <span class="command"><strong>dnssec-keygen</strong></span> and
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User <span class="command"><strong>dnssec-settime</strong></span>. Check the parent zone
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User (as in <span class="command"><strong>dnssec-checkds</strong></span>) to determine when it's
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User safe for the key to roll.
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User Allow configuration of standby keys and use of the REVOKE bit,
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User for keys that use RFC 5011 semantics.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">dnssec-coverage</span>(8)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">dnssec-keygen</span>(8)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">dnssec-settime</span>(8)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">dnssec-checkds</span>(8)