northox/dnssec-reverb

Automate DNSSEC key rotation for both ZSK KSK

dnssec-reverb

Shell script based DNSSEC key management tool

I was looking for something that would take care of the rotation of my DNSSEC keys that wouldn't require many dependencies, was simple to manage and that I could actually trust - easily auditable. I found an unmaintained script called dnsseczonetool from @kfujiwara and refactor it to fit my needs. It is used and tested on OpenBSD but should work pretty much anywhere with the proper paths.

Reverb is straightforward and couldn't be more trustable/easy to audit. Enjoy!

Release notes

• CAUTION the latest release changed the serial special tag from '_SERIAL_' to '00001111' to ensure named/nsd compatibility. Update your master zone.

Features

• Supports nsd and bind servers
• Supports ldns and bind's dnssec tools
• Should run on any unix-like systems™
• Don't trust me, audit the code!™
• KISS®
• auto increment of the serial (date format)

Requirements

• nsd or bind
• ldns from NLnet labs or bind's DNSSEC tools
• standard unix tools such as sed & awk

Installation

1. Copy dnssec-reverb in a directory in your $PATH.

   $ sudo cp dnssec-reverb /usr/local/sbin/

2. Create a configuration file. The config file will be searched in the following order 1) by looking at the $DNSSEC_REVERB_CONF environment variable, 2) within the same directory than the script (dirname $0), 3) within /etc/ and finally 4) within /usr/local/etc/. At the very least it must specify the master zone file directory using the MASTERDIR variable. Optionnaly, specific domain parameters can be set - see the configuration section.

   echo MASTERDIR="/var/nsd/zones/master" >> /etc/dnssec-reverb.conf
   echo ZSK_PARAM_example.org="-a RSASHA1-NSEC3-SHA1" >> /etc/dnssec-reverb.conf
   

3. Prepare the traditional zone files and set the serial to this special tag: 00001111. We use a number to keep named checkzone compatibility. The file name should be equal to the zone name.

   $ grep serial example.org
   @ IN SOA ns1.example.org. dnsmaster.example.org. (
   00001111   ; serial
   1h         ; refresh (1 hours)
   1h         ; retry (1 hour)
   5w         ; expire (4 weeks)
   30m        ; minimum (30 minutes)
   

4. Edit nsd.conf to load the signed zone file:

   zone "example.org" {
       type master;
       file "/var/nsd/zones/master/example.org.signed";
   }
   

5. Generate first key and sign zone:

   dnssec-reverb keygen example.org
   dnssec-reverb sign example.org
   

You can validate your DNSSEC setup using this web app: http://dnsviz.net/d/mantor.org/dnssec/

Configuration

To override the default configuration (as describe below in parentheses), simply edit dnssec-reverb.conf.

Paths | default value:

• MASTERDIR: Master zone file directory | mandatory - no default
• DBDIR: directory used to store state and data | $MASTERDIR/dnssec-reverb-db
• keygen: ldns-keygen path | $(which ldns-keygen)
• signzone: ldns-signzone path | $(which ldns-signzone)
• key2ds: ldns-key2ds path | $(which ldns-key2ds)
• checkzone: nsd-checkzone path | $(which nsd-checkzone)
• control: nsd-control path | $(which nsd-control)
• RELOAD_COMMAND: reload command | (echo -n 'reload is '; $control reload) && (echo -n 'notify is '; $control notify)

Params - default value:

• KSK_PARAM: keygen's options for KSK | '-a ECDSAP256SHA256 -k'
• ZSK_PARAM: keygen's options for ZSK | '-a ECDSAP256SHA256'
• SIGN_PARAM: signzone options | '-n' (NSEC3)
• DS_PARAM: key2ds or dsfromkey options | '-2' (SHA256)

Signatures expiration:

• EXPIRE_DAYS: used to calculate the expiration date of the signatures to this date. Defaults to 33.

The previous configuration set can be overridden by zone by simply adding "_$zone" at the end of the variable. For example: ZSK_PARAM_example.org="-a RSASHA1-NSEC3-SHA1" to change the cipher for example.org's keys only. All zone name must be lowercase. Zone whose name contains '.' and '-' characters are replaced by '_'.

Usage

$ dnssec-reverb
usage: dnssec-reverb keygen <zone>
       dnssec-reverb rmkeys <zone>
       dnssec-reverb [-s] ksk-add <zone>
       dnssec-reverb [-s] ksk-roll <zone>
       dnssec-reverb [-s] zsk-add <zone>
       dnssec-reverb [-s] zsk-roll <zone>
       dnssec-reverb [-s] zsk-rmold <zone>
       dnssec-reverb sign <zone>
       dnssec-reverb status <zone>

Initial setup - assuming your zone has no DNSSEC keys published

1. Generate KSK and ZSK.

   dnssec-reverb keygen example.org

2. Retrieve your fresh KSK's digest and setup the DS at your registrar.

   dnssec-reverb status example.org

3. Sign zone using keys generated in step #1.

   dnssec-reverb sign example.org

Rollover of the KSK

Manual

1. Add and publish an additional but not valid/signed KSK. After this operation you will have two KSK, one active/signed by your registrar and a new one not active/signed.

   dnssec-reverb --sign ksk-add example.org

2. After allowing some time for propagation use the information provided by the status command to change the valid KSK within the DNSSEC interface of your domain registrar. You'll need the id, type of algo, type of hash and the digest of the active KSK.

   # dnssec-reverb status example.org
   example.org -- https://dnsviz.net/d/example.org/dnssec/
     type state  id    algo hash (expiration)        (digest)
     KSK  active 60742 13    2   set w/ registrar    53cf303e75669063c34e1f4a75bfffbbad45bd202d24f3899ccb7cf9a8b502b6
     ZSK  active 06178 13    2   2020/11/28 04:32:05
          next   43617 13    2   2020/11/28 04:32:05
   

3. After allowing some time for propagation, roll our the new KSK and remove the old one.

   dnssec-reverb ksk-roll example.org

Automated

1. Set something similar in your crontab. It will automatically add a new KSK and - assuming your email are setup correctly - send an email when you need to take action with your registrar. Optionally, you could replace the later with a script calling your registrar API to complete the rollover automagically.

0	0	1	dec		*   dessec-reverb ksk-add example.org
0	0	1	jan		*   dessec-reverb ksk-roll example.org

Rollover of the ZSK

Manual

1. Add and publish an additional and valid/signed ZSK. After this operation you will have two active ZSK.

   dnssec-reverb --sign zsk-add example.org

2. After allowing some time for the propagation you are ready to remove the old ZSK.

   dnssec-reverb -s zsk-roll example.org

3. Remove the old ZSK from reverb active records

   dnssec-reverb zsk-rmold example.org
dnssec-reverb sign example.org

Automated

Set something similar in your crontab. It will roll the ZSK at a 3 months interval by adding the new ZSK one month before publishing it and removing the old a month later.

0       6       1       jan,apr,jul,oct *   dnssec-reverb -s zsk-add example.org
0       6       1       feb,may,aug,nov *   dnssec-reverb -s zsk-roll example.org
0       6       1       mar,jun,sep,dec *   dnssec-reverb -s zsk-rmold example.org

License

Simplified BSD

Source

https://github.com/northox/dnssec-reverb

Acknowledgements

This code is heavily based on @kfujiwara work's.

Author(s)

Danny Fullerton - Mantor Organization
@kfujiwara

dnssec-reverb's Issues

ubuntu sh is not handling [[

Hello,

Ubuntu 22.04 is not handling [[ for /bin/sh. I suggest to use /bin/bash

root@ns01:/srv/dnssec# ./dnssec-reverb sign  64.57.2.in-addr.arpa
./dnssec-reverb: 157: [[: not found
zone 64.57.2.in-addr.arpa is ok
date: 1685813497: No such file or directory

dnssec-reverb/dnssec-reverb

Line 157 in 9aa8e24

if [[ $signzone = *'dnssec-signzone' ]]; then # if bind

Some ideas from Linda Lapinlampi

• Remove configuration (maybe, simplifies the script)
• Make shell commands in install instructions consistent (the dollar sign should
  only be displayed when there's output)
• Fix typo /vas/nsd to /var/nsd
• Add more Markdown code elements to where it's sensible
• Replace (potentially dangerous) $ZONEFILE.tmp and $tmpfile with mktemp(1) (the
  latter is not POSIX-portable in shell)
• Once ED25519 support is added to ldns, switch to that by default
• Change all cases of rm $LOCKF to rm -f $LOCKF, and others
• Replace SERIAL with some pseudo-serial number usable by NSD in non-signed
  zones?
• umask 077 where applicable
• Add a manual page (mdoc language)

`Keygen` option can't be used for a new domain

Hi,

for a new domain:

ns1# dnssec-reverb keygen example.com
dnssec-reverb: zone does not exist

The issue seems to be here:

dnssec-reverb/dnssec-reverb

Line 273 in 6fbb297

if [ ! -s "$KSK_CUR_FILE" ]; then

If I understand correctly this file does not exist yet and keygen option would create one.

Is this check necessary? It looks like some of the options check for files existence on their own.
Or alternatively:

        if [ ! -s "$KSK_CUR_FILE" ] && [[ $CMD != "keygen" ]]; then
                Fatal "zone does not exist"
        fi

named-checkzone

named-checkzone actually check the non signed zone and print an error (due to SERIAL, which is not valid)

`status` does not show KSK digest

Added domain by: dnssec-reverb keygen example.com

Status output is missing digest:

ns1# dnssec-reverb status example.com                                                                                    
example.com -- https://dnsviz.net/d/example.com/dnssec/
 type state  id    algo hash (expiration)        (digest)
 KSK  active                 set w/ registrar    
 ZSK  active 53113 14    2   2021/09/29 12:01:42

My config in /etc/dnssec-reverb.conf:

MASTERDIR="/var/nsd/zones/master"

KEYGEN_CMD="$(which ldns-keygen)"
SIGNZONE_CMD="$(which ldns-signzone)"
KEY2DS_CMD="$(which ldns-key2ds)"
CHECKZONE_CMD="$(which nsd-checkzone)"
CONTROL_CMD="$(which nsd-control)"
RELOAD_CMD="(echo -n 'reload is '; $CONTROL_CMD reload) && (echo -n 'notify is '; $CONTROL_CMD notify)"

# https://tools.ietf.org/id/draft-ietf-dnsop-algorithm-update-01.html

KSK_PARAM="-a ECDSAP384SHA384 -k"
ZSK_PARAM="-a ECDSAP384SHA384"
SIGN_PARAM="-n" # -n = use NSEC3
DS_HASH="2" # 1=SHA1 2=SHA256 3=GOST 4=SHA384
DS_PARAM="-$DS_HASH"

EXPIRE_DAYS="33"

It appears that this line (173 and 176) is not correct:

	$KEY2DS_CMD "$_DS_PARAM" "$KEYDIR/$(cat "$KSK_CUR_FILE").key" | \
		awk '{printf (" KSK  active %5s %2s   %2s   set w/ registrar    %s\n", $5, $6, $7, $8)}'

ldns-key2ds returns filename according to it's manual:

ldns-key2ds is used to transform a public DNSKEY RR to a DS RR. When run it will read file with a DNSKEY RR in it and it will create a .ds file with the DS RR in it.

It prints out the basename for this file (K<name>+<alg>+<id>).

so I don't understand what should be the input of the awk command.

Not quite clear where the config goes.

Default MASTERDIR should be for obvious

Maybe for a default config with all defaults in comments?

Config file for bind

Hi,
I don't fully understand situation that I am in.

Error on triggering command : dnssec-reverb: cannot find $KEYZONE_CMD

dnssec-reverb.conf:
_keygen="$(which dnssec-keygen)"
signzone="$(which dnssec-signzone)"
key2ds="$(which dnssec-dsfromkey)"
checkzone="$(which named-checkzone)"
control="$(which rndc)"

KSK_PARAM="-n zone -a ECDSAP256SHA256 -f ksk"
ZSK_PARAM="-n zone -a ECDSAP256SHA256 "
SIGN_PARAM="-N increment"
DS_PARAM="-2"_

this early part of script should load config variables :
CONF="dnssec-reverb.conf"
if [ -r "$DNSSEC_REVERB_CONF/$CONF" ]; then
CONF="$DNSSEC_REVERB_CONF/$CONF"
elif [ -r "$DIR/$CONF" ]; then
CONF="${DIR}/$CONF"
elif [ -r "/etc/$CONF" ]; then
CONF="/etc/$CONF"
elif [ -r "/usr/local/etc/$CONF" ]; then
CONF="/usr/local/etc/$CONF"
else
Fatal "cannot find config file"
fi
. "$CONF"

I suppose its done, but it gets Fatal right on first check.
[ "$KEYGEN_CMD" = "" ] && Fatal "cannot find \$KEYZONE_CMD"

There is no KEYGEN_CMD variable in default config. Am I missing something ?
I suppose "keygen" in config file should be KEYGEN_CMD no?

Thanks for clarifying. BR!

time value is invalid

hello
got an error on debian using your script

dnssec-signzone: fatal: time value 1540731882 is invalid

i read the docs and it is said: If no end-time is specified, 30 days from the start time is used as a default.
so maybe we can remove it ?

serial for each zone, not global one

the serial number is global for all zones.
It would be good to have serial counter based on the domain name

I have quite a lot of zone to sign, so this feature would be usefull for me.

I could try to provide also patch f interested.

generate DS line into the file

I have several nested zones, like

• example.org
• test.example.org
• dev.example.org
• ...

It would be good to generate DS file for for the zone, so I could only do $INCLUDE into master zone.

date is expecting reference file

Hello,

the date -r is expecting reference file.
I have got error

root@ns01:/srv/dnssec# bash ./dnssec-reverb sign  64.57.2.in-addr.arpa
zone 64.57.2.in-addr.arpa is ok
date: 1685813368: No such file or directory

dnssec-reverb/dnssec-reverb

Line 163 in 9aa8e24

TT=$EXPIRE; date -r "$TT" '+%Y/%m/%d %H:%M:%S' > "$KEYDIR/$ZSK.expire"

regards
hudecof