1DNSSEC-KEYMGR(8)                     BIND9                    DNSSEC-KEYMGR(8)
2
3
4
5  .SH "NAME" dnssec-keymgr - Ensures correct DNSKEY coverage for a zone based
6on a defined policy
7  .SH "SYNOPSIS"
8    .HP 14
9      dnssec-keymgr
10       [-K directory]
11       [-c file]
12       [-d time]
13       [-k]
14       [-z]
15       [-g path]
16       [-s path]
17       [zone...]
18  .SH "DESCRIPTION"
19    .PP dnssec-keymgr is a high level Python wrapper to facilitate the key
20rollover process for zones handled by BIND. It uses the BIND commands for
21manipulating DNSSEC key metadata: dnssec-keygen and dnssec-settime.
22    .PP DNSSEC policy can be read from a configuration file (default
23/etc/dnssec.policy), from which the key parameters, publication and rollover
24schedule, and desired coverage duration for any given zone can be determined.
25This file may be used to define individual DNSSEC policies on a per-zone
26basis, or to set a default policy used for all zones.
27    .PP When dnssec-keymgr runs, it examines the DNSSEC keys for one or more
28zones, comparing their timing metadata against the policies for those zones.
29If key settings do not conform to the DNSSEC policy (for example, because the
30policy has been changed), they are automatically corrected.
31    .PP A zone policy can specify a duration for which we want to ensure the
32key correctness (coverage). It can also specify a rollover period
33(roll-period). If policy indicates that a key should roll over before the
34coverage period ends, then a successor key will automatically be created and
35added to the end of the key series.
36    .PP If zones are specified on the command line, dnssec-keymgr will examine
37only those zones. If a specified zone does not already have keys in place,
38then keys will be generated for it according to policy.
39    .PP If zones are not specified on the command line, then dnssec-keymgr
40will search the key directory (either the current working directory or the
41directory set by the -K option), and check the keys for all the zones
42represented in the directory.
43    .PP It is expected that this tool will be run automatically and unattended
44(for example, by cron).
45  .SH "OPTIONS"
46      .PP -K directory
47                     Sets the directory in which keys can be found. Defaults
48           to the current working directory.
49                 .RE
50                 .PP -c file
51                         If -c is specified, then the DNSSEC policy is read
52               from file. (If not specified, then the policy is read from
53               /etc/policy.conf; if that file doesn't exist, a built-in global
54               default policy is used.)
55                     .RE
56                     .PP -f
57                             Force: allow updating of key events even if they
58                   are already in the past. This is not recommended for use
59                   with zones in which keys have already been published.
60                   However, if a set of keys has been generated all of which
61                   have publication and activation dates in the past, but the
62                   keys have not been published in a zone as yet, then this
63                   option can be used to clean them up and turn them into a
64                   proper series of keys with appropriate rollover intervals.
65                         .RE
66                         .PP -q
67                                 Quiet: suppress printing of dnssec-keygen and
68                       dnssec-settime.
69                             .RE
70                             .PP -k
71                                     Only apply policies to KSK keys.
72                                 .RE
73                                 .PP -z
74                                         Only apply policies to ZSK keys.
75                                     .RE
76                                     .PP -g keygen path
77                                             Specifies a path to a
78                                   dnssec-keygen binary. Used for testing.
79                                         .RE
80                                         .PP -s settime path
81                                                 Specifies a path to a
82                                       dnssec-settime binary. Used for
83                                       testing.
84                                             .RE
85                                         .SH "POLICY CONFIGURATION"
86                                           .PP The policy.conf file can
87                                       specify three kinds of policies:
88
89                                       ·        Policy classes      (policy
90                                           name { ... };)      can be
91                                           inherited by zone policies or other
92                                           policy classes; these      can be
93                                           used to create sets of different
94                                           security profiles. For
95                                                example, a policy class normal
96                                           might specify      1024-bit key
97                                           sizes, but a class extra might
98                                                specify 2048 bits instead;
99                                           extra would be      used for zones
100                                           that had unusually high security
101                                           needs.
102                                                 .RE
103
104                                           ·        Algorithm policies:
105                                                    (algorithm-policy
106                                               algorithm { ... }; )
107                                                    override default
108                                               per-algorithm settings.  For
109                                               example, by default,
110                                                    RSASHA256 keys use
111                                               2048-bit key sizes for both KSK
112                                               and ZSK. This      can be
113                                               modified using
114                                               algorithm-policy, and the
115                                                    new key sizes would then
116                                               be used for any key of type
117                                               RSASHA256.
118                                                     .RE
119
120                                               ·        Zone policies:
121                                                        (zone name { ... }; )
122                                                        set policy for a
123                                                   single zone by name. A zone
124                                                   policy can inherit      a
125                                                   policy class by including a
126                                                   policy option.
127                                                         .RE
128                                                       .PP Options that can be
129                                                   specified in policies:
130                                                         .PP directory
131                                                              Specifies the
132                                                       directory in which keys
133                                                       should be stored.
134                                                             .RE
135                                                             .PP algorithm
136                                                                  The key
137                                                           algorithm. If no
138                                                           policy is defined,
139                                                           the default is
140                                                                 RSASHA256.
141                                                                 .RE
142                                                                 .PP keyttl
143                                                                      The key
144                                                               TTL. If no
145                                                               policy is
146                                                               defined, the
147                                                               default is one
148                                                               hour.
149                                                                     .RE
150                                                                     .PP
151                                                               coverage
152                                                                          The
153                                                                   length of
154                                                                   time to
155                                                                   ensure that
156                                                                   keys will
157                                                                   be correct;
158                                                                   no action
159                                                                         will
160                                                                   be taken to
161                                                                   create new
162                                                                   keys to be
163                                                                   activated
164                                                                   after this
165                                                                   time.
166                                                                         This
167                                                                   can be
168                                                                   represented
169                                                                   as a number
170                                                                   of seconds,
171                                                                   or as a
172                                                                   duration
173                                                                   using
174                                                                   human-readable
175                                                                   units
176                                                                   (examples:
177                                                                   "1y" or "6
178                                                                   months").
179                                                                          A
180                                                                   default
181                                                                   value for
182                                                                   this option
183                                                                   can be set
184                                                                   in
185                                                                   algorithm
186                                                                   policies
187                                                                          as
188                                                                   well as in
189                                                                   policy
190                                                                   classes or
191                                                                   zone
192                                                                   policies.
193                                                                         If no
194                                                                   policy is
195                                                                   configured,
196                                                                   the default
197                                                                   is six
198                                                                   months.
199                                                                         .RE
200                                                                         .PP
201                                                                   key-size
202
203                                                                       Specifies
204                                                                       the
205                                                                       number
206                                                                       of bits
207                                                                       to use
208                                                                       in
209                                                                       creating
210                                                                       keys.
211
212                                                                       Takes
213                                                                       two
214                                                                       arguments:
215                                                                       keytype
216                                                                       (eihter
217                                                                       "zsk"
218                                                                       or
219                                                                       "ksk")
220                                                                       and
221                                                                       size.
222
223                                                                       A
224                                                                       default
225                                                                       value
226                                                                       for
227                                                                       this
228                                                                       option
229                                                                       can be
230                                                                       set in
231                                                                       algorithm
232                                                                       policies
233
234                                                                       as well
235                                                                       as in
236                                                                       policy
237                                                                       classes
238                                                                       or zone
239                                                                       policies.
240                                                                       If no
241                                                                       policy
242                                                                       is
243                                                                             configured,
244                                                                       the
245                                                                       default
246                                                                       is 1024
247                                                                       bits
248                                                                       for DSA
249                                                                       keys
250                                                                       and
251                                                                       2048
252                                                                       for
253                                                                             RSA.
254                                                                             .RE
255                                                                             .PP
256                                                                       roll-period
257
258                                                                           How
259                                                                           frequently
260                                                                           keys
261                                                                           should
262                                                                           be
263                                                                           rolled
264                                                                           over.
265
266                                                                           Takes
267                                                                           two
268                                                                           arguments:
269                                                                           keytype
270                                                                           (eihter
271                                                                           "zsk"
272                                                                           or
273                                                                           "ksk")
274                                                                           and
275                                                                           a
276                                                                           duration.
277
278                                                                           A
279                                                                           default
280                                                                           value
281                                                                           for
282                                                                           this
283                                                                           option
284                                                                           can
285                                                                           be
286                                                                           set
287                                                                           in
288                                                                           algorithm
289                                                                           policies
290
291                                                                           as
292                                                                           well
293                                                                           as
294                                                                           in
295                                                                           policy
296                                                                           classes
297                                                                           or
298                                                                           zone
299                                                                           policies.
300                                                                           If
301                                                                           no
302                                                                           policy
303                                                                           is
304                                                                                 configured,
305                                                                           the
306                                                                           default
307                                                                           is
308                                                                           one
309                                                                           year
310                                                                           for
311                                                                           ZSK's.
312                                                                           KSK's
313                                                                           do
314                                                                           not
315                                                                                 roll
316                                                                           over
317                                                                           by
318                                                                           default.
319                                                                                 .RE
320                                                                                 .PP
321                                                                           pre-publish
322
323                                                                               How
324                                                                               long
325                                                                               before
326                                                                               activation
327                                                                               a
328                                                                               key
329                                                                               should
330                                                                               be
331                                                                               published.
332                                                                               Note:
333                                                                               If
334                                                                                     roll-period
335                                                                               is
336                                                                               not
337                                                                               set,
338                                                                               this
339                                                                               value
340                                                                               is
341                                                                               ignored.
342
343                                                                               Takes
344                                                                               two
345                                                                               arguments:
346                                                                               keytype
347                                                                               (either
348                                                                               "zsk"
349                                                                               or
350                                                                               "ksk")
351                                                                               and
352                                                                               a
353                                                                               duration.
354
355                                                                               A
356                                                                               default
357                                                                               value
358                                                                               for
359                                                                               this
360                                                                               option
361                                                                               can
362                                                                               be
363                                                                               set
364                                                                               in
365                                                                               algorithm
366                                                                               policies
367
368                                                                               as
369                                                                               well
370                                                                               as
371                                                                               in
372                                                                               policy
373                                                                               classes
374                                                                               or
375                                                                               zone
376                                                                               policies.
377                                                                               The
378                                                                               default
379                                                                               is
380                                                                                     one
381                                                                               month.
382                                                                                     .RE
383                                                                                     .PP
384                                                                               post-publish
385
386                                                                                   How
387                                                                                   long
388                                                                                   after
389                                                                                   inactivation
390                                                                                   a
391                                                                                   key
392                                                                                   should
393                                                                                   be
394                                                                                   deleted
395                                                                                   from
396                                                                                   the
397                                                                                   zone.
398
399                                                                                   Note:
400                                                                                   If
401                                                                                   roll-period
402                                                                                   is
403                                                                                   not
404                                                                                   set,
405                                                                                   this
406                                                                                   value
407                                                                                   is
408                                                                                   ignored.
409
410                                                                                   Takes
411                                                                                   two
412                                                                                   arguments:
413                                                                                   keytype
414                                                                                   (eihter
415                                                                                   "zsk"
416                                                                                   or
417                                                                                   "ksk")
418                                                                                   and
419                                                                                   a
420                                                                                   duration.
421
422                                                                                   A
423                                                                                   default
424                                                                                   value
425                                                                                   for
426                                                                                   this
427                                                                                   option
428                                                                                   can
429                                                                                   be
430                                                                                   set
431                                                                                   in
432                                                                                   algorithm
433                                                                                   policies
434
435                                                                                   as
436                                                                                   well
437                                                                                   as
438                                                                                   in
439                                                                                   policy
440                                                                                   classes
441                                                                                   or
442                                                                                   zone
443                                                                                   policies.
444                                                                                   The
445                                                                                   default
446                                                                                   is
447                                                                                   one
448                                                                                         month.
449                                                                                         .RE
450                                                                                         .PP
451                                                                                   standby
452
453                                                                                       Not
454                                                                                       yet
455                                                                                       implemented.
456                                                                                             .RE
457                                                                                         .SH
458                                                                                       "REMAINING
459                                                                                       WORK"
460
461                                                                                       ·
462                                                                                           Enable
463                                                                                           scheduling
464                                                                                           of
465                                                                                           KSK
466                                                                                           rollovers
467                                                                                           using
468                                                                                           the
469                                                                                           -P
470                                                                                           sync
471                                                                                                 and
472                                                                                           -D
473                                                                                           sync
474                                                                                           options
475                                                                                           to
476                                                                                                 dnssec-keygen
477                                                                                           and
478                                                                                                 dnssec-settime.
479                                                                                           Check
480                                                                                           the
481                                                                                           parent
482                                                                                           zone
483                                                                                                 (as
484                                                                                           in
485                                                                                           dnssec-checkds)
486                                                                                           to
487                                                                                           determine
488                                                                                           when
489                                                                                           it's
490                                                                                                 safe
491                                                                                           for
492                                                                                           the
493                                                                                           key
494                                                                                           to
495                                                                                           roll.
496                                                                                               .RE
497
498                                                                                           ·
499                                                                                               Allow
500                                                                                               configuration
501                                                                                               of
502                                                                                               standby
503                                                                                               keys
504                                                                                               and
505                                                                                               use
506                                                                                               of
507                                                                                               the
508                                                                                               REVOKE
509                                                                                               bit,
510                                                                                                     for
511                                                                                               keys
512                                                                                               that
513                                                                                               use
514                                                                                               RFC
515                                                                                               5011
516                                                                                               semantics.
517                                                                                                   .RE
518                                                                                                 .SH
519                                                                                               "SEE
520                                                                                               ALSO"
521                                                                                                   .PP
522                                                                                               dnssec-
523                                                                                               coverage(8),
524                                                                                               dnssec-
525                                                                                               keygen(8),
526                                                                                               dnssec-
527                                                                                               settime(8),
528                                                                                               dnssec-
529                                                                                               checkds(8)
530

AUTHOR

532       Internet Systems Consortium, Inc.
533
535       Copyright © 2016 Internet Systems Consortium, Inc. ("ISC")
536
537
538
539ISC                               2016-04-03                  DNSSEC-KEYMGR(8)
Impressum