Commit 831f59eb authored by Evan Hunt's avatar Evan Hunt

[master] add dnssec-coverage tool

3528.	[func]		New "dnssec-coverage" command scans the timing
			metadata for a set of DNSSEC keys and reports if a
			lapse in signing coverage has been scheduled
			inadvertently. (Note: This tool depends on python;
			it will not be built or installed on systems that
			do not have a python interpreter.) [RT #28098]
parent 027591e1
3528. [func] New "dnssec-coverage" command scans the timing
metadata for a set of DNSSEC keys and reports if a
lapse in signing coverage has been scheduled
inadvertently. (Note: This tool depends on python;
it will not be built or installed on systems that
do not have a python interpreter.) [RT #28098]
3527. [compat] Add a URI to allow applications to explicitly
request a particular XML schema from the statistics
channel, returning 404 if not supported. [RT #32481]
......
dnssec-checkds
dnssec-checkds.py
dnssec-coverage
dnssec-coverage.py
......@@ -22,17 +22,19 @@ top_srcdir = @top_srcdir@
PYTHON = @PYTHON@
TARGETS = dnssec-checkds
SRCS = dnssec-checkds.py
TARGETS = dnssec-checkds dnssec-coverage
SRCS = dnssec-checkds.py dnssec-coverage.py
MANPAGES = dnssec-checkds.8
HTMLPAGES = dnssec-checkds.html
MANPAGES = dnssec-checkds.8 dnssec-coverage.8
HTMLPAGES = dnssec-checkds.html dnssec-coverage.html
MANOBJS = ${MANPAGES} ${HTMLPAGES}
@BIND9_MAKE_RULES@
dnssec-checkds: dnssec-checkds.py
dnssec-coverage: dnssec-coverage.py
doc man:: ${MANOBJS}
docclean manclean maintainer-clean::
......@@ -44,10 +46,12 @@ installdirs:
install:: ${TARGETS} installdirs
${INSTALL_PROGRAM} dnssec-checkds@EXEEXT@ ${DESTDIR}${sbindir}
${INSTALL_PROGRAM} dnssec-coverage@EXEEXT@ ${DESTDIR}${sbindir}
${INSTALL_DATA} ${srcdir}/dnssec-checkds.8 ${DESTDIR}${mandir}/man8
${INSTALL_DATA} ${srcdir}/dnssec-coverage.8 ${DESTDIR}${mandir}/man8
clean distclean::
rm -f ${TARGETS}
distclean::
rm -f dnssec-checkds.py
rm -f dnssec-checkds.py dnssec-coverage.py
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<refentry id="man.dnssec-coverage">
<refentryinfo>
<date>April 16, 2012</date>
</refentryinfo>
<refmeta>
<refentrytitle><application>dnssec-coverage</application></refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname><application>dnssec-coverage</application></refname>
<refpurpose>checks future DNSKEY coverage for a zone</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2012</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>dnssec-coverage</command>
<arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
<arg><option>-f <replaceable class="parameter">file</replaceable></option></arg>
<arg><option>-d <replaceable class="parameter">DNSKEY TTL</replaceable></option></arg>
<arg><option>-m <replaceable class="parameter">max TTL</replaceable></option></arg>
<arg><option>-r <replaceable class="parameter">interval</replaceable></option></arg>
<arg><option>-c <replaceable class="parameter">compilezone path</replaceable></option></arg>
<arg choice="opt">zone</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para><command>dnssec-coverage</command>
verifies that the DNSSEC keys for a given zone or a set of zones
have timing metadata set properly to ensure no future lapses in DNSSEC
coverage.
</para>
<para>
If <option>zone</option> is specified, then keys found in
the key repository matching that zone are scanned, and an ordered
list is generated of the events scheduled for that key (i.e.,
publication, activation, inactivation, deletion). The list of
events is walked in order of occurrence. Warnings are generated
if any event is scheduled which could cause the zone to enter a
state in which validation failures might occur: for example, if
the number of published or active keys for a given algorithm drops
to zero, or if a key is deleted from the zone too soon after a new
key is rolled, and cached data signed by the prior key has not had
time to expire from resolver caches.
</para>
<para>
If <option>zone</option> is not specified, then all keys in the
key repository will be scanned, and all zones for which there are
keys will be analyzed. (Note: This method of reporting is only
accurate if all the zones that have keys in a given repository
share the same TTL parameters.)
</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>-f <replaceable class="parameter">file</replaceable></term>
<listitem>
<para>
If a <option>file</option> is specified, then the zone is
read from that file; the largest TTL and the DNSKEY TTL are
determined directly from the zone data, and the
<option>-m</option> and <option>-d</option> options do
not need to be specified on the command line.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-K <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
Sets the directory in which keys can be found. Defaults to the
current working directory.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-m <replaceable class="parameter">maximum TTL</replaceable></term>
<listitem>
<para>
Sets the value to be used as the maximum TTL for the zone or
zones being analyzed when determining whether there is a
possibility of validation failure. When a zone-signing key is
deactivated, there must be enough time for the record in the
zone with the longest TTL to have expired from resolver caches
before that key can be purged from the DNSKEY RRset. If that
condition does not apply, a warning will be generated.
</para>
<para>
The length of the TTL can be set in seconds, or in larger units
of time by adding a suffix: 'mi' for minutes, 'h' for hours,
'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
</para>
<para>
This option is mandatory unless the <option>-f</option> has
been used to specify a zone file. (If <option>-f</option> has
been specified, this option may still be used; it will overrde
the value found in the file.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-d <replaceable class="parameter">DNSKEY TTL</replaceable></term>
<listitem>
<para>
Sets the value to be used as the DNSKEY TTL for the zone or
zones being analyzed when determining whether there is a
possibility of validation failure. When a key is rolled (that
is, replaced with a new key), there must be enough time
for the old DNSKEY RRset to have expired from resolver caches
before the new key is activated and begins generating
signatures. If that condition does not apply, a warning
will be generated.
</para>
<para>
The length of the TTL can be set in seconds, or in larger units
of time by adding a suffix: 'mi' for minutes, 'h' for hours,
'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
</para>
<para>
This option is mandatory unless the <option>-f</option> has
been used to specify a zone file, or a default key TTL was
set with the <option>-L</option> to
<command>dnssec-keygen</command>. (If either of those is true,
this option may still be used; it will overrde the value found
in the zone or key file.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-r <replaceable class="parameter">resign interval</replaceable></term>
<listitem>
<para>
Sets the value to be used as the resign interval for the zone
or zones being analyzed when determining whether there is a
possibility of validation failure. This value defaults to
22.5 days, which is also the default in
<command>named</command>. However, if it has been changed
by the <option>sig-validity-interval</option> option in
<filename>named.conf</filename>, then it should also be
changed here.
</para>
<para>
The length of the interval can be set in seconds, or in larger
units of time by adding a suffix: 'mi' for minutes, 'h' for hours,
'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">compilezone path</replaceable></term>
<listitem>
<para>
Specifies a path to a <command>named-compilezone</command> binary.
Used for testing.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>dnssec-checkds</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>dnssec-dsfromkey</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->
#!@PYTHON@
############################################################################
# Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC")
#
# Permission to use, copy, modify, and/or distribute this software for any
# purpose with or without fee is hereby granted, provided that the above
# copyright notice and this permission notice appear in all copies.
#
# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
############################################################################
import argparse
import os
import glob
import sys
import re
import time
import calendar
from collections import defaultdict
import pprint
prog='dnssec-coverage'
########################################################################
# Class Event
########################################################################
class Event:
""" A discrete key metadata event, e.g., Publish, Activate, Inactive,
Delete. Stores the date of the event, and identifying information about
the key to which the event will occur."""
def __init__(self, _what, _key):
now = time.time()
self.what = _what
self.when = _key.metadata[_what]
self.key = _key
self.keyid = _key.keyid
self.sep = _key.sep
self.zone = _key.zone
self.alg = _key.alg
def __repr__(self):
return repr((self.when, self.what, self.keyid, self.sep,
self.zone, self.alg))
def showtime(self):
return time.strftime("%a %b %d %H:%M:%S UTC %Y", self.when)
def showkey(self):
return self.key.showkey()
def showkeytype(self):
return self.key.showkeytype()
########################################################################
# Class Key
########################################################################
class Key:
"""An individual DNSSEC key. Identified by path, zone, algorithm, keyid.
Contains a dictionary of metadata events."""
def __init__(self, keyname):
directory = os.path.dirname(keyname)
key = os.path.basename(keyname)
(zone, alg, keyid) = key.split('+')
keyid = keyid.split('.')[0]
key = [zone, alg, keyid]
key_file = directory + os.sep + '+'.join(key) + ".key"
private_file = directory + os.sep + '+'.join(key) + ".private"
self.zone = zone[1:-1]
self.alg = int(alg)
self.keyid = int(keyid)
kfp = file(key_file, "r")
for line in kfp:
if line[0] == ';':
continue
tokens = line.split()
if not tokens:
continue
if tokens[1].lower() in ('in', 'ch', 'hs'):
septoken = 3
self.ttl = args.keyttl
if not self.ttl:
vspace()
print("WARNING: Unable to determine TTL for DNSKEY %s." %
self.showkey())
print("\t Using 1 day (86400 seconds); re-run with the -d "
"option for more\n\t accurate results.")
self.ttl = 86400
else:
septoken = 4
self.ttl = int(tokens[1]) if not args.keyttl else args.keyttl
if (int(tokens[septoken]) & 0x1) == 1:
self.sep = True
else:
self.sep = False
kfp.close()
pfp = file(private_file, "rU")
propDict = dict()
for propLine in pfp:
propDef = propLine.strip()
if len(propDef) == 0:
continue
if propDef[0] in ('!', '#'):
continue
punctuation = [propDef.find(c) for c in ':= '] + [len(propDef)]
found = min([ pos for pos in punctuation if pos != -1 ])
name = propDef[:found].rstrip()
value = propDef[found:].lstrip(":= ").rstrip()
propDict[name] = value
if("Publish" in propDict):
propDict["Publish"] = time.strptime(propDict["Publish"],
"%Y%m%d%H%M%S")
if("Activate" in propDict):
propDict["Activate"] = time.strptime(propDict["Activate"],
"%Y%m%d%H%M%S")
if("Inactive" in propDict):
propDict["Inactive"] = time.strptime(propDict["Inactive"],
"%Y%m%d%H%M%S")
if("Delete" in propDict):
propDict["Delete"] = time.strptime(propDict["Delete"],
"%Y%m%d%H%M%S")
if("Revoke" in propDict):
propDict["Revoke"] = time.strptime(propDict["Revoke"],
"%Y%m%d%H%M%S")
pfp.close()
self.metadata = propDict
def showkey(self):
return "%s/%03d/%05d" % (self.zone, self.alg, self.keyid);
def showkeytype(self):
return ("KSK" if self.sep else "ZSK")
# ensure that the gap between Publish and Activate is big enough
def check_prepub(self):
now = time.time()
if (not "Activate" in self.metadata):
debug_print("No Activate information in key: %s" % self.showkey())
return False
a = calendar.timegm(self.metadata["Activate"])
if (not "Publish" in self.metadata):
debug_print("No Publish information in key: %s" % self.showkey())
if a > now:
vspace()
print("WARNING: Key %s (%s) is scheduled for activation but \n"
"\t not for publication." %
(self.showkey(), self.showkeytype()))
return False
p = calendar.timegm(self.metadata["Publish"])
now = time.time()
if p < now and a < now:
return True
if p == a:
vspace()
print ("WARNING: %s (%s) is scheduled to be published and\n"
"\t activated at the same time. This could result in a\n"
"\t coverage gap if the zone was previously signed." %
(self.showkey(), self.showkeytype()))
print("\t Activation should be at least %s after publication."
% duration(self.ttl))
return True
if a < p:
vspace()
print("WARNING: Key %s (%s) is active before it is published" %
(self.showkey(), self.showkeytype()))
return False
if (a - p < self.ttl):
vspace()
print("WARNING: Key %s (%s) is activated too soon after\n"
"\t publication; this could result in coverage gaps due to\n"
"\t resolver caches containing old data."
% (self.showkey(), self.showkeytype()))
print("\t Activation should be at least %s after publication." %
duration(self.ttl))
return False
return True
# ensure that the gap between Inactive and Delete is big enough
def check_postpub(self, timespan = None):
if not timespan:
timespan = self.ttl
now = time.time()
if (not "Delete" in self.metadata):
debug_print("No Delete information in key: %s" % self.showkey())
return False
d = calendar.timegm(self.metadata["Delete"])
if (not "Inactive" in self.metadata):
debug_print("No Inactive information in key: %s" % self.showkey())
if d > now:
vspace()
print("WARNING: Key %s (%s) is scheduled for deletion but\n"
"\t not for inactivation." %
(self.showkey(), self.showkeytype()))
return False
i = calendar.timegm(self.metadata["Inactive"])
if d < now and i < now:
return True
if (d < i):
vspace()
print("WARNING: Key %s (%s) is scheduled for deletion before\n"
"\t inactivation." % (self.showkey(), self.showkeytype()))
return False
if (d - i < timespan):
vspace()
print("WARNING: Key %s (%s) scheduled for deletion too soon after\n"
"\t deactivation; this may result in coverage gaps due to\n"
"\t resolver caches containing old data."
% (self.showkey(), self.showkeytype()))
print("\t Deletion should be at least %s after inactivation." %
duration(timespan))
return False
return True
########################################################################
# class Zone
########################################################################
class Zone:
"""Stores data about a specific zone"""
def __init__(self, _name, _keyttl = None, _maxttl = None):
self.name = _name
self.keyttl = _keyttl
self.maxttl = _maxttl
def load(self, filename):
if not args.compilezone:
sys.stderr.write(prog + ': FATAL: "named-compilezone" not found\n')
exit(1)
if not self.name:
return
maxttl = keyttl = None
fp = os.popen("%s -o - %s %s 2> /dev/null" %
(args.compilezone, self.name, filename))
for line in fp:
fields = line.split()
if not maxttl or int(fields[1]) > maxttl:
maxttl = int(fields[1])
if fields[3] == "DNSKEY":
keyttl = int(fields[1])
fp.close()
self.keyttl = keyttl
self.maxttl = maxttl
############################################################################
# debug_print:
############################################################################
def debug_print(debugVar):
"""pretty print a variable iff debug mode is enabled"""
if not args.debug_mode:
return
if type(debugVar) == str:
print("DEBUG: " + debugVar)
else:
print("DEBUG: " + pprint.pformat(debugVar))
return
############################################################################
# vspace:
############################################################################
_firstline = True
def vspace():
"""adds vertical space between two sections of output text if and only
if this is *not* the first section being printed"""
global _firstline
if _firstline:
_firstline = False
else:
print
############################################################################
# vreset:
############################################################################
def vreset():
"""reset vertical spacing"""
global _firstline
_firstline = True
############################################################################
# getunit
############################################################################
def getunit(secs, size):
"""given a number of seconds, and a number of seconds in a larger unit of
time, calculate how many of the larger unit there are and return both
that and a remainder value"""
bigunit = secs // size
if bigunit:
secs %= size
return (bigunit, secs)
############################################################################
# addtime
############################################################################
def addtime(output, unit, t):
"""add a formatted unit of time to an accumulating string"""
if t:
output += ("%s%d %s%s" %
((", " if output else ""),
t, unit, ("s" if t > 1 else "")))
return output
############################################################################
# duration:
############################################################################
def duration(secs):
"""given a length of time in seconds, print a formatted human duration
in larger units of time
"""
# define units:
minute = 60
hour = minute * 60
day = hour * 24
month = day * 30