Automatically Renew Wildcard Certificates

Scripts for the automated DNS validation of Let's Encrypt certificates

Tags: Certificates Encryption SSL

Let's Encrypt certificates with DNS validation can only be automatically issued and renewed if the DNS provider facilitates an API. If this is not the case, one can use the name servers of deSEC and their API.

Another article in this blog described how to use the certbot program to issue and renew wildcard certificates from Let's Encrypt. Wildcard certificates can only be issued using "DNS Challenge", whereby the certbot program receives a token (the "Challenge") from Let's Encrypt, which must be created in a TXT record of the subdomain _acme-challenge of the relevant domain in the DNS so that it can be verified there by Let's Encrypt.

certbot is able to create this TXT record via so-called pre- and post-validation hooks and delete it again after verification - provided the DNS provider offers a corresponding API. If this is not the case, the TXT record must be created and removed interactively, which prevents the certificate from being automatically renewed.

This article shows how the deSEC API can be used to carry out a DNS challenge. The prerequisite for this is that the domain registrar has the option of using external name servers, because no domains can be registered via deSEC.

Preliminary Work

A deSEC account is required, but it is free. This account can be used to create up to 15 domains to manage their DNS entries.

The first step after creating an account with deSEC is to create the domain name in question there and to enter the deSEC name servers (ns1.desec.io and ns2.desec.org) with the registrar of the domain.

Next, an access token must be created for the deSEC account, which is required for access to the API. This can be done on the deSEC website.

Creation of a TXT record

A TXT record can be created using the following call with curl:

curl \
 -H "Authorization: Token TOKEN" \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \
 -X PUT \
 https://desec.io/api/v1/domains/DOMAIN/rrsets/ \
 -d '[{"subname":"_acme-challenge","type":"TXT","records":["\"CHALLENGE\""],"ttl":"3600"}]'

Note that the placeholders TOKEN, DOMAIN, and CHALLENGE must be replaced by the corresponding actual values.

When called via a script that is passed to the certbot program as parameter --manual-auth-hook, the values for DOMAIN and CHALLENGE are exported by certbot as environment variables CERTBOT_DOMAIN and CERTBOT_VALIDATION and can therefore be used within the script.

Such a script can be downloaded from this Git repository (desec_auth_hook.sh).

Removal of a TXT record

After the TXT entry has been successfully validated by Let's Encrypt, it can be removed again.

When called by certbot, the parameter --manual-cleanup-hook is used for this, to which a script can be passed that essentially has to contain the same curl call, but with an empty value for records:

curl \
 -H "Authorization: Token TOKEN" \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \
 -X PUT \
 https://desec.io/api/v1/domains/DOMAIN/rrsets/ \
 -d '[{"subname":"_acme-challenge","type":"TXT","records":[],"ttl":"3600"}]'

Such a script can also be downloaded from this Git repository (desec_cleanup_hook.sh).

Top