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 in Hetzner Console 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 in Hetzner Console

  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 API:

Source of files: github.com/dschoeffm/hetzner-dns-certbot

• /usr/local/bin/certbot-hetzner-auth.sh

  #!/bin/bash
  
  token="$(cat /etc/hetzner-dns-token)"
  
  domain_name="$( echo $CERTBOT_DOMAIN | rev | cut -d'.' -f 1,2 | rev)"
  subdomain=".${CERTBOT_DOMAIN%.$domain_name}"
  if [ "$CERTBOT_DOMAIN" = "$domain_name" ]; then
    subdomain=""
  fi
  
  # Create TXT record for DNS-01 challenge
  curl "https://api.hetzner.cloud/v1/zones/${domain_name}/rrsets" \
    -X POST \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"_acme-challenge${subdomain}\",
      \"type\": \"TXT\",
      \"ttl\":300,
      \"records\":[{\"value\":\"\\\"${CERTBOT_VALIDATION}\\\"\"}] }" > /dev/null 2>/dev/null
  
  # just make sure we sleep for a while (this should be a dig poll loop)
  sleep 30

• /usr/local/bin/certbot-hetzner-cleanup.sh

  #!/bin/bash
  
  token="$(cat /etc/hetzner-dns-token)"
  
  domain_name="$( echo $CERTBOT_DOMAIN | rev | cut -d'.' -f 1,2 | rev)"
  subdomain=".${CERTBOT_DOMAIN%.$domain_name}"
  if [ "$CERTBOT_DOMAIN" = "$domain_name" ]; then
    subdomain=""
  fi
  
  curl "https://api.hetzner.cloud/v1/zones/${domain_name}/rrsets/_acme-challenge${subdomain}/TXT" \
    -X "DELETE" \
    -H "Authorization: Bearer ${token}" >/dev/null 2>/dev/null

Set the correct permissions:

sudo chmod +x /usr/local/bin/certbot-hetzner-auth.sh
sudo chmod +x /usr/local/bin/certbot-hetzner-cleanup.sh

If your domain uses a standard single-level structure, like example.com, you can now proceed to step 2.

If your domain includes a second-level designation, like example.co.uk, update the value of domain_name at the beginning of both files from 1,2 to 1,2,3:

sudo sed -i "s/-f 1,2 /-f 1,2,3 /" /usr/local/bin/certbot-hetzner-auth.sh
sudo sed -i "s/-f 1,2 /-f 1,2,3 /" /usr/local/bin/certbot-hetzner-cleanup.sh

Step 2 - Acquire API Token

In order to talk to the Hetzner API, we need an authorization token. You can create one in Hetzner Console:

Getting Started » Generating an API token

For this tutorial, we will assume the token is:

LlGoDUQ39S6akqoav5meAsv5OIpeywhj

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

echo "LlGoDUQ39S6akqoav5meAsv5OIpeywhj" | sudo tee /etc/hetzner-dns-token > /dev/null

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 Console API token and used domain validation to request a wildcard certificate, which covers the domain, as well as all subdomains.

License: MIT