NAME

danectl - DNSSEC DANE implementation manager

SYNOPSIS

 usage: danectl [options] command [arg...]

 options:
  -h, --help                             - Show the usage message
  -V, --version                          - Show the name and version
  -v, --verbose                          - Verbose mode (announce actions)
  -q, --quiet                            - Quiet mode (pass -q to certbot)
  -n, --test                             - Test mode (don't change things)

 commands:
  help                                   - Show the manual page
  aliases                                - Show the command aliases

  certbot <options...>                   - Supply certbot command line options
  adopt <certname...>                    - Adopt an existing cert as current
  new <domain...>                        - Create a new original/current cert
  dup <domain...>                        - Create a new duplicate/next cert
  add-tlsa <certname> <_#._tcp[.host]..> - Add port/pro/host for TLSA output
  del-tlsa <certname> <_#._tcp[.host]..> - Delete port/pro/host for TLSA output
  show-tlsa <certname>                   - Show port/pro/host for TLSA output
  tlsa-current <certname...>             - Output TLSA RRs for the current key
  tlsa-next <certname...>                - Output TLSA RRs for the next key
  tlsa-check [<certname...>]             - Check that TLSA RRs are published
  add-reload <certname> <service...>     - Add services to reload on rollover
  del-reload <certname> <service...>     - Delete services to reload on rollover
  show-reload <certname>                 - Show services to reload on rollover
  reload <certname...>                   - Reload affected services
  rollover <certname...>                 - Perform a key rollover
  status                                 - Show current/next status

  sshfp <domain>                         - Output SSHFP RRs for localhost
  sshfp-check <domain>                   - Check that SSHFP RRs are published
  openpgpkey <emailaddress>              - Output OPENPGPKEY RR for an email
  openpgpkey-check <emailaddress>        - Check OPENPGPKEY RR is published
  smimea <smimecert.pem>                 - Output SMIMEA RR for a certificate
  smimea-check <smimecert.pem>           - Check SMIMEA RR is published

INTRODUCTION

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 to 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.

DESCRIPTION

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". The current and next will repeatedly swap places between the original and the duplicate 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.

After that, certbot automatically renews both certificates every few months, but the underlying keypairs 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 can then output the TLSA records, in zonefile format, and you need to publish them to the DNS (somehow). Danectl can then check that the TLSA records have been published to the DNS.

You also need to configure danectl with the list of TLS services that need to be reloaded when the key rolls over. 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/<cert-name>, and then reload them. This is like following instructions for using a certbot certificate, but replacing "live" with "current".

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

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

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

OPTIONS

-h, --help

This outputs danectl's usage message, then exits.

-V, --version

This outputs danectl's name and version, then exits.

-v, --verbose

This enables verbose mode, causing danectl to print actions before performing them.

-q, --quiet

This enables quiet mode, causing danectl to pass -q to certbot. This only affects the "new", "dup", and "rollover" commands, and is probably a good idea, as it makes the output tidier.

-n, --test

This enables test mode, preventing danectl from performing any changes. It implies verbose mode, causing danectl to print the actions that would have been performed.

COMMANDS

Danectl can show you this manual page:

  danectl help

You can also show the aliases for all of the commands:

  danectl aliases

Before you can use danectl to do anything interesting, you might need to supply any command line options that certbot will need when it creates new certificate lineages. This is for authentication and installation. The default is "--apache" to use the Apache plugin. Don't use quotes and don't put spaces inside arguments. It won't end well.

  danectl certbot --apache

The "certbot" command modifies your ~/.danectlrc file.

If you already have a certbot certificate lineage, you can adopt it for DANE use:

  danectl adopt example.org

Note that you must use the cert-name, not the list of certified domains. To see all of your cert-names, run "certbot certificates", or look in /etc/letsencrypt/live.

This will create a symlink in /etc/letsencrypt/current to the adopted certificate lineage.

If you want to create a new certbot certificate lineage for DANE use instead:

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

Note that you must provide the complete list of domain names to certify. The cert-name of the new certificate lineage will be the first domain in the list.

This will create a symlink in /etc/letsencrypt/current to the new certificate lineage.

Either way, you then need to create an additional duplicate certificate lineage for the same set of domains:

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

Note that you must provide the complete list of domain names to certify. It must be identical to the list of domains in the adopted or new original certificate lineage. The cert-name will be the first domain in the list followed by "-duplicate". You won't need to use that suffix with danectl, but you will need to use it when using certbot directly.

This will create a symlink in /etc/letsencrypt/next to the duplicate certificate lineage.

Once a pair of certificate lineages is set up, certbot will automatically renew them both, but the underlying keypairs won't change. That means that the TLSA records (see below) can remain stable for longer than just a few months.

Most of the remaining commands below require the base cert-name as their first argument. Not the list of domain names, just the first domain, or cert-name, without any "-duplicate" suffix.

To specify the port/protocol/host combinations that you will want TLSA records for:

  danectl add-tlsa example.org _443._tcp _443._tcp.www
  danectl add-tlsa example.org _25._tcp.mail _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

Do not include the base cert-name in the port/protocol/host combinations. That will be included automatically.

They can also be removed:

  danectl del-tlsa example.org _110._tcp.mail _143._tcp.mail

The "add-tlsa" and "del-tlsa" commands modify your ~/.danectlrc file.

You can also show which port/protocol/host combinations will be included for TLSA records:

  danectl show-tlsa example.org

To output all TLSA records for the current key:

  danectl tlsa-current example.org

To output all TLSA records for the next key:

  danectl tlsa-next example.org

Initially, you need to publish the TLSA records for both the current and next keys in the DNS (somehow).

To check that all TLSA records for the current and next keys are correctly published in the DNS:

  danectl tlsa-check example.org

If no cert-name is supplied, then all cert-names are checked.

All TLSA records for the current and next keys must be published in the DNS before you configure your services to use the current key.

To specify the services that need to be reloaded when a key rolls over:

  danectl add-reload example.org apache2 postfix dovecot

They can also be removed:

  danectl del-reload example.org postfix # Postfix can look after itself :-)

The "add-reload" and "del-reload" commands modify your ~/.danectlrc file.

You can also show which services will be reloaded:

  danectl show-reload example.org

At any point, you can reload the services that need to be reloaded when the key rolls over:

  danectl reload example.org

But this shouldn't be necessary. It's automatic when a key rolls over. Although it might be useful in certbot renewal hooks.

Occasionally (e.g. annually), perform a key rollover:

  danectl rollover example.org

This will redesignate the next key as the current key (and vice versa), reload affected services, and create a new keypair/certificate as the new next key. It also outputs the old TLSA records for the old current key that you need to remove from the DNS (somehow). And it outputs the new TLSA records for the new next key that you need to publish in the DNS (somehow).

At any time, you can show the status of all certificate pairs:

  danectl status

This will show, for each base cert-name, which certificate lineage is current (original or duplicate), and which is next. It will also show any new TLSA records that should be, but are not, published in the DNS. It will also show any old TLSA records that are published in the DNS, but should no longer be.

If any of the symlinks in /etc/letsencrypt/{current,next} target certificate lineages that no longer exist in /etc/letsencrypt/live, this is also mentioned, and they are deleted. This indicates that the certificate lineage was previously deleted with certbot.

You can also output SSHFP records for the local SSH server:

  danectl sshfp example.org

If you want to authorize your local SSH server's host keys to clients via DNSSEC, you will need to publish these SSHFP records in the DNS (somehow). You will also need to set VerifyHostKeyDNS to "yes" or "ask" in the ssh client configuration.

To check that SSHFP records for the local SSH server are published in the DNS:

  danectl sshfp-check example.org

You can also output an OPENPGPKEY record for the key that is associated with an email address in your GnuPG public keyring:

  danectl openpgpkey user@example.org

The email address must be a valid argument for gpg's --export operation. If you want your correspondents to find the key, you will need to publish the OPENPGPKEY record in the DNS (somehow), and they will need to add "dane" to their auto-key-locate list.

To check that the OPENPGPKEY record for the email address is published in the DNS:

  danectl openpgpkey-check user@example.org

You can also output an SMIMEA record for an S/MIME certificate:

  danectl smimea smimecert.pem

The S/MIME certificate file must be in PEM format. If you want your correspondents to find the certificate, you will need to publish the SMIMEA record in the DNS (somehow), and they will probably need to consult their mail client documentation.

To check that the SMIMEA record for an S/MIME certificate is published in the DNS:

  danectl smimea-check smimecert.pem

FILES

  /etc/letsencrypt/live    - Certbot certificate lineages
  /etc/letsencrypt/current - Current keypairs/certificates
  /etc/letsencrypt/next    - Next keypairs/certificates
  ~/.danectlrc             - Configuration file

The ~/.danectlrc configuration file is technically a shell script. But danectl's additions and removals are purely a single name="value" line at a time. Bear that in mind if you modify it manually.

CAVEAT

If you need to add or remove any domains from a pair of certificate lineages, you will need to do it with certbot, and you will need to do it for both the original and the duplicate certificate lineages (e.g. example.org and example.org-duplicate), and you will need to use certbot's --cert-name command line option. Since there will be two certificate lineages with the same set of domains, it would be ambiguous otherwise. Perhaps danectl should be able to do this, but it doesn't. There may be other things that you will need to use certbot directly for. Keep things in sync.

BUGS

Danectl relies entirely on certbot. This isn't a bug. It's a choice. This choice was made so as to make danectl easy to implement, and because it's pragmatic. The same key can be used with DANE-aware or PKIX-aware clients. You don't need to know which. And you don't need to exclude any clients.

But it means that it only works with keys that are created by certbot, and with certificates that are issued by a Certificate Authority (CA). If you want to use DANE so as to avoid the CA ecosystem entirely, danectl won't help you do that.

On the other hand, only a single CA is involved, LetsEncrypt, not the entire ecosystem, and danectl only generates TLSA 3 1 1 records, which only refer to the local public key itself. There is no reliance on any keys belonging to the CA. That's good because those keys can and will change on a schedule that is beyond your control. But your own keys are under your control.

So danectl is opinionated and inflexible. Other things can be done with TLSA records, but they can't be done with danectl. But what can be done with danectl can be done easily. If you need greater flexibility, you'll need to find it elsewhere.

For OPENPGPKEY usage, if your public keyring contains multiple keys with the same email address keyid, danectl will only output the first one that gpg exports. Let me know if this is a problem.

For SMIMEA usage, only SMIMEA 3 0 0 records are supported. This isn't really a bug, as they seem to be the most/only useful ones.

Danectl doesn't actually publish or remove any DNS records for you. This isn't really a bug. It's a limitation. There are too many ways to publish records to the DNS. But danectl does try to make it easy for you to handle that yourself by outputting records in the well-known Bind9 zonefile format. When performing a key rollover, and when performing any of the checks, any superfluous records that are to be removed are output in the form of comments where the leading semicolon (";") is not followed by a space (" "). That makes them easy to identify with grep (i.e. grep "^;[^ ]" for superfluous records to be removed, and grep -v "^;[^ ]" for missing records to be published). Perhaps a plugin system could be added to automate updates for different DNS server software and different DNS service providers, but it should be easy enough to write a separate script to read the output of danectl and do what you need with it. And anyway, DANE-related DNS updates probably won't be frequent enough for their automation to be important. But of course, your mileage may vary.

REQUIREMENTS

For TLSA usage, danectl requires /bin/sh, ls, sed, grep, host, readlink, certbot, openssl, sha256sum, and root privileges.

For SSHFP usage, danectl requires /bin/sh, sed, host, perl, and ssh-keygen.

For OPENPGPKEY usage, danectl requires /bin/sh, perl, and gpg.

For SMIMEA usage, danectl requires /bin/sh, perl, and openssl.

LICENSE

Danectl is released under the terms of the GPLv2+ https://www.gnu.org/licenses.

SEE ALSO

certbot(1), danebot(1), ssh(1), ssh_config(5), gpg(1), openssl(1), RFC6698, RFC7671, RFC7672, RFC4255, RFC7929, RFC8162.

AUTHOR

20210906 raf <raf@raf.org>

URL

  https://raf.org/danectl
  https://github.com/raforg/danectl