dnssec-keymgr.docbook revision f6096b958c8b58c4709860d7c4dcdde5deeacb7a
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater - Copyright (C) 2015 Internet Systems Consortium, Inc. ("ISC")
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Permission to use, copy, modify, and/or distribute this software for any
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - purpose with or without fee is hereby granted, provided that the above
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - copyright notice and this permission notice appear in all copies.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - PERFORMANCE OF THIS SOFTWARE.
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater<!-- Converted by db4-upgrade version 1.0 -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="man.dnssec-keymgr">
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews <refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentrytitle><application>dnssec-keymgr</application></refentrytitle>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refnamediv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refname><application>dnssec-keymgr</application></refname>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refpurpose>Ensures correct DNSKEY coverage for a zone based on a defined policy</refpurpose>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refnamediv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </copyright>
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews <refsynopsisdiv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">file</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-d <replaceable class="parameter">time</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-k</option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-z</option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-g <replaceable class="parameter">path</replaceable></option></arg>
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater <arg choice="opt" rep="norepeat"><option>-s <replaceable class="parameter">path</replaceable></option></arg>
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater </cmdsynopsis>
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater </refsynopsisdiv>
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater <refsection><info><title>DESCRIPTION</title></info>
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater is a high level Python wrapper to facilitate the key rollover
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater process for zones handled by BIND. It uses the BIND commands
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater for manipulating DNSSEC key metadata:
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater DNSSEC policy can be read from a configuration file (default
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater <filename>/etc/dnssec.policy</filename>), from which the key
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater parameters, publication and rollover schedule, and desired
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater coverage duration for any given zone can be determined. This
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater file may be used to define individual DNSSEC policies on a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein per-zone basis, or to set a default policy used for all zones.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein When <command>dnssec-keymgr</command> runs, it examines the DNSSEC
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein keys for one or more zones, comparing their timing metadata against
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater the policies for those zones. If key settings do not conform to the
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater DNSSEC policy (for example, because the policy has been changed),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein they are automatically corrected.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein A zone policy can specify a duration for which we want to
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater ensure the key correctness (<option>coverage</option>). It can
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater also specify a rollover period (<option>roll-period</option>).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If policy indicates that a key should roll over before the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein coverage period ends, then a successor key will automatically be
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein created and added to the end of the key series.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If zones are specified on the command line,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <command>dnssec-keymgr</command> will examine only those zones.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If a specified zone does not already have keys in place, then
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater keys will be generated for it according to policy.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If zones are <emphasis>not</emphasis> specified on the command
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater line, then <command>dnssec-keymgr</command> will search the
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater key directory (either the current working directory or the directory
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater set by the <option>-K</option> option), and check the keys for
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater all the zones represented in the directory.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein It is expected that this tool will be run automatically and
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater unattended (for example, by <command>cron</command>).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refsection>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater <refsection><info><title>OPTIONS</title></info>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater <variablelist>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-K <replaceable class="parameter">directory</replaceable></term>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater Sets the directory in which keys can be found. Defaults to the
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater current working directory.
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews </varlistentry>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-c <replaceable class="parameter">file</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If <option>-c</option> is specified, then the DNSSEC
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein policy is read from <option>file</option>. (If not
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein specified, then the policy is read from
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <filename>/etc/policy.conf</filename>; if that file
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater doesn't exist, a built-in global default policy is used.)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Force: allow updating of key events even if they are
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater already in the past. This is not recommended for use with
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater zones in which keys have already been published. However,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein if a set of keys has been generated all of which have
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater publication and activation dates in the past, but the
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater keys have not been published in a zone as yet, then this
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater option can be used to clean them up and turn them into a
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater proper series of keys with appropriate rollover intervals.
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater </varlistentry>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Quiet: suppress printing of <command>dnssec-keygen</command>
a1ad6695ed6f988406cf155aa26376f84f73bcb9Automatic Updater </varlistentry>
a1ad6695ed6f988406cf155aa26376f84f73bcb9Automatic Updater <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Only apply policies to KSK keys.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater Only apply policies to ZSK keys.
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater </varlistentry>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-g <replaceable class="parameter">keygen path</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies a path to a <command>dnssec-keygen</command> binary.
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews Used for testing.
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater </varlistentry>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater <varlistentry>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater <term>-s <replaceable class="parameter">settime path</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies a path to a <command>dnssec-settime</command> binary.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Used for testing.
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater </varlistentry>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater </variablelist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refsection><info><title>POLICY CONFIGURATION</title></info>
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater The <filename>policy.conf</filename> file can specify three kinds
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews of policies:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <itemizedlist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein (<option>policy <replaceable>name</replaceable> { ... };</option>)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein can be inherited by zone policies or other policy classes; these
58d9e9169e7ab4355a0b0bfc13bc616bc5247dfeAutomatic Updater can be used to create sets of different security profiles. For
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein example, a policy class <userinput>normal</userinput> might specify
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 1024-bit key sizes, but a class <userinput>extra</userinput> might
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews specify 2048 bits instead; <userinput>extra</userinput> would be
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews used for zones that had unusually high security needs.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews Algorithm policies:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews (<option>algorithm-policy <replaceable>algorithm</replaceable> { ... };</option> )
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews override default per-algorithm settings. For example, by default,
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews RSASHA256 keys use 2048-bit key sizes for both KSK and ZSK. This
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews can be modified using <command>algorithm-policy</command>, and the
922312472e2e05ebc64993d465999c5351b83036Automatic Updater new key sizes would then be used for any key of type RSASHA256.
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater Zone policies:
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater (<option>zone <replaceable>name</replaceable> { ... };</option> )
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater set policy for a single zone by name. A zone policy can inherit
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews a policy class by including a <option>policy</option> option.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews </itemizedlist>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews Options that can be specified in policies:
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews <variablelist>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <varlistentry>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews Specifies the directory in which keys should be stored.
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews </varlistentry>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <varlistentry>
0c6ada0a814f3c5417daa1654129bc2af56ed504Automatic Updater The key algorithm. If no policy is defined, the default is
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews </varlistentry>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <varlistentry>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews The key TTL. If no policy is defined, the default is one hour.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews </varlistentry>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The length of time to ensure that keys will be correct; no action
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein will be taken to create new keys to be activated after this time.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This can be represented as a number of seconds, or as a duration using
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein human-readable units (examples: "1y" or "6 months").
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein A default value for this option can be set in algorithm policies
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein as well as in policy classes or zone policies.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If no policy is configured, the default is six months.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies the number of bits to use in creating keys.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Takes two arguments: keytype (eihter "zsk" or "ksk") and size.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein A default value for this option can be set in algorithm policies
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein as well as in policy classes or zone policies. If no policy is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein configured, the default is 1024 bits for DSA keys and 2048 for