Adding upstream version 1:9.16.44.upstream/1%9.16.44upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 223 insertions, 0 deletions

diff --git a/bin/python/dnssec-keymgr.rst b/bin/python/dnssec-keymgr.rst
new file mode 100644
index 0000000..4320541
--- /dev/null
+++ b/bin/python/dnssec-keymgr.rst
@@ -0,0 +1,223 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0.  If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. highlight: console
+
+.. _man_dnssec-keymgr:
+
+dnssec-keymgr - Ensures correct DNSKEY coverage based on a defined policy
+-------------------------------------------------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`dnssec-keymgr` [**-K**\ *directory*] [**-c**\ *file*] [**-f**] [**-k**] [**-q**] [**-v**] [**-z**] [**-g**\ *path*] [**-s**\ *path*] [zone...]
+
+Description
+~~~~~~~~~~~
+
+``dnssec-keymgr`` 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: ``dnssec-keygen`` and
+``dnssec-settime``.
+
+DNSSEC policy can be read from a configuration file (default
+/etc/dnssec-policy.conf), 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.
+
+When ``dnssec-keymgr`` 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.
+
+A zone policy can specify a duration for which we want to ensure the key
+correctness (``coverage``). It can also specify a rollover period
+(``roll-period``). 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.
+
+If zones are specified on the command line, ``dnssec-keymgr`` 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.
+
+If zones are *not* specified on the command line, then ``dnssec-keymgr``
+will search the key directory (either the current working directory or
+the directory set by the ``-K`` option), and check the keys for all the
+zones represented in the directory.
+
+Key times that are in the past will not be updated unless the ``-f`` is
+used (see below). Key inactivation and deletion times that are less than
+five minutes in the future will be delayed by five minutes.
+
+It is expected that this tool will be run automatically and unattended
+(for example, by ``cron``).
+
+Options
+~~~~~~~
+
+**-c** *file*
+
+   If ``-c`` is specified, then the DNSSEC policy is read from ``file``.
+   (If not specified, then the policy is read from
+   /etc/dnssec-policy.conf; if that file doesnt exist, a built-in global
+   default policy is used.)
+
+**-f**
+
+   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.
+
+**-g** *keygen-path*
+
+   Specifies a path to a ``dnssec-keygen`` binary. Used for testing. See
+   also the ``-s`` option.
+
+**-h**
+
+   Print the ``dnssec-keymgr`` help summary and exit.
+
+**-K** *directory*
+
+   Sets the directory in which keys can be found. Defaults to the
+   current working directory.
+
+**-k**
+
+   Only apply policies to KSK keys. See also the ``-z`` option.
+
+**-q**
+
+   Quiet: suppress printing of ``dnssec-keygen`` and ``dnssec-settime``.
+
+**-s** *settime-path*
+
+   Specifies a path to a ``dnssec-settime`` binary. Used for testing.
+   See also the ``-g`` option.
+
+**-v**
+
+   Print the ``dnssec-keymgr`` version and exit.
+
+**-z**
+
+   Only apply policies to ZSK keys. See also the ``-k`` option.
+
+Policy Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+The dnssec-policy.conf file can specify three kinds of policies:
+
+   · *Policy classes* (``policy``\ *name*\ ``{ ... };``) 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 ``normal`` might specify 1024-bit key sizes, but a class
+   ``extra`` might specify 2048 bits instead; ``extra`` would be used
+   for zones that had unusually high security needs.
+
+..
+
+   · *Algorithm policies:* (``algorithm-policy``\ *algorithm*\ ``{ ...
+   };`` ) 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 ``algorithm-policy``, and the new key
+   sizes would then be used for any key of type RSASHA256.
+
+   · *Zone policies:* (``zone``\ *name*\ ``{ ... };`` ) set policy for a
+   single zone by name. A zone policy can inherit a policy class by
+   including a ``policy`` option. Zone names beginning with digits
+   (i.e., 0-9) must be quoted. If a zone does not have its own policy
+   then the "default" policy applies.
+
+Options that can be specified in policies:
+
+``algorithm`` *name*;
+
+   The key algorithm. If no policy is defined, the default is RSASHA256.
+
+``coverage`` *duration*;
+
+   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.
+
+``directory`` *path*;
+
+   Specifies the directory in which keys should be stored.
+
+``key-size`` *keytype* *size*;
+
+   Specifies the number of bits to use in creating keys. The keytype is
+   either "zsk" or "ksk". 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 2048 bits for RSA keys.
+
+``keyttl`` *duration*;
+
+   The key TTL. If no policy is defined, the default is one hour.
+
+``post-publish`` *keytype* *duration*;
+
+   How long after inactivation a key should be deleted from the zone.
+   Note: If ``roll-period`` is not set, this value is ignored. The
+   keytype is either "zsk" or "ksk". A default duration for this option
+   can be set in algorithm policies as well as in policy classes or zone
+   policies. The default is one month.
+
+``pre-publish`` *keytype* *duration*;
+
+   How long before activation a key should be published. Note: If
+   ``roll-period`` is not set, this value is ignored. The keytype is
+   either "zsk" or "ksk". A default duration for this option can be set
+   in algorithm policies as well as in policy classes or zone policies.
+   The default is one month.
+
+``roll-period`` *keytype* *duration*;
+
+   How frequently keys should be rolled over. The keytype is either
+   "zsk" or "ksk". A default duration 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 ZSKs. KSKs do
+   not roll over by default.
+
+``standby`` *keytype* *number*;
+
+   Not yet implemented.
+
+Remaining Work
+~~~~~~~~~~~~~~
+
+   · Enable scheduling of KSK rollovers using the ``-P sync`` and ``-D
+   sync`` options to ``dnssec-keygen`` and ``dnssec-settime``. Check the
+   parent zone (as in ``dnssec-checkds``) to determine when its safe for
+   the key to roll.
+
+..
+
+   · Allow configuration of standby keys and use of the REVOKE bit, for
+   keys that use RFC 5011 semantics.
+
+See Also
+~~~~~~~~
+
+``dnssec-coverage``\ (8), ``dnssec-keygen``\ (8),
+``dnssec-settime``\ (8), ``dnssec-checkds``\ (8)