Utvecklare → Guider

Wildcard-certifikat med DNS-01 och certbot

DNS-01-utmaningen bevisar att du kontrollerar en domän med en TXT-post i stället för en webbsida. Det är det enda sättet att få ett wildcard-certifikat, och det fungerar för servrar som inte kan nås från internet. Den här hooken låter certbot publicera posten via NameOcean API.

NameOcean utfärdar själv ett kostnadsfritt wildcard-certifikat för alla domäner på NameOcean DNS, förnyar det och ger dig en nedladdningslänk (SSL, eller POST /ssl/example.com). Använd den här guiden när din server ska skaffa och förnya sitt eget certifikat.

Det här behöver du

Domänens DNS hos NameOcean (namnservrarna ns1.nameocean.net till ns4.nameocean.net).
certbot, dig (dnsutils eller bind-utils) och nameocean CLI på servern.
En API-nyckel med dns:read och dns:write. Begränsa den till serverns IP-adress om möjligt.

1. Installera hooken

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

Nyckeln ligger i en fil som bara root kan läsa; certbots sparade förnyelseinställningar innehåller den aldrig.

2. Skaffa certifikatet

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"

För varje namn letar hooken upp vilken av dina NameOcean-zoner det tillhör, lägger till _acme-challenge som en TXT-post och väntar tills alla fyra namnservrar svarar med den, oftast inom tio sekunder. Efter kontrollen tar städsteget bort exakt den post som lades till. example.com och *.example.com använder båda _acme-challenge.example.com; de två värdena publiceras sida vid sida.

3. Förnyelser

certbot sparar hookarna tillsammans med certifikatet, så dess timer förnyar det på samma sätt. Testa det en gång:

root@server

# certbot renew --dry-run

Varje post som hooken lägger till och tar bort visas under Dashboard → Aktivitet tillsammans med nyckeln som användes, och skickar webhook-händelserna dns.record.created och dns.record.deleted.

Hooken

Läs igenom den innan du kör den som root. Den anropar bara nameocean CLI och dig.

/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

Utan CLI

Hooken gör två API-anrop som du kan göra från valfri ACME-klient eller valfritt språk:

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"