DNS Validated Let's Encrypt Certificates

Introduction

In order to help users encrypt traffic to your server, you need a valid TLS/SSL certificate. Let's Encrypt is an organization which issues such certificates for free. However, you have to prove ownership over the domain, for which you want the certificate. This tutorial guides you through getting a wildcard certificate for your domain, while using the Hetzner DNS service and its API.

With Let's Encrypt, there are different types of challenges to prove that you own the domain (see "Challenge Types)". This tutorial uses the DNS-01 challenge, which requires you to create a new DNS entry called _acme-challenge.example.com. You could create this DNS entry manually. However, we will use scripts that automatically create and delete the DNS entry for us.

The route this tutorial takes is one of many. Depending on your personal preference you may also like to take a look at this project:

github.com/ctrlaltcoop/certbot-dns-hetzner

Prerequisites

You need the following things to get started:

• A server
• A domain: <example.com>
• Your Domain is set up to use the Hetzner DNS service

  Not covered here, but if you have your domain with another provider, you can follow the first two steps in this tutorial.

This tutorial assumes you are using Ubuntu 24.04, however this should also work on other Linux systems.

Step 1 - Install Dependencies

We will make use of curl, jq and certbot. You need to install those:

sudo apt update
sudo apt install curl jq certbot

Additionally we also need some glue between certbot and Hetzner's DNS API:

curl https://raw.githubusercontent.com/dschoeffm/hetzner-dns-certbot/master/certbot-hetzner-auth.sh | sudo tee /usr/local/bin/certbot-hetzner-auth.sh
curl https://raw.githubusercontent.com/dschoeffm/hetzner-dns-certbot/master/certbot-hetzner-cleanup.sh | sudo tee /usr/local/bin/certbot-hetzner-cleanup.sh
sudo chmod +x /usr/local/bin/certbot-hetzner-auth.sh
sudo chmod +x /usr/local/bin/certbot-hetzner-cleanup.sh

Step 2 - Acquire API Token

In order to talk to the Hetzner DNS API, we need an authorization token. You can create one on the Hetzner DNS website:

dns.hetzner.com/settings/api-token

For this tutorial, we will assume the token is:

LlGoDUQ39S6akqoav5meAsv5OIpeywhj

Save the token to /etc/hetzner-dns-token:

echo LlGoDUQ39S6akqoav5meAsv5OIpeywhj > /etc/hetzner-dns-token

Step 3 - Get Certificate

At this point, we can request a certificate from Let's Encrypt:

Replace <example.com> with your own domain.

sudo certbot certonly --manual --preferred-challenges=dns --manual-auth-hook /usr/local/bin/certbot-hetzner-auth.sh --manual-cleanup-hook /usr/local/bin/certbot-hetzner-cleanup.sh -d <example.com> -d *.<example.com>

Step 4 - Install Certificate

After having acquired a freshly baked TLS/SSL certificate, you will also want to put it to use. For example in a web server, or a mail server. This however is not covered here.

Conclusion

We created a Hetzner DNS API token and used domain validation to request a wildcard certificate, which covers the domain, as well as all subdomains.

License: MIT