diff options
Diffstat (limited to 'doc/man/dnssec-keymgr.8in')
| -rw-r--r-- | doc/man/dnssec-keymgr.8in | 297 |
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. +. |