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