danectl

DNSSEC DANE implementation manager


What is danectl? | Supported Platforms | Documentation | Download

What is DANE?

DANE is DNS-based Authentication of Named Entities. It means securely letting the world know in advance what your public encryption keys are by publishing them as DNS records (TLSA SSHFP OPENPGPKEY SMIMEA) in your DNSSEC-enabled internet domain zone. This is the simplest and most secure way to let the world know what keys to expect when connecting to your servers. This can apply to TLS keys, SSH host keys, and OpenPGP and S/MIME keys. This makes it possible to prevent impersonation or man-in-the-middle attacks. It's mostly used with mail servers. Eventually, it could render certificate authorities unnecessary. DNSSEC has become very easy these days.

What is danectl?

Danectl is a DNSSEC DANE implementation manager. It uses certbot to create and manage pairs of keys for use with a TLSA 3 1 1 current + next workflow. It generates TLSA records for your TLS services for you to publish in the DNS, checks that they are correctly published, and performs key rollovers.

Danectl can also generate and check SSHFP records for the local SSH server.
Danectl can also generate and check an OPENPGPKEY record for a GnuPG key.
Danectl can also generate and check an SMIMEA record for an S/MIME certificate.

Danectl lets you create a pair of certbot certificate lineages to be used with DANE-aware TLS clients. They are referred to as the "original" and the "duplicate", or as the "current" and the "next".

    danectl new example.org www.example.org mail.example.org
    danectl dup example.org www.example.org mail.example.org

The current and next will repeatedly swap places between the original and the duplicate certificate lineages as the key rolls over from one to the other (with a new "next" key being created after each rollover).

If you already have a certbot certificate lineage that you want to use with DANE, then instead of creating both certificate lineages, you can adopt the existing one for DANE use, and then just create the duplicate.

    danectl adopt example.org
    danectl dup example.org www.example.org mail.example.org

After that, certbot automatically renews both certificates every few months, but the underlying keys won't change, and the TLSA records (see below) can remain stable.

You then configure danectl with the set of port/protocol/host combinations that you need TLSA records for.

    danectl add-tlsa example.org _443._tcp _443._tcp.www
    danectl add-tlsa example.org _25._tcp.mail
    danectl add-tlsa example.org _465._tcp.mail _587._tcp.mail
    danectl add-tlsa example.org _110._tcp.mail _143._tcp.mail
    danectl add-tlsa example.org _993._tcp.mail _995._tcp.mail
    danectl del-tlsa example.org _110._tcp.mail _143._tcp.mail

Danectl can then output the TLSA records, in BIND9 zonefile format, and you need to publish them in the DNS (somehow).

    danectl tlsa-current example.org
    danectl tlsa-next example.org

Danectl can then check that the TLSA records have been published in the DNS.

    danectl tlsa-check example.org

You also need to configure danectl with the list of TLS services that need to be reloaded when the key rolls over.

    danectl add-reload example.org apache2 postfix dovecot
    danectl del-reload example.org postfix

This is needed even when certbot is configured to do it with deploy hooks, because those hooks are only run when a certificate is renewed. Service reloads also need to happen when there's a DANE key rollover, and that doesn't necessarily happen at the same time as automatic certbot certificate renewals.

You then need to configure your TLS services to use the "current" certificate in /etc/letsencrypt/current, and then reload them. This is like following instructions for using a certbot certificate, but replacing "/etc/letsencrypt/live" with "/etc/letsencrypt/current".

    Left as an exercise for the reader

Periodically, you can perform key rollovers on a schedule that suits you (e.g., annually). An emergency key rollover is exactly the same.

    danectl rollover example.org

At any time, you can show the status (which certificate lineages are current, which are next, which new TLSA records are not yet published in the DNS, and which old TLSA records have not yet been remove from the DNS).

    danectl status

In addition to TLSA records, you can also generate SSHFP, OPENPGPKEY, and SMIMEA records, and check that they are published in the DNS.

    danectl sshfp example.org
    danectl sshfp-check example.org
    danectl openpgpkey user@example.org
    danectl openpgpkey-check user@example.org
    danectl smimea smimecert.pem
    danectl smimea-check smimecert.pem

For more information read the Documentation.

Supported Platforms

Danectl is written in Bourne shell, and should work on any platform that has the following prerequisites.

In all cases, danectl requires /bin/sh and host (or drill).

On systems like Solaris, /usr/xpg4/bin/sh is used instead of /bin/sh.

For TLSA usage, danectl also requires ls, sed, grep, readlink, certbot, openssl, sha256sum, and root privileges (for certbot).

For SSHFP usage, danectl also requires sed, perl and ssh-keygen.

For OPENPGPKEY usage, danectl also requires perl and gpg.

For SMIMEA usage, danectl also requires perl and openssl.

For non-ASCII domain names, danectl also requires GNU idn2.

The danectl-zonefile output adapter requires perl.

The danectl-nsupdate output adapter requires perl.

For reloading affected services on key rollover, any system with systemctl, service, rcctl, or service scripts in /etc/init.d, /etc/rc.d, or /usr/local/etc/rc.d should work (e.g., Linux, FreeBSD, NetBSD, OpenBSD, Solaris).

Documentation

There is a README file and manual entries:

README - Description, Install, Requirements
LICENSE - GNU General Public Licence Version 2
danectl(1) - DNSSEC DANE implementation manager (source)
danectl-zonefile(1) - Adapt danectl DNS RR output to modify BIND9 zonefiles (source)
danectl-nsupdate(1) - Adapt danectl DNS RR output for BIND9 nsupdate (source)

Download

Latest: danectl-0.8.4.tar.gz (SHA256 179730da7e8d7b68f62b92292b7bc883922fa5cb8361eba22666a1fa6886e10e)
     
Previous: danectl-0.8.2.tar.gz (SHA256 9eeb5e51f2447f2d62ee09e6e7b7a6ddce04c5a989172d23bb35a7b6142066b6)
danectl-0.8.2.tar.gz (SHA256 9eeb5e51f2447f2d62ee09e6e7b7a6ddce04c5a989172d23bb35a7b6142066b6)
danectl-0.8.1.tar.gz (SHA256 ace9fe35494365489a3546de343c74fef0ed250fa448a7c9884b6eb2463cae2f)
danectl-0.8.tar.gz (SHA256 c25118d13b92161ed7135a31f6bea8538006eaa369d61ec222b36478ff343742)
danectl-0.7.4.tar.gz (SHA256 bf0e98cf0d0b57b5bf28e5bc37455028d9197d70a1491cc7d789775bf87faf63)
danectl-0.7.3.tar.gz (SHA256 814938c870cf10b79a55ac6050318e70c6ae536a5c0e8699cdaeaddc9658f99f)
danectl-0.7.2.tar.gz (SHA256 79ceb965d37ef88688361c1620543d1f0cc83013c377319b787280953f76ac2e)
danectl-0.7.1.tar.gz (SHA256 1fbc3e8c6ae00f3519910308b510700e6e84006f72121d6fc35521cb79d1d6a3)
danectl-0.7.tar.gz (SHA256 b45d48371ada4371de0954f7cadb1ca648c36f198cc2eb72166e0342013bf130)
danectl-0.6.tar.gz (SHA256 4f7e64fb27b315489f58dbb2cf3ea344aceefd91f0bcf850a82ef9e67a9e60dc)
danectl-0.5.tar.gz (SHA256 62fc5dc331a0d4e38dc202b3467c0ae0fbb6d908ed9ce25b1a4729869cb6a73f)
danectl-0.4.1.tar.gz (SHA256 074d455683d5a85cf755926b26cd1d97703e666753afee682d87bc8df14d4299)
danectl-0.4.tar.gz (SHA256 8f7431d7dc0740224bef013c8fbf7829353448c589fe3a0de9dd763dda7cf23f)
danectl-0.3.2.tar.gz (SHA256 b1df9d906a31d0eb4c552991df33f02c9351738efa30e18626f8cb2287815917)
danectl-0.3.1.tar.gz (SHA256 a064fd103682156322b05b7ad0acf06d29e522774adfd8ec22b68d11d8408c76)
danectl-0.3.tar.gz (SHA256 c1c015d6e9db848f74e0e8395ed9d4a9683a3bbf4ef972479ab6732a2f762c97)
danectl-0.2.tar.gz (SHA256 f308f80f93146a26c10a7d25358c4c9c3ea00545a7f0051f7a29473bc0f44505)
danectl-0.1.tar.gz (SHA256 ed1de2edabff073331d406d82ed590968371e6a3bb402f6c73a2e8638ae2b4d4)

What is danectl? | Supported Platforms | Documentation | Download

Last modified by raf at Wed 19 Jul 2023 00:18:09 AEST
v