Wildcardcertificaten met DNS-01 en certbot

Met de DNS-01-challenge bewijst u dat u een domein beheert via een TXT-record in plaats van een webpagina. Het is de enige manier om een wildcardcertificaat te verkrijgen, en het werkt ook voor servers die niet bereikbaar zijn vanaf internet. Met deze hook kan certbot dat record via de NameOcean API publiceren.

NameOcean geeft zelf een gratis wildcardcertificaat uit voor elk domein op NameOcean DNS, verlengt het en geeft u een downloadlink (SSL, of POST /ssl/example.com). Gebruik deze handleiding als uw server zelf een certificaat moet aanvragen en verlengen.

Wat u nodig hebt

De DNS van het domein bij NameOcean (nameservers ns1.nameocean.net tot en met ns4.nameocean.net).
certbot, dig (dnsutils of bind-utils) en de nameocean CLI op de server.
Een API-sleutel met dns:read en dns:write. Beperk deze indien mogelijk tot het IP-adres van de server.

1. De hook installeren

root@server

# curl -fsSL https://nameocean.net/install.sh | sh
# curl -fsSL https://nameocean.net/developers/guides/letsencrypt-dns-01/nameocean-hook.sh \
    -o /etc/letsencrypt/nameocean-hook.sh
# chmod 700 /etc/letsencrypt/nameocean-hook.sh
# echo 'NAMEOCEAN_API_KEY=no_live_…' > /etc/letsencrypt/nameocean.env
# chmod 600 /etc/letsencrypt/nameocean.env

De sleutel staat in een bestand dat alleen root kan lezen; de opgeslagen verlengingsinstellingen van certbot bevatten hem nooit.

2. Het certificaat aanvragen

root@server

# certbot certonly --manual --preferred-challenges dns \
    --manual-auth-hook "/etc/letsencrypt/nameocean-hook.sh auth" \
    --manual-cleanup-hook "/etc/letsencrypt/nameocean-hook.sh cleanup" \
    -d example.com -d "*.example.com"

Voor elke naam zoekt de hook de bijbehorende zone tussen uw NameOcean-zones, voegt _acme-challenge toe als TXT-record en wacht tot alle vier de nameservers ermee antwoorden, meestal binnen tien seconden. Na de controle verwijdert de opschoonstap precies het record dat is toegevoegd. example.com en *.example.com gebruiken allebei _acme-challenge.example.com; de twee waarden worden naast elkaar gepubliceerd.

3. Verlengingen

certbot slaat de hooks op bij het certificaat, zodat de timer het op dezelfde manier verlengt. Test dat één keer:

root@server

# certbot renew --dry-run

Elk record dat de hook toevoegt en verwijdert, staat in Dashboard → Activiteit met de sleutel die het deed, en verstuurt webhook-events dns.record.created en dns.record.deleted.

De hook

Lees hem door voordat u hem als root uitvoert. Hij roept alleen de nameocean CLI en dig aan.

/etc/letsencrypt/nameocean-hook.sh

#!/bin/sh
# certbot DNS-01 hooks for NameOcean DNS:
#   --manual-auth-hook "/etc/letsencrypt/nameocean-hook.sh auth"
#   --manual-cleanup-hook "/etc/letsencrypt/nameocean-hook.sh cleanup"
# Needs the nameocean CLI and an API key with dns:write, in /etc/letsencrypt/nameocean.env:
#   NAMEOCEAN_API_KEY=no_live_...
set -e
[ -f /etc/letsencrypt/nameocean.env ] && . /etc/letsencrypt/nameocean.env && export NAMEOCEAN_API_KEY

# the zone CERTBOT_DOMAIN is in: the longest of your zones it ends with
zone="$NAMEOCEAN_ZONE"
if [ -z "$zone" ]; then
  for z in $(nameocean dns ls --json | sed -n 's/.*"name": *"\([^"]*\)".*/\1/p'); do
    case "$CERTBOT_DOMAIN" in "$z" | *".$z") [ ${#z} -gt ${#zone} ] && zone="$z" ;; esac
  done
fi
[ -n "$zone" ] || { echo "no NameOcean DNS zone for $CERTBOT_DOMAIN" >&2; exit 1; }
name="_acme-challenge"
[ "$CERTBOT_DOMAIN" = "$zone" ] || name="_acme-challenge.${CERTBOT_DOMAIN%.$zone}"

case "$1" in
auth)
  id=$(nameocean dns add "$zone" TXT "$name" "$CERTBOT_VALIDATION" --ttl 5m --json \
    | sed -n 's/.*"id": *\([0-9][0-9]*\).*/\1/p' | head -n 1)
  [ -n "$id" ] || { echo "could not add the TXT record" >&2; exit 1; }
  echo "$id" # certbot passes this to the cleanup hook as CERTBOT_AUTH_OUTPUT
  # wait until all four nameservers answer with it (usually a few seconds)
  for i in $(seq 1 60); do
    n=0
    for ns in ns1 ns2 ns3 ns4; do
      dig +short TXT "$name.$zone" "@$ns.nameocean.net" | grep -q -- "$CERTBOT_VALIDATION" && n=$((n + 1))
    done
    [ "$n" -eq 4 ] && exit 0
    sleep 2
  done
  echo "the TXT record is not on every nameserver after 2 minutes" >&2
  exit 1
  ;;
cleanup)
  [ -z "$CERTBOT_AUTH_OUTPUT" ] || nameocean dns rm "$zone" TXT "$CERTBOT_AUTH_OUTPUT"
  ;;
*)
  echo "usage: $0 auth|cleanup" >&2
  exit 2
  ;;
esac

Zonder de CLI

De hook doet twee API-aanroepen die u vanuit elke ACME-client of programmeertaal kunt doen:

curl

$ curl -X POST https://nameocean.net/api/v1/dns/example.com/records \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" -H "Content-Type: application/json" \
    -d '{"type": "TXT", "hostname": "_acme-challenge", "text": "<validation>", "ttl": "5m"}'
{"id": 4190, "type": "TXT", "hostname": "_acme-challenge", …}
$ curl -X DELETE https://nameocean.net/api/v1/dns/example.com/records/TXT/4190 \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY"