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:
-->
This diff is collapsed.
......@@ -44,6 +44,7 @@ REVOKE=$TOP/bin/dnssec/dnssec-revoke
SETTIME=$TOP/bin/dnssec/dnssec-settime
DSFROMKEY=$TOP/bin/dnssec/dnssec-dsfromkey
CHECKDS=$TOP/bin/python/dnssec-checkds
COVERAGE=$TOP/bin/python/dnssec-coverage
CHECKZONE=$TOP/bin/check/named-checkzone
CHECKCONF=$TOP/bin/check/named-checkconf
PK11GEN="$TOP/bin/pkcs11/pkcs11-keygen -s ${SLOT:-0} -p 1234"
......@@ -57,8 +58,8 @@ ARPANAME=$TOP/bin/tools/arpaname
# load on the machine to make it unusable to other users.
# v6synth
SUBDIRS="acl additional allow_query addzone autosign builtin
cacheclean checkconf @CHECKDS@ checknames checkzone database
dlv dlvauto dlz dlzexternal dlzredir dname dns64 dnssec
cacheclean checkconf @CHECKDS@ checknames checkzone @COVERAGE@
database dlv dlvauto dlz dlzexternal dlzredir dname dns64 dnssec
dsdigest ecdsa formerr forward glue gost ixfr inline limits
logfileconfig lwresd masterfile masterformat metadata
notify nsupdate pending pkcs11 redirect resolver rndc rpz
......
This set includes one KSK rollover. The KSK is deactivated prior to
its replacement being activated. Tool output should resemble:
Checking KSK events for zone example.com, algorithm 7:
ERROR: After 2012-31-Jul (20:59:14):
Inactive: example.com/007/45435 (KSK)
No KSK's are active
Checking ZSK events for zone example.com, algorithm 7:
OK
args="-d 1h -m 2h"
warn=0
error=1
ok=1
retcode=1
match="No KSK's are active"
This set includes one ZSK rollover. The first ZSK is deactivated
prior to its replacement being activated. Tool output should resemble:
Checking KSK events for zone example.com, algorithm 7:
OK
Checking ZSK events for zone example.com, algorithm 7:
ERROR: After 2012-05-Dec (20:39:32):
Inactive: example.com/005/08376 (ZSK)
No ZSK's are active
args="-d 1h -m 2h"
warn=0
error=1
ok=1
retcode=1
match="No ZSK's are active"
This set contains one KSK rollover. The KSK is unpublished before its
successor is published. Tool output should resemble:
Checking KSK events for zone example.com, algorithm 7:
ERROR: After 2012-06-Oct (21:07:57):
Delete: example.com/007/23040 (KSK)
No KSK's are published
Checking ZSK events for zone example.com, algorithm 7:
OK
args="-d 1h -m 2h"
warn=1
error=1
ok=1
retcode=1
match="WARNING: Key .* (KSK) is scheduled for deletion before
No KSK's are published"
This set contains one ZSK rollover. The ZSK is unpublished before its
successor is published. Tool output should resemble:
Checking KSK events for zone example.com, algorithm 7:
OK
Checking ZSK events for zone example.com, algorithm 7:
ERROR: After 2012-06-Oct (21:13:45):
Delete: example.com/007/25967 (ZSK)
No ZSK's are published
args="-d 1h -m 2h"
warn=1
error=1
ok=1
retcode=1
match="WARNING: Key .* (ZSK) is scheduled for deletion before
No ZSK's are published"
This set includes one KSK rollover. The first KSK is deleted
and its successor published prior to the first KSK being deactivated
and its successor activated. Tool output should resemble:
Checking KSK events for zone example.com, algorithm 7:
ERROR: After 2012-05-Dec (21:22:19):
Delete: example.com/007/06219 (KSK)
Publish: example.com/007/20559 (KSK)
No KSK's are both active and published
Checking ZSK events for zone example.com, algorithm 7:
OK
args="-d 1h -m 2h"
warn=1
error=1
ok=1
retcode=1
match="WARNING: Key .* (KSK) is scheduled for deletion before
No KSK's are both active and published"
This set includes one KSK rollover. The first KSK is deleted
and its successor published prior to the first KSK being deactivated
and its successor activated. Tool output should resemble:
Checking KSK events for zone example.com, algorithm 7:
OK
Checking ZSK events for zone example.com, algorithm 7:
ERROR: After 2012-05-Dec (20:44:18):
Delete: example.com/007/26369 (ZSK)
Publish: example.com/007/21029 (ZSK)
No ZSK's are both active and published
args="-d 1h -m 2h"
warn=1
error=1
ok=1
retcode=1
match="WARNING: Key .* (ZSK) is scheduled for deletion before
No ZSK's are both active and published"
This set includes a KSK rollover, with insufficient delay between
prepublication and rollover.
Expected tool output TBD.
args="-d 1w -m 2w"
warn=1
error=0
ok=2
retcode=0
match="WARNING: Key .* (KSK) is activated too soon after
Activation should be at least 7 days after publication."
This set includes a KSK rollover, with insufficient delay between
prepublication and rollover.
Expected tool output TBD.
args="-d 1w -m 2w"
warn=1
error=0
ok=2
retcode=0
match="WARNING: Key .* (ZSK) is activated too soon after
Activation should be at least 7 days after publication."
#!/bin/sh
rm -f named-compilezone
rm -f */K*.key
rm -f */K*.private
rm -rf coverage.*
rm -f random.data
#!/bin/sh
# 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.
SYSTEMTESTTOP=..
. $SYSTEMTESTTOP/conf.sh
KEYGEN="$KEYGEN -qr random.data"
sh clean.sh
ln -s $CHECKZONE named-compilezone
../../../tools/genrandom 400 random.data
# Test 1: KSK goes inactive before successor is active
dir=01-ksk-inactive
rm -f $dir/K*.key
rm -f $dir/K*.private
ksk1=`$KEYGEN -K $dir -3fk example.com`
$SETTIME -K $dir -I +9mo -D +1y $ksk1 > /dev/null 2>&1
ksk2=`$KEYGEN -K $dir -S $ksk1`
$SETTIME -K $dir -I +7mo $ksk1 > /dev/null 2>&1
zsk1=`$KEYGEN -K $dir -3 example.com`
# Test 2: ZSK goes inactive before successor is active
dir=02-zsk-inactive
rm -f $dir/K*.key
rm -f $dir/K*.private
zsk1=`$KEYGEN -K $dir -3 example.com`
$SETTIME -K $dir -I +9mo -D +1y $zsk1 > /dev/null 2>&1
zsk2=`$KEYGEN -K $dir -S $zsk1`
$SETTIME -K $dir -I +7mo $zsk1 > /dev/null 2>&1
ksk1=`$KEYGEN -K $dir -3fk example.com`
# Test 3: KSK is unpublished before its successor is published
dir=03-ksk-unpublished
rm -f $dir/K*.key
rm -f $dir/K*.private
ksk1=`$KEYGEN -K $dir -3fk example.com`
$SETTIME -K $dir -I +9mo -D +1y $ksk1 > /dev/null 2>&1
ksk2=`$KEYGEN -K $dir -S $ksk1`
$SETTIME -K $dir -D +6mo $ksk1 > /dev/null 2>&1
zsk1=`$KEYGEN -K $dir -3 example.com`
# Test 4: ZSK is unpublished before its successor is published
dir=04-zsk-unpublished
rm -f $dir/K*.key
rm -f $dir/K*.private
zsk1=`$KEYGEN -K $dir -3 example.com`
$SETTIME -K $dir -I +9mo -D +1y $zsk1 > /dev/null 2>&1
zsk2=`$KEYGEN -K $dir -S $zsk1`
$SETTIME -K $dir -D +6mo $zsk1 > /dev/null 2>&1
ksk1=`$KEYGEN -K $dir -3fk example.com`
# Test 5: KSK deleted and successor published before KSK is deactivated
# and successor activated.
dir=05-ksk-unpub-active
rm -f $dir/K*.key
rm -f $dir/K*.private
ksk1=`$KEYGEN -K $dir -3fk example.com`
$SETTIME -K $dir -I +9mo -D +8mo $ksk1 > /dev/null 2>&1
ksk2=`$KEYGEN -K $dir -S $ksk1`
zsk1=`$KEYGEN -K $dir -3 example.com`
# Test 6: ZSK deleted and successor published before ZSK is deactivated
# and successor activated.
dir=06-zsk-unpub-active
rm -f $dir/K*.key
rm -f $dir/K*.private
zsk1=`$KEYGEN -K $dir -3 example.com`
$SETTIME -K $dir -I +9mo -D +8mo $zsk1 > /dev/null 2>&1
zsk2=`$KEYGEN -K $dir -S $zsk1`
ksk1=`$KEYGEN -K $dir -3fk example.com`
# Test 7: KSK rolled with insufficient delay after prepublication.
dir=07-ksk-ttl
rm -f $dir/K*.key
rm -f $dir/K*.private
ksk1=`$KEYGEN -K $dir -3fk example.com`
$SETTIME -K $dir -I +9mo -D +1y $ksk1 > /dev/null 2>&1
ksk2=`$KEYGEN -K $dir -S $ksk1`
# allow only 1 day between publication and activation
$SETTIME -K $dir -P +269d $ksk2 > /dev/null 2>&1
zsk1=`$KEYGEN -K $dir -3 example.com`
# Test 8: ZSK rolled with insufficient delay after prepublication.
dir=08-zsk-ttl
rm -f $dir/K*.key
rm -f $dir/K*.private
zsk1=`$KEYGEN -K $dir -3 example.com`
$SETTIME -K $dir -I +9mo -D +1y $zsk1 > /dev/null 2>&1
zsk2=`$KEYGEN -K $dir -S $zsk1`
# allow only 1 day between publication and activation
$SETTIME -K $dir -P +269d $zsk2 > /dev/null 2>&1
ksk1=`$KEYGEN -K $dir -3fk example.com`
#!/bin/sh
# 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.
SYSTEMTESTTOP=..
. $SYSTEMTESTTOP/conf.sh
COVERAGE="$COVERAGE -c ./named-compilezone"
status=0
n=1
matchall () {
file=$1
echo "$2" | while read matchline; do
grep "$matchline" $file > /dev/null 2>&1 || {
echo "FAIL"
return
}
done
}
echo "I:checking for DNSSEC key coverage issues"
ret=0
for dir in [0-9][0-9]-*; do
ret=0
echo "I:$dir"
args= warn= error= ok= retcode= match=
. $dir/expect
$COVERAGE $args -K $dir example.com > coverage.$n 2>&1
# check that return code matches expectations
[ $? -eq $retcode ] || ret=1
# check for correct number of errors
found=`grep ERROR coverage.$n | wc -l`
[ $found -eq $error ] || ret=1
# check for correct number of warnings
found=`grep WARNING coverage.$n | wc -l`
[ $found -eq $warn ] || ret=1
# check for correct number of OKs
found=`grep "No errors found" coverage.$n | wc -l`
[ $found -eq $ok ] || ret=1
found=`matchall coverage.$n "$match"`
[ "$found" = "FAIL" ] && ret=1
n=`expr $n + 1`
if [ $ret != 0 ]; then echo "I:failed"; fi
status=`expr $status + $ret`
done
echo "I:exit status: $status"
exit $status
......@@ -1236,6 +1236,18 @@ israw1 signer/signer.out.7 || ret=1
if [ $ret != 0 ]; then echo "I:failed"; fi
status=`expr $status + $ret`
echo "I:checking dnssec-signzone output format ($n)"
ret=0
(
cd signer
$SIGNER -O full -f - -Sxt -o example example.db > signer.out.3 2>&1
$SIGNER -O text -f - -Sxt -o example example.db >