diff options
Diffstat (limited to '')
| -rw-r--r-- | bin/python/dnssec-keymgr.8 | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/bin/python/dnssec-keymgr.8 b/bin/python/dnssec-keymgr.8 new file mode 100644 index 0000000..a538fda --- /dev/null +++ b/bin/python/dnssec-keymgr.8 @@ -0,0 +1,301 @@ +.\" Copyright (C) 2016-2019 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" 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 http://mozilla.org/MPL/2.0/. +.\" +.hy 0 +.ad l +'\" t +.\" Title: dnssec-keymgr +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 2016-06-03 +.\" Manual: BIND9 +.\" Source: ISC +.\" Language: English +.\" +.TH "DNSSEC\-KEYMGR" "8" "2016\-06\-03" "ISC" "BIND9" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +dnssec-keymgr \- Ensures correct DNSKEY coverage for a zone based on a defined policy +.SH "SYNOPSIS" +.HP \w'\fBdnssec\-keymgr\fR\ 'u +\fBdnssec\-keymgr\fR [\fB\-K\ \fR\fB\fIdirectory\fR\fR] [\fB\-c\ \fR\fB\fIfile\fR\fR] [\fB\-f\fR] [\fB\-k\fR] [\fB\-q\fR] [\fB\-v\fR] [\fB\-z\fR] [\fB\-g\ \fR\fB\fIpath\fR\fR] [\fB\-r\ \fR\fB\fIpath\fR\fR] [\fB\-s\ \fR\fB\fIpath\fR\fR] [zone...] +.SH "DESCRIPTION" +.PP +\fBdnssec\-keymgr\fR +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\fR +and +\fBdnssec\-settime\fR\&. +.PP +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\&. +.PP +When +\fBdnssec\-keymgr\fR +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\&. +.PP +A zone policy can specify a duration for which we want to ensure the key correctness (\fBcoverage\fR)\&. It can also specify a rollover period (\fBroll\-period\fR)\&. 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\&. +.PP +If zones are specified on the command line, +\fBdnssec\-keymgr\fR +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\&. +.PP +If zones are +\fInot\fR +specified on the command line, then +\fBdnssec\-keymgr\fR +will search the key directory (either the current working directory or the directory set by the +\fB\-K\fR +option), and check the keys for all the zones represented in the directory\&. +.PP +It is expected that this tool will be run automatically and unattended (for example, by +\fBcron\fR)\&. +.SH "OPTIONS" +.PP +\-c \fIfile\fR +.RS 4 +If +\fB\-c\fR +is specified, then the DNSSEC policy is read from +\fBfile\fR\&. (If not specified, then the policy is read from +/etc/dnssec\-policy\&.conf; if that file doesn\*(Aqt exist, a built\-in global default policy is used\&.) +.RE +.PP +\-f +.RS 4 +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\&. +.RE +.PP +\-g \fIkeygen\-path\fR +.RS 4 +Specifies a path to a +\fBdnssec\-keygen\fR +binary\&. Used for testing\&. See also the +\fB\-s\fR +option\&. +.RE +.PP +\-h +.RS 4 +Print the +\fBdnssec\-keymgr\fR +help summary and exit\&. +.RE +.PP +\-K \fIdirectory\fR +.RS 4 +Sets the directory in which keys can be found\&. Defaults to the current working directory\&. +.RE +.PP +\-k +.RS 4 +Only apply policies to KSK keys\&. See also the +\fB\-z\fR +option\&. +.RE +.PP +\-q +.RS 4 +Quiet: suppress printing of +\fBdnssec\-keygen\fR +and +\fBdnssec\-settime\fR\&. +.RE +.PP +\-r \fIrandomdev\fR +.RS 4 +Specifies a path to a file containing random data\&. This is passed to the +\fBdnssec\-keygen\fR +binary using its +\fB\-r\fR +option\&. +.RE +.PP +\-s \fIsettime\-path\fR +.RS 4 +Specifies a path to a +\fBdnssec\-settime\fR +binary\&. Used for testing\&. See also the +\fB\-g\fR +option\&. +.RE +.PP +\-v +.RS 4 +Print the +\fBdnssec\-keymgr\fR +version and exit\&. +.RE +.PP +\-z +.RS 4 +Only apply policies to ZSK keys\&. See also the +\fB\-k\fR +option\&. +.RE +.SH "POLICY CONFIGURATION" +.PP +The +dnssec\-policy\&.conf +file can specify three kinds of policies: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIPolicy classes\fR +(\fBpolicy \fR\fB\fIname\fR\fR\fB { \&.\&.\&. };\fR) 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\fR +might specify 1024\-bit key sizes, but a class +\fBextra\fR +might specify 2048 bits instead; +\fBextra\fR +would be used for zones that had unusually high security needs\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Algorithm policies: (\fBalgorithm\-policy \fR\fB\fIalgorithm\fR\fR\fB { \&.\&.\&. };\fR +) 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\fR, and the new key sizes would then be used for any key of type RSASHA256\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Zone policies: (\fBzone \fR\fB\fIname\fR\fR\fB { \&.\&.\&. };\fR +) set policy for a single zone by name\&. A zone policy can inherit a policy class by including a +\fBpolicy\fR +option\&. Zone names beginning with digits (i\&.e\&., 0\-9) must be quoted\&. +.RE +.PP +Options that can be specified in policies: +.PP +\fBalgorithm\fR +.RS 4 +The key algorithm\&. If no policy is defined, the default is RSASHA256\&. +.RE +.PP +\fBcoverage\fR +.RS 4 +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\&. +.RE +.PP +\fBdirectory\fR +.RS 4 +Specifies the directory in which keys should be stored\&. +.RE +.PP +\fBkey\-size\fR +.RS 4 +Specifies the number of bits to use in creating keys\&. Takes two arguments: keytype (eihter "zsk" or "ksk") and size\&. 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 1024 bits for DSA keys and 2048 for RSA\&. +.RE +.PP +\fBkeyttl\fR +.RS 4 +The key TTL\&. If no policy is defined, the default is one hour\&. +.RE +.PP +\fBpost\-publish\fR +.RS 4 +How long after inactivation a key should be deleted from the zone\&. Note: If +\fBroll\-period\fR +is not set, this value is ignored\&. Takes two arguments: keytype (eihter "zsk" or "ksk") and a duration\&. A default value for this option can be set in algorithm policies as well as in policy classes or zone policies\&. The default is one month\&. +.RE +.PP +\fBpre\-publish\fR +.RS 4 +How long before activation a key should be published\&. Note: If +\fBroll\-period\fR +is not set, this value is ignored\&. Takes two arguments: keytype (either "zsk" or "ksk") and a duration\&. A default value for this option can be set in algorithm policies as well as in policy classes or zone policies\&. The default is one month\&. +.RE +.PP +\fBroll\-period\fR +.RS 4 +How frequently keys should be rolled over\&. Takes two arguments: keytype (eihter "zsk" or "ksk") and a duration\&. 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 one year for ZSK\*(Aqs\&. KSK\*(Aqs do not roll over by default\&. +.RE +.PP +\fBstandby\fR +.RS 4 +Not yet implemented\&. +.RE +.SH "REMAINING WORK" +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Enable scheduling of KSK rollovers using the +\fB\-P sync\fR +and +\fB\-D sync\fR +options to +\fBdnssec\-keygen\fR +and +\fBdnssec\-settime\fR\&. Check the parent zone (as in +\fBdnssec\-checkds\fR) to determine when it\*(Aqs safe for the key to roll\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Allow configuration of standby keys and use of the REVOKE bit, for keys that use RFC 5011 semantics\&. +.RE +.SH "SEE ALSO" +.PP +\fBdnssec-coverage\fR(8), +\fBdnssec-keygen\fR(8), +\fBdnssec-settime\fR(8), +\fBdnssec-checkds\fR(8) +.SH "AUTHOR" +.PP +\fBInternet Systems Consortium, Inc\&.\fR +.SH "COPYRIGHT" +.br +Copyright \(co 2016-2019 Internet Systems Consortium, Inc. ("ISC") +.br |