dnssec-keymgr.html 13.2 KB
Newer Older
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2
<!--
Tinderbox User's avatar
Tinderbox User committed
3
 - Copyright (C) 2016-2018 Internet Systems Consortium, Inc. ("ISC")
4
 - 
Tinderbox User's avatar
Tinderbox User committed
5 6 7
 - 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/.
8
-->
9
<html lang="en">
10 11 12 13 14 15 16
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>dnssec-keymgr</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
<a name="man.dnssec-keymgr"></a><div class="titlepage"></div>
Tinderbox User's avatar
Tinderbox User committed
17 18 19 20 21 22
  
  

  

  <div class="refnamediv">
23
<h2>Name</h2>
Tinderbox User's avatar
Tinderbox User committed
24 25 26 27
<p>
    <span class="application">dnssec-keymgr</span>
     &#8212; Ensures correct DNSKEY coverage for a zone based on a defined policy
  </p>
28
</div>
Tinderbox User's avatar
Tinderbox User committed
29 30 31 32

  

  <div class="refsynopsisdiv">
33
<h2>Synopsis</h2>
Tinderbox User's avatar
Tinderbox User committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
    <div class="cmdsynopsis"><p>
      <code class="command">dnssec-keymgr</code> 
       [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>]
       [<code class="option">-c <em class="replaceable"><code>file</code></em></code>]
       [<code class="option">-f</code>]
       [<code class="option">-k</code>]
       [<code class="option">-q</code>]
       [<code class="option">-v</code>]
       [<code class="option">-z</code>]
       [<code class="option">-g <em class="replaceable"><code>path</code></em></code>]
       [<code class="option">-s <em class="replaceable"><code>path</code></em></code>]
       [zone...]
    </p></div>
  </div>

  <div class="refsection">
50
<a name="id-1.7"></a><h2>DESCRIPTION</h2>
Tinderbox User's avatar
Tinderbox User committed
51
    <p>
Tinderbox User's avatar
Tinderbox User committed
52 53 54 55
      <span class="command"><strong>dnssec-keymgr</strong></span> 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: <span class="command"><strong>dnssec-keygen</strong></span> and
56 57
      <span class="command"><strong>dnssec-settime</strong></span>.
    </p>
Tinderbox User's avatar
Tinderbox User committed
58
    <p>
59
      DNSSEC policy can be read from a configuration file (default
Tinderbox User's avatar
Tinderbox User committed
60
      <code class="filename">/etc/dnssec-policy.conf</code>), from which the key
61 62 63 64 65
      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.
    </p>
Tinderbox User's avatar
Tinderbox User committed
66
    <p>
67 68 69 70 71 72
      When <span class="command"><strong>dnssec-keymgr</strong></span> 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.
    </p>
Tinderbox User's avatar
Tinderbox User committed
73
    <p>
74 75 76 77 78 79 80
      A zone policy can specify a duration for which we want to
      ensure the key correctness (<code class="option">coverage</code>).  It can
      also specify a rollover period (<code class="option">roll-period</code>).
      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.
    </p>
Tinderbox User's avatar
Tinderbox User committed
81
    <p>
82 83 84 85 86
      If zones are specified on the command line,
      <span class="command"><strong>dnssec-keymgr</strong></span> 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.
    </p>
Tinderbox User's avatar
Tinderbox User committed
87
    <p>
88 89 90 91 92 93
      If zones are <span class="emphasis"><em>not</em></span> specified on the command
      line, then <span class="command"><strong>dnssec-keymgr</strong></span> will search the
      key directory (either the current working directory or the directory
      set by the <code class="option">-K</code> option), and check the keys for
      all the zones represented in the directory.
    </p>
Tinderbox User's avatar
Tinderbox User committed
94
    <p>
95 96 97
      It is expected that this tool will be run automatically and
      unattended (for example, by <span class="command"><strong>cron</strong></span>).
    </p>
Tinderbox User's avatar
Tinderbox User committed
98 99 100
  </div>

  <div class="refsection">
101
<a name="id-1.8"></a><h2>OPTIONS</h2>
Tinderbox User's avatar
Tinderbox User committed
102
    <div class="variablelist"><dl class="variablelist">
103
<dt><span class="term">-c <em class="replaceable"><code>file</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
104
<dd>
Tinderbox User's avatar
Tinderbox User committed
105 106 107 108 109 110 111 112
	  <p>
	    If <code class="option">-c</code> is specified, then the DNSSEC
	    policy is read from <code class="option">file</code>.  (If not
	    specified, then the policy is read from
	    <code class="filename">/etc/dnssec-policy.conf</code>; if that file
	    doesn't exist, a built-in global default policy is used.)
	  </p>
	</dd>
113
<dt><span class="term">-f</span></dt>
Tinderbox User's avatar
Tinderbox User committed
114
<dd>
Tinderbox User's avatar
Tinderbox User committed
115 116 117 118 119 120 121 122 123 124 125
	  <p>
	    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.
	  </p>
	</dd>
Tinderbox User's avatar
Tinderbox User committed
126
<dt><span class="term">-g <em class="replaceable"><code>keygen-path</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
127
<dd>
Tinderbox User's avatar
Tinderbox User committed
128 129 130 131 132 133
	  <p>
	    Specifies a path to a <span class="command"><strong>dnssec-keygen</strong></span> binary.
	    Used for testing.
	    See also the <code class="option">-s</code> option.
	  </p>
	</dd>
Tinderbox User's avatar
Tinderbox User committed
134
<dt><span class="term">-h</span></dt>
Tinderbox User's avatar
Tinderbox User committed
135
<dd>
Tinderbox User's avatar
Tinderbox User committed
136 137 138 139 140
	  <p>
	    Print the <span class="command"><strong>dnssec-keymgr</strong></span> help summary
	    and exit.
	  </p>
	</dd>
141
<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
142
<dd>
Tinderbox User's avatar
Tinderbox User committed
143 144 145 146 147
	  <p>
	    Sets the directory in which keys can be found.  Defaults to the
	    current working directory.
	  </p>
	</dd>
148
<dt><span class="term">-k</span></dt>
Tinderbox User's avatar
Tinderbox User committed
149
<dd>
Tinderbox User's avatar
Tinderbox User committed
150 151 152 153 154
	  <p>
	    Only apply policies to KSK keys.
	    See also the <code class="option">-z</code> option.
	  </p>
	</dd>
155
<dt><span class="term">-q</span></dt>
Tinderbox User's avatar
Tinderbox User committed
156
<dd>
Tinderbox User's avatar
Tinderbox User committed
157 158 159 160 161
	  <p>
	    Quiet: suppress printing of <span class="command"><strong>dnssec-keygen</strong></span>
	    and <span class="command"><strong>dnssec-settime</strong></span>.
	  </p>
	</dd>
Tinderbox User's avatar
Tinderbox User committed
162
<dt><span class="term">-s <em class="replaceable"><code>settime-path</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
163
<dd>
Tinderbox User's avatar
Tinderbox User committed
164 165 166 167 168 169
	  <p>
	    Specifies a path to a <span class="command"><strong>dnssec-settime</strong></span> binary.
	    Used for testing.
	    See also the <code class="option">-g</code> option.
	  </p>
	</dd>
Tinderbox User's avatar
Tinderbox User committed
170
<dt><span class="term">-v</span></dt>
Tinderbox User's avatar
Tinderbox User committed
171
<dd>
Tinderbox User's avatar
Tinderbox User committed
172
	  <p>
Tinderbox User's avatar
Tinderbox User committed
173
	    Print the <span class="command"><strong>dnssec-keymgr</strong></span> version and exit.
Tinderbox User's avatar
Tinderbox User committed
174 175
	  </p>
	</dd>
176
<dt><span class="term">-z</span></dt>
Tinderbox User's avatar
Tinderbox User committed
177
<dd>
Tinderbox User's avatar
Tinderbox User committed
178 179 180 181 182
	  <p>
	    Only apply policies to ZSK keys.
	    See also the <code class="option">-k</code> option.
	  </p>
	</dd>
183
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
184 185 186
  </div>

  <div class="refsection">
187
<a name="id-1.9"></a><h2>POLICY CONFIGURATION</h2>
Tinderbox User's avatar
Tinderbox User committed
188
    <p>
Tinderbox User's avatar
Tinderbox User committed
189
      The <code class="filename">dnssec-policy.conf</code> file can specify three kinds
190 191
      of policies:
    </p>
Tinderbox User's avatar
Tinderbox User committed
192 193 194
    <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
	<p>
Tinderbox User's avatar
Tinderbox User committed
195 196 197 198 199 200 201 202
	  <span class="emphasis"><em>Policy classes</em></span>
	  (<code class="option">policy <em class="replaceable"><code>name</code></em> { ... };</code>)
	  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 <strong class="userinput"><code>normal</code></strong> might specify
	  1024-bit key sizes, but a class <strong class="userinput"><code>extra</code></strong> might
	  specify 2048 bits instead; <strong class="userinput"><code>extra</code></strong> would be
	  used for zones that had unusually high security needs.
Tinderbox User's avatar
Tinderbox User committed
203 204 205 206
	</p>
      </li>
<li class="listitem">
	<p>
Tinderbox User's avatar
Tinderbox User committed
207 208 209 210 211 212
	  Algorithm policies:
	  (<code class="option">algorithm-policy <em class="replaceable"><code>algorithm</code></em> { ... };</code> )
	  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 <span class="command"><strong>algorithm-policy</strong></span>, and the
	  new key sizes would then be used for any key of type RSASHA256.
Tinderbox User's avatar
Tinderbox User committed
213 214 215 216
	</p>
      </li>
<li class="listitem">
	<p>
Tinderbox User's avatar
Tinderbox User committed
217 218 219 220
	  Zone policies:
	  (<code class="option">zone <em class="replaceable"><code>name</code></em> { ... };</code> )
	  set policy for a single zone by name. A zone policy can inherit
	  a policy class by including a <code class="option">policy</code> option.
Tinderbox User's avatar
Tinderbox User committed
221
	  Zone names beginning with digits (i.e., 0-9) must be quoted.
Tinderbox User's avatar
Tinderbox User committed
222 223
	</p>
      </li>
224
</ul></div>
Tinderbox User's avatar
Tinderbox User committed
225
    <p>
226 227
      Options that can be specified in policies:
    </p>
Tinderbox User's avatar
Tinderbox User committed
228
    <div class="variablelist"><dl class="variablelist">
229
<dt><span class="term"><span class="command"><strong>algorithm</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
230 231
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
232
	    The key algorithm. If no policy is defined, the default is
Tinderbox User's avatar
Tinderbox User committed
233
	    RSASHA256.
Tinderbox User's avatar
Tinderbox User committed
234 235
	  </p>
	</dd>
236
<dt><span class="term"><span class="command"><strong>coverage</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
237 238
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
239
	    The length of time to ensure that keys will be correct; no action
Tinderbox User's avatar
Tinderbox User committed
240 241
	    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
Tinderbox User's avatar
Tinderbox User committed
242 243 244
	    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.
Tinderbox User's avatar
Tinderbox User committed
245
	    If no policy is configured, the default is six months.
Tinderbox User's avatar
Tinderbox User committed
246 247
	  </p>
	</dd>
248
<dt><span class="term"><span class="command"><strong>directory</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
249
<dd>
Tinderbox User's avatar
Tinderbox User committed
250
	  <p>
Tinderbox User's avatar
Tinderbox User committed
251
	    Specifies the directory in which keys should be stored.
Tinderbox User's avatar
Tinderbox User committed
252
	  </p>
Tinderbox User's avatar
Tinderbox User committed
253
	</dd>
254
<dt><span class="term"><span class="command"><strong>key-size</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
255 256
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
257 258 259 260
	    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
Tinderbox User's avatar
Tinderbox User committed
261
	    configured, the default is 2048 bits for RSA keys.
Tinderbox User's avatar
Tinderbox User committed
262 263
	  </p>
	</dd>
264
<dt><span class="term"><span class="command"><strong>keyttl</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
265 266
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
267
	    The key TTL. If no policy is defined, the default is one hour.
Tinderbox User's avatar
Tinderbox User committed
268 269
	  </p>
	</dd>
270
<dt><span class="term"><span class="command"><strong>post-publish</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
271 272
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
273 274 275 276 277 278
	    How long after inactivation a key should be deleted from the zone.
	    Note: If <code class="option">roll-period</code> 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.
Tinderbox User's avatar
Tinderbox User committed
279 280
	  </p>
	</dd>
281
<dt><span class="term"><span class="command"><strong>pre-publish</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
282 283
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
284
	    How long before activation a key should be published.  Note: If
Tinderbox User's avatar
Tinderbox User committed
285
	    <code class="option">roll-period</code> is not set, this value is ignored.
Tinderbox User's avatar
Tinderbox User committed
286 287 288
	    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
Tinderbox User's avatar
Tinderbox User committed
289
	    one month.
Tinderbox User's avatar
Tinderbox User committed
290 291
	  </p>
	</dd>
292
<dt><span class="term"><span class="command"><strong>roll-period</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
293 294
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
295 296 297 298
	    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
Tinderbox User's avatar
Tinderbox User committed
299 300
	    configured, the default is one year for ZSK's. KSK's do not
	    roll over by default.
Tinderbox User's avatar
Tinderbox User committed
301 302
	  </p>
	</dd>
303
<dt><span class="term"><span class="command"><strong>standby</strong></span></span></dt>
Tinderbox User's avatar
Tinderbox User committed
304 305
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
306
	    Not yet implemented.
Tinderbox User's avatar
Tinderbox User committed
307 308
	  </p>
	</dd>
309
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
310 311 312
  </div>

  <div class="refsection">
313
<a name="id-1.10"></a><h2>REMAINING WORK</h2>
Tinderbox User's avatar
Tinderbox User committed
314 315 316
  <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
      <p>
Tinderbox User's avatar
Tinderbox User committed
317 318 319 320 321 322
	Enable scheduling of KSK rollovers using the <code class="option">-P sync</code>
	and <code class="option">-D sync</code> options to
	<span class="command"><strong>dnssec-keygen</strong></span> and
	<span class="command"><strong>dnssec-settime</strong></span>.  Check the parent zone
	(as in <span class="command"><strong>dnssec-checkds</strong></span>) to determine when it's
	safe for the key to roll.
Tinderbox User's avatar
Tinderbox User committed
323 324 325 326
      </p>
    </li>
<li class="listitem">
      <p>
Tinderbox User's avatar
Tinderbox User committed
327 328
	Allow configuration of standby keys and use of the REVOKE bit,
	for keys that use RFC 5011 semantics.
Tinderbox User's avatar
Tinderbox User committed
329 330
      </p>
    </li>
331
</ul></div>
Tinderbox User's avatar
Tinderbox User committed
332 333 334
  </div>

  <div class="refsection">
335
<a name="id-1.11"></a><h2>SEE ALSO</h2>
Tinderbox User's avatar
Tinderbox User committed
336 337 338 339 340 341 342 343 344 345 346 347 348
    <p>
      <span class="citerefentry">
	<span class="refentrytitle">dnssec-coverage</span>(8)
      </span>,
      <span class="citerefentry">
	<span class="refentrytitle">dnssec-keygen</span>(8)
      </span>,
      <span class="citerefentry">
	<span class="refentrytitle">dnssec-settime</span>(8)
      </span>,
      <span class="citerefentry">
	<span class="refentrytitle">dnssec-checkds</span>(8)
      </span>
349
    </p>
Tinderbox User's avatar
Tinderbox User committed
350 351
  </div>

352 353
</div></body>
</html>