dnssec-keymgr.8 9.47 KB
Newer Older
Tinderbox User's avatar
Tinderbox User committed
1
.\" Copyright (C) 2016-2018 Internet Systems Consortium, Inc. ("ISC")
2
.\" 
Tinderbox User's avatar
Tinderbox User committed
3 4 5
.\" 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/.
6 7 8 9 10 11 12
.\"
.hy 0
.ad l
'\" t
.\"     Title: dnssec-keymgr
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
Tinderbox User's avatar
Tinderbox User committed
13
.\"      Date: 2016-06-03
14 15 16 17
.\"    Manual: BIND9
.\"    Source: ISC
.\"  Language: English
.\"
Tinderbox User's avatar
Tinderbox User committed
18
.TH "DNSSEC\-KEYMGR" "8" "2016\-06\-03" "ISC" "BIND9"
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
.\" -----------------------------------------------------------------
.\" * 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
Tinderbox User's avatar
Tinderbox User committed
42
\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\-s\ \fR\fB\fIpath\fR\fR] [zone...]
43 44 45 46 47 48 49 50 51
.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
Tinderbox User's avatar
Tinderbox User committed
52
/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\&.
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
.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
Tinderbox User's avatar
Tinderbox User committed
82
/etc/dnssec\-policy\&.conf; if that file doesn\*(Aqt exist, a built\-in global default policy is used\&.)
83 84 85 86 87 88 89
.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
Tinderbox User's avatar
Tinderbox User committed
90
\-g \fIkeygen\-path\fR
91 92 93 94 95 96 97 98
.RS 4
Specifies a path to a
\fBdnssec\-keygen\fR
binary\&. Used for testing\&. See also the
\fB\-s\fR
option\&.
.RE
.PP
Tinderbox User's avatar
Tinderbox User committed
99 100 101 102 103 104 105
\-h
.RS 4
Print the
\fBdnssec\-keymgr\fR
help summary and exit\&.
.RE
.PP
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
\-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
Tinderbox User's avatar
Tinderbox User committed
126
\-s \fIsettime\-path\fR
127 128 129 130 131 132 133 134
.RS 4
Specifies a path to a
\fBdnssec\-settime\fR
binary\&. Used for testing\&. See also the
\fB\-g\fR
option\&.
.RE
.PP
Tinderbox User's avatar
Tinderbox User committed
135 136 137 138 139 140 141
\-v
.RS 4
Print the
\fBdnssec\-keymgr\fR
version and exit\&.
.RE
.PP
142 143 144 145 146 147 148 149 150
\-z
.RS 4
Only apply policies to ZSK keys\&. See also the
\fB\-k\fR
option\&.
.RE
.SH "POLICY CONFIGURATION"
.PP
The
Tinderbox User's avatar
Tinderbox User committed
151
dnssec\-policy\&.conf
152 153 154 155 156 157 158 159 160 161 162
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
Tinderbox User's avatar
Tinderbox User committed
163 164 165 166 167 168 169 170
(\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
171 172 173 174 175 176 177 178 179
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Tinderbox User's avatar
Tinderbox User committed
180 181 182 183
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
184 185 186 187 188 189 190 191 192
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Tinderbox User's avatar
Tinderbox User committed
193 194 195
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
Tinderbox User's avatar
Tinderbox User committed
196
option\&. Zone names beginning with digits (i\&.e\&., 0\-9) must be quoted\&.
Tinderbox User's avatar
Tinderbox User committed
197
.RE
198 199 200 201 202
.PP
Options that can be specified in policies:
.PP
\fBalgorithm\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
203 204
The key algorithm\&. If no policy is defined, the default is RSASHA256\&.
.RE
205 206 207
.PP
\fBcoverage\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
208 209
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
210 211 212
.PP
\fBdirectory\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
213 214
Specifies the directory in which keys should be stored\&.
.RE
215 216 217
.PP
\fBkey\-size\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
218
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 2048 bits for RSA keys\&.
Tinderbox User's avatar
Tinderbox User committed
219
.RE
220 221 222
.PP
\fBkeyttl\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
223 224
The key TTL\&. If no policy is defined, the default is one hour\&.
.RE
225 226 227
.PP
\fBpost\-publish\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
228 229 230 231
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
232 233 234
.PP
\fBpre\-publish\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
235 236 237 238
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
239 240 241
.PP
\fBroll\-period\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
242 243
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
244 245 246
.PP
\fBstandby\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
247 248
Not yet implemented\&.
.RE
249 250 251 252 253 254 255 256 257 258
.SH "REMAINING WORK"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Tinderbox User's avatar
Tinderbox User committed
259 260 261 262 263 264 265 266 267 268
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
269 270 271 272 273 274 275 276 277
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Tinderbox User's avatar
Tinderbox User committed
278 279
Allow configuration of standby keys and use of the REVOKE bit, for keys that use RFC 5011 semantics\&.
.RE
280 281 282 283 284 285 286 287 288 289 290
.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
Tinderbox User's avatar
Tinderbox User committed
291
Copyright \(co 2016-2018 Internet Systems Consortium, Inc. ("ISC")
292
.br