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

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

1 files changed, 297 insertions, 0 deletions

diff --git a/doc/man/dnssec-keymgr.8in b/doc/man/dnssec-keymgr.8in
new file mode 100644
index 0000000..ae163db
--- /dev/null
+++ b/doc/man/dnssec-keymgr.8in
@@ -0,0 +1,297 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "DNSSEC-KEYMGR" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9"
+.SH NAME
+dnssec-keymgr \- ensure correct DNSKEY coverage based on a defined policy
+.SH SYNOPSIS
+.sp
+\fBdnssec\-keymgr\fP [\fB\-K\fP\fIdirectory\fP] [\fB\-c\fP\fIfile\fP] [\fB\-f\fP] [\fB\-k\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-z\fP] [\fB\-g\fP\fIpath\fP] [\fB\-s\fP\fIpath\fP] [zone...]
+.SH DESCRIPTION
+.sp
+\fBdnssec\-keymgr\fP 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: \fBdnssec\-keygen\fP and
+\fBdnssec\-settime\fP\&.
+.sp
+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 \(dqdefault\(dq policy used for all
+zones.
+.sp
+When \fBdnssec\-keymgr\fP 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.
+.sp
+A zone policy can specify a duration for which we want to ensure the key
+correctness (\fBcoverage\fP). It can also specify a rollover period
+(\fBroll\-period\fP). 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.
+.sp
+If zones are specified on the command line, \fBdnssec\-keymgr\fP 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.
+.sp
+If zones are \fInot\fP specified on the command line, then \fBdnssec\-keymgr\fP
+will search the key directory (either the current working directory or
+the directory set by the \fB\-K\fP option), and check the keys for all the
+zones represented in the directory.
+.sp
+Key times that are in the past will not be updated unless the \fB\-f\fP is
+used (see below). Key inactivation and deletion times that are less than
+five minutes in the future will be delayed by five minutes.
+.sp
+It is expected that this tool will be run automatically and unattended
+(for example, by \fBcron\fP).
+.SH OPTIONS
+.sp
+\fB\-c\fP \fIfile\fP
+.INDENT 0.0
+.INDENT 3.5
+If \fB\-c\fP is specified, then the DNSSEC policy is read from \fBfile\fP\&.
+(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.)
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-f\fP
+.INDENT 0.0
+.INDENT 3.5
+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.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-g\fP \fIkeygen\-path\fP
+.INDENT 0.0
+.INDENT 3.5
+Specifies a path to a \fBdnssec\-keygen\fP binary. Used for testing. See
+also the \fB\-s\fP option.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-h\fP
+.INDENT 0.0
+.INDENT 3.5
+Print the \fBdnssec\-keymgr\fP help summary and exit.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-K\fP \fIdirectory\fP
+.INDENT 0.0
+.INDENT 3.5
+Sets the directory in which keys can be found. Defaults to the
+current working directory.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-k\fP
+.INDENT 0.0
+.INDENT 3.5
+Only apply policies to KSK keys. See also the \fB\-z\fP option.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-q\fP
+.INDENT 0.0
+.INDENT 3.5
+Quiet: suppress printing of \fBdnssec\-keygen\fP and \fBdnssec\-settime\fP\&.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-s\fP \fIsettime\-path\fP
+.INDENT 0.0
+.INDENT 3.5
+Specifies a path to a \fBdnssec\-settime\fP binary. Used for testing.
+See also the \fB\-g\fP option.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-v\fP
+.INDENT 0.0
+.INDENT 3.5
+Print the \fBdnssec\-keymgr\fP version and exit.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\-z\fP
+.INDENT 0.0
+.INDENT 3.5
+Only apply policies to ZSK keys. See also the \fB\-k\fP option.
+.UNINDENT
+.UNINDENT
+.SH POLICY CONFIGURATION
+.sp
+The dnssec\-policy.conf file can specify three kinds of policies:
+.INDENT 0.0
+.INDENT 3.5
+· \fIPolicy classes\fP (\fBpolicy\fP\fIname\fP\fB{ ... };\fP) 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 \fBnormal\fP might specify 1024\-bit key sizes, but a class
+\fBextra\fP might specify 2048 bits instead; \fBextra\fP would be used
+for zones that had unusually high security needs.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+· \fIAlgorithm policies:\fP (\fBalgorithm\-policy\fP\fIalgorithm\fP\fB{ ...
+};\fP ) 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 \fBalgorithm\-policy\fP, and the new key
+sizes would then be used for any key of type RSASHA256.
+.sp
+· \fIZone policies:\fP (\fBzone\fP\fIname\fP\fB{ ... };\fP ) set policy for a
+single zone by name. A zone policy can inherit a policy class by
+including a \fBpolicy\fP option. Zone names beginning with digits
+(i.e., 0\-9) must be quoted. If a zone does not have its own policy
+then the \(dqdefault\(dq policy applies.
+.UNINDENT
+.UNINDENT
+.sp
+Options that can be specified in policies:
+.sp
+\fBalgorithm\fP \fIname\fP;
+.INDENT 0.0
+.INDENT 3.5
+The key algorithm. If no policy is defined, the default is RSASHA256.
+.UNINDENT
+.UNINDENT
+.sp
+\fBcoverage\fP \fIduration\fP;
+.INDENT 0.0
+.INDENT 3.5
+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: \(dq1y\(dq or \(dq6 months\(dq). 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.
+.UNINDENT
+.UNINDENT
+.sp
+\fBdirectory\fP \fIpath\fP;
+.INDENT 0.0
+.INDENT 3.5
+Specifies the directory in which keys should be stored.
+.UNINDENT
+.UNINDENT
+.sp
+\fBkey\-size\fP \fIkeytype\fP \fIsize\fP;
+.INDENT 0.0
+.INDENT 3.5
+Specifies the number of bits to use in creating keys. The keytype is
+either \(dqzsk\(dq or \(dqksk\(dq. 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.
+.UNINDENT
+.UNINDENT
+.sp
+\fBkeyttl\fP \fIduration\fP;
+.INDENT 0.0
+.INDENT 3.5
+The key TTL. If no policy is defined, the default is one hour.
+.UNINDENT
+.UNINDENT
+.sp
+\fBpost\-publish\fP \fIkeytype\fP \fIduration\fP;
+.INDENT 0.0
+.INDENT 3.5
+How long after inactivation a key should be deleted from the zone.
+Note: If \fBroll\-period\fP is not set, this value is ignored. The
+keytype is either \(dqzsk\(dq or \(dqksk\(dq. 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.
+.UNINDENT
+.UNINDENT
+.sp
+\fBpre\-publish\fP \fIkeytype\fP \fIduration\fP;
+.INDENT 0.0
+.INDENT 3.5
+How long before activation a key should be published. Note: If
+\fBroll\-period\fP is not set, this value is ignored. The keytype is
+either \(dqzsk\(dq or \(dqksk\(dq. 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.
+.UNINDENT
+.UNINDENT
+.sp
+\fBroll\-period\fP \fIkeytype\fP \fIduration\fP;
+.INDENT 0.0
+.INDENT 3.5
+How frequently keys should be rolled over. The keytype is either
+\(dqzsk\(dq or \(dqksk\(dq. 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.
+.UNINDENT
+.UNINDENT
+.sp
+\fBstandby\fP \fIkeytype\fP \fInumber\fP;
+.INDENT 0.0
+.INDENT 3.5
+Not yet implemented.
+.UNINDENT
+.UNINDENT
+.SH REMAINING WORK
+.INDENT 0.0
+.INDENT 3.5
+· Enable scheduling of KSK rollovers using the \fB\-P sync\fP and \fB\-D
+sync\fP options to \fBdnssec\-keygen\fP and \fBdnssec\-settime\fP\&. Check the
+parent zone (as in \fBdnssec\-checkds\fP) to determine when its safe for
+the key to roll.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+· Allow configuration of standby keys and use of the REVOKE bit, for
+keys that use RFC 5011 semantics.
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fBdnssec\-coverage\fP(8), \fBdnssec\-keygen\fP(8),
+\fBdnssec\-settime\fP(8), \fBdnssec\-checkds\fP(8)
+.SH AUTHOR
+Internet Systems Consortium
+.SH COPYRIGHT
+2023, Internet Systems Consortium
+.\" Generated by docutils manpage writer.
+.