How to use Let's Encrypt DNS challenge validation?

Currently it is possible to perform a DNS validation also with the certbot LetsEncrypt client in the manual mode. Automation is also possible (see below).

Manual plugin

certbot -d bristol3.pki.enigmabridge.com --manual --preferred-challenges dns certonly

Certbot will then provide you an instructions to manually update a TXT record for the domain in order to proceed with the validation.

Please deploy a DNS TXT record under the name
_acme-challenge.bristol3.pki.enigmabridge.com with the following value:

667drNmQL3vX6bu8YZlgy0wKNBlCny8yrjF1lSaUndc

Once this is deployed,
Press ENTER to continue

Once you have updated DNS record, press Enter, certbot will continue and if LetsEncrypt CA verifies the challenge, certificate is issued as normally.

You may also use a command with more options to minimize interactivity and answering certbot questions. Note that manual plugin does not yet support non-interactive mode.

certbot --text --agree-tos --email you@example.com -d bristol3.pki.enigmabridge.com --manual --preferred-challenges dns --expand --renew-by-default  --manual-public-ip-logging-ok certonly

The renewal does not work with the manual plugin as it runs in non-interactive mode. More info at official Certbot documentation.

Update: manual hooks

In the new Certbot version you can use hooks, e.g. --manual-auth-hook, --manual-cleanup-hook. The hooks are external scripts executed by Certbot to perform the task.

Information is passed in environment variables - e.g., domain to validate, challenge token. Vars: CERTBOT_DOMAIN, CERTBOT_VALIDATION, CERTBOT_TOKEN.

certbot certonly --manual --preferred-challenges=dns --manual-auth-hook /path/to/dns/authenticator.sh --manual-cleanup-hook /path/to/dns/cleanup.sh -d secure.example.com

You can write your own handler or use already existing, there are many available, e.g., for Cloudflare DNS.

Automation, Renewal, Scripting

~~If you would like to automate DNS challenges validation it is not currently possible with vanila certbot.~~ Update: some automation is possible with the Certbot hooks.

We thus created a simple plugin that supports scripting with DNS automation. It's available as certbot-external-auth.

pip install certbot-external-auth

It supports DNS, HTTP, TLS-SNI validation methods. You can either use it in the handler mode or JSON output mode.

Handler mode

In the handler mode, the certbot + plugin calls external hooks (a program, shell script, python, ...) to perform the validation and installation. In practice you write a simple handler/shell script which gets input arguments - domain, token and makes the change in DNS. When handler finishes, certbot proceeds with validation as usual.

Handler mode is also compatible with Dehydrated DNS hooks (former letsencrypt.sh). There are already many DNS hooks for common providers (e.g., CloudFlare, GoDaddy, AWS). In the repository there is a README with extensive examples and example handlers.

certbot \
    --text --agree-tos --email you@example.com \
    --expand --renew-by-default \
    --configurator certbot-external-auth:out \
    --certbot-external-auth:out-public-ip-logging-ok \
    -d "bristol3.pki.enigmabridge.com" \
    --preferred-challenges dns \
    --certbot-external-auth:out-handler ./dehydrated-example.sh \
    --certbot-external-auth:out-dehydrated-dns \
    run

JSON mode

Another plugin mode is JSON mode. It produces one JSON object per line. This enables a more complicated integration - e.g., Ansible or some deployment manager is calling certbot. Communication is performed via STDOUT and STDIN. Cerbot produces JSON object with data to perform the validation, e.g.,

certbot \
    --text --agree-tos --email you@example.com \
    --expand --renew-by-default \
    --configurator certbot-external-auth:out \
    --certbot-external-auth:out-public-ip-logging-ok \
    -d "bristol3.pki.enigmabridge.com" \
    --preferred-challenges dns \
    certonly 2>/dev/null

{"cmd": "perform_challenge", "type": "dns-01", "domain": "bs3.pki.enigmabridge.com", "token": "3gJ87yANDpmuuKVL2ktfQ0_qURQ3mN0IfqgbTU_AGS4", "validation": "ejEDZXYEeYHUxqBAiX4csh8GKkeVX7utK6BBOBshZ1Y", "txt_domain": "_acme-challenge.bs3.pki.enigmabridge.com", "key_auth": "3gJ87yANDpmuuKVL2ktfQ0_qURQ3mN0IfqgbTU_AGS4.tRQM98JsABZRm5-NiotcgD212RAUPPbyeDP30Ob_7-0"}

Once DNS is updated, caller sends new-line character to STDIN of the certbot to signalize it can continue with validation.

This enables automation and certificate management from the central management server. For installation you can deploy certificates over SSH.

For more info please refer to the readme and examples on certbot-external-auth GitHub.