Wildcardcertificaat met Certbot via DNS-01 instellen

Waarom een wildcard-certificaat DNS-01 vereist

Een wildcard-certificaat dekt elk subdomein van het eerste niveau van een domein: *.example.com komt overeen met app.example.com, blog.example.com en elke andere naam die één label diep is. Let's Encrypt geeft wildcard-certificaten alleen uit via de DNS-01-challenge. Daarom moet Certbot aantonen dat het de DNS van het domein beheert door een TXT-record te publiceren op _acme-challenge.example.com. De HTTP-01-challenge is hiervoor niet geschikt, omdat het aanbieden van een tokenbestand alleen controle bewijst over één hostnaam: degene waarvan de validatieserver het bestand heeft opgehaald. Een wildcard is een claim over elke mogelijke naam op één niveau onder het domein, en het enige publieke record dat spreekt voor de gehele naamruimte is de DNS zelf.

Die ene vereiste bepaalt alles op deze pagina. Om DNS-01 te voltooien, moet u TXT-records kunnen aanmaken in de zone van het domein, of in een afzonderlijke validatiezone waarnaar _acme-challenge verwijst met een CNAME (hieronder besproken). Dit kan handmatig of via de API (application programming interface) van uw DNS-provider. De handmatige methode werkt één keer, maar faalt bij vernieuwing om een concrete reden die hieronder wordt getoond. De API-methode, via een Certbot DNS-plugin, vernieuwt automatisch en is de configuratie waar u uiteindelijk op uit zou moeten komen.

Dit is het wildcard-hoofdstuk van onze Certbot-handleidingen. Gewone certificaten voor één hostnaam, de configuratie van de webserver en de regels voor poort 80 worden behandeld in Certbot met nginx op Ubuntu 24.04 en Certbot met Apache op Ubuntu 24.04.

Hoe het TXT-record voor _acme-challenge werkt

Wanneer Certbot *.example.com aanvraagt, antwoordt Let's Encrypt met een willekeurig token. Certbot combineert dat token met de ACME-sleutel (automatic certificate management environment) van uw account, berekent een hash van het resultaat met SHA-256 en produceert een korte tekstwaarde. Die waarde moet als TXT-record op _acme-challenge.example.com staan. Let's Encrypt bevraagt vervolgens vanaf zijn eigen infrastructuur de gezaghebbende nameservers van uw domein. Als het record dat Let's Encrypt leest overeenkomt met de verwachte waarde, hebt u aangetoond dat u controle hebt over de zone. Controle over de zone wordt dan geaccepteerd als controle over elke naam daaronder.

Twee details veroorzaken de meeste fouten:

• Als u example.com en *.example.com op hetzelfde certificaat aanvraagt, zijn dit twee afzonderlijke uitdagingen. Beide TXT-records staan op dezelfde naam, _acme-challenge.example.com. Beide records moeten tegelijkertijd bestaan. Het tweede record toevoegen is correct. Het eerste record vervangen door het tweede laat de eerste uitdaging mislukken.
• De validatie leest uw gezaghebbende servers, maar de beheerpanelen van providers kunnen een minuut of langer nodig hebben om een nieuw record naar deze servers te publiceren. Controleer dit vanaf een externe locatie voordat u de validatie laat uitvoeren:

dig +short TXT _acme-challenge.example.com @1.1.1.1

Wanneer dit de waarde weergeeft die Certbot heeft opgevraagd, kan de validatie slagen. Wanneer er niets wordt weergegeven, wacht u en voert u de opdracht opnieuw uit.

Eenmalig zien hoe het werkt: handmatige modus

In de handmatige modus voert u de DNS-wijziging zelf uit. Zo begrijpt u het mechanisme voordat u dit automatiseert:

sudo certbot certonly --manual --preferred-challenges dns -d example.com -d '*.example.com'

De aanhalingstekens rond de wildcard voorkomen dat uw shell * als een bestandsnaampatroon behandelt. Certbot pauzeert en geeft instructies:

Please deploy a DNS TXT record under the name:
_acme-challenge.example.com.
with the following value:
Jx9mQ2wLr8vTn5cKp0aYdG3hB7fZs4eN1oiRuXqMk6E

Maak die TXT-record aan in het paneel van uw DNS-provider. Controleer met de bovenstaande opdracht dig of de record zichtbaar is. Druk pas daarna op Enter. Omdat deze uitvoering om het hoofddomein en de wildcard vraagt, geeft Certbot tweemaal een prompt. Laat beide records staan totdat de uitgifte is voltooid. Bij succes eindigt de uitvoer met de bekende regels:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem

Waarom de handmatige modus zichzelf niet kan vernieuwen

Elke vernieuwing is een nieuwe challenge met een nieuw token. Daarom verandert de TXT-waarde elke keer. Het record dat u vandaag hebt toegevoegd, is over 60 dagen niet meer bruikbaar. De vernieuwingstimer voert Certbot tweemaal per dag zonder toezicht uit. Er is dan niemand achter het toetsenbord om de nieuwe waarde toe te voegen. Daarom mislukt de vernieuwing van een handmatig uitgegeven certificaat met precies deze fout:

Failed to renew certificate example.com with error: The manual plugin is not
working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with
--manual-auth-hook when using the manual plugin non-interactively.')

U kunt aan deze vereiste voldoen door --manual-auth-hook-scripts te schrijven die de API van uw DNS-provider aanroepen. Op dat moment bouwt u echter handmatig een DNS-plugin opnieuw. Gebruik de handmatige modus om de procedure te leren, of voor een eenmalige uitgifte voor een domein waarvan u de DNS nog niet kunt automatiseren. Stel ruim vóór dag 90 een herinnering in, omdat Let's Encrypt geen e-mails over het verlopen van certificaten meer verstuurt. Gebruik in alle andere gevallen een plugin.

De pluginroute: certbot-dns-cloudflare op Ubuntu 24.04

Een DNS-plugin bevat een API-referentie voor uw DNS-provider en voert het volledige proces met TXT-records zelf uit, zowel bij de uitgifte als bij elke verlenging. Cloudflare wordt hier als voorbeeld gebruikt omdat dit de providerplugin is die de meeste gebruikers nodig hebben en die in Ubuntu is opgenomen.

Onze Certbot-handleidingen bevelen de apt-pakketten op Ubuntu 24.04 aan. Dat geldt ook voor Cloudflare:

sudo apt update
sudo apt install certbot python3-certbot-dns-cloudflare

Een opmerking over de versies. Het archief van 24.04 bevat deze plugin met versie 2.0.0 naast Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare toont uw versie. Deze afwijking is geen probleem. API-tokens met beperkte rechten werken, omdat de onderliggende python3-cloudflare-bibliotheek in 24.04 versie 2.11.1 heeft. Dat is hoger dan versie 2.3.1, die de plugin nodig heeft voor tokenondersteuning. In oudere Ubuntu-releases was die bibliotheek te oud voor tokens. Daar komen de waarschuwingen vandaan die u online kunt vinden over de apt-plugin die de Global API Key verplicht stelt. Op 24.04 zijn die waarschuwingen niet meer van toepassing.

Maak in het Cloudflare-dashboard een API-token met beperkte rechten aan, niet de Global API Key: My Profile, vervolgens API Tokens en daarna Create Token. Gebruik alleen de machtiging Zone / DNS / Edit en beperk het token tot de zone waarvoor u het certificaat uitgeeft. Plaats het token in een bestand dat alleen root kan lezen:

sudo mkdir -p /root/.secrets
sudo tee /root/.secrets/cloudflare.ini > /dev/null <<'EOF'
dns_cloudflare_api_token = paste_your_scoped_token_here
EOF
sudo chmod 600 /root/.secrets/cloudflare.ini

Certbot controleert de modus en waarschuwt voor Unsafe permissions on credentials configuration file als anderen het bestand kunnen lezen. Vraag nu het certificaat aan:

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
  -d example.com -d '*.example.com'

De plugin maakt de TXT-records via de API aan, wacht kort totdat de wijzigingen zijn doorgevoerd, laat de validatie uitvoeren en verwijdert de records daarna weer. Als de nameservers van uw zone wijzigingen langzaam overnemen, verhoogt u de wachttijd met --dns-cloudflare-propagation-seconds 60. Het certificaat wordt opgeslagen in /etc/letsencrypt/live/example.com/. Configureer nginx of Apache met fullchain.pem en privkey.pem, precies zoals in de basishandleidingen wordt beschreven, inclusief de deploy hook.

Als de plugin van uw provider niet in apt staat

Het archief van 24.04 bevat alleen plugins voor een handvol providers, waaronder Cloudflare, Route 53, DigitalOcean en de generieke RFC 2136-interface. Voer apt search certbot-dns uit om de lijst te bekijken. Als uw provider ontbreekt, is dit het enige punt waarop ons advies om apt te gebruiken vervalt: installeer Certbot en de plugin in plaats daarvan via snap, en verwijder eerst de apt-versie van Certbot zodat twee vernieuwingstimers nooit strijden om /etc/letsencrypt:

sudo apt remove certbot python3-certbot-dns-cloudflare
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-yourprovider

Een snap-plugin maakt alleen verbinding met de snap-versie van Certbot; deze kan de apt-versie niet uitbreiden. Daarom mogen beide installaties niet naast elkaar bestaan. Als uw DNS-host helemaal geen API aanbiedt, heeft u drie realistische opties. U kunt de DNS van het domein verhuizen naar een provider die wel een API heeft. U kunt uw eigen nameserver draaien en de rfc2136-plugin daarop richten. Of u kunt uw huidige DNS-host behouden en een eenmalige CNAME toevoegen van _acme-challenge.example.com naar een validatiezone die wel een API heeft, zoals een gehoste acme-dns-service of een acme-dns-server die u zelf beheert. Let's Encrypt volgt die CNAME tijdens de validatie, waardoor de TXT-records in de gedelegeerde zone staan en uw hoofdzone nooit meer hoeft te veranderen.

Vernieuwing: bewijs dit nu, niet over 60 dagen

Certbot registreert in /etc/letsencrypt/renewal/example.com.conf hoe elk certificaat is uitgegeven, waaronder authenticator = dns-cloudflare en het pad naar de referenties. De standaardtimer die tweemaal per dag wordt uitgevoerd, vernieuwt het certificaat daardoor zonder uw tussenkomst. Test de volledige procedure tegen de stagingomgeving:

sudo certbot renew --dry-run

Een geslaagde test betekent dat de referentie werkt en dat de validatie van begin tot eind wordt voltooid. De werkelijke vernieuwing over 60 dagen volgt hetzelfde pad. Voer vandaag nog twee vervolgstappen uit. Ten eerste verandert een vernieuwd certificaat op schijf niets totdat de webserver het opnieuw laadt. Configureer daarom de deploy hook die in de nginx- en Apache-handleidingen wordt beschreven. Ten tweede moet u zorgvuldig omgaan met het bestand met referenties. Iedereen die het kan lezen, kan uw DNS-zone wijzigen. Daarmee kan die persoon uw e-mail omleiden of eigen DNS-01-challenges uitvoeren. Stel de bestandsmodus in op 600, bewaar het bestand onder /root, beperk het token tot één zone en roteer het token als u ooit vermoedt dat het is gelekt.

Wanneer u geen wildcard nodig hebt

Een wildcard is geschikt voor veel subdomeinen of voor subdomeinen die u niet kunt voorspellen. Het is niet de juiste standaardkeuze voor alle andere situaties.

• Eén subdomein of een beperkt aantal bekende subdomeinen: een normaal SAN-certificaat (subject alternative name) is eenvoudiger. certbot --nginx -d example.com -d www.example.com -d app.example.com ondersteunt maximaal 100 namen via plain HTTP-01, en er staat nooit een DNS API-referentie op de server.
• Een wildcard komt exact overeen met één label. *.example.com dekt het kale example.com niet. Daarom vragen de bovenstaande opdrachten beide aan. De wildcard dekt ook a.b.example.com niet; daarvoor is *.b.example.com nodig.
• Achter elk subdomein staat dezelfde private key. Als de machine waarop deze sleutel staat wordt gecompromitteerd, worden alle namen die de wildcard dekt tegelijk getroffen.
• Als Traefik TLS (transport layer security) beëindigt voor uw containers, hebt u Certbot helemaal niet nodig: Traefik vraagt zelf wildcardcertificaten aan via DNS-01, met hetzelfde type providertoken.

Een wildcard is vooral nuttig voor subdomeinen per klant of per app die sneller worden aangemaakt dan u certificaten opnieuw wilt uitgeven, en voor interne hosts zonder openbare poort 80, zoals services die alleen bereikbaar zijn via een WireGuard VPN. DNS-01 maakt nooit verbinding met de host waarvoor het certificaat wordt uitgegeven. Daarom kan zelfs een volledig private machine een publiek vertrouwd certificaat bevatten.

FAQ

Kan Certbot een wildcard-certificaat uitgeven met HTTP-01?

Nee. HTTP-01 bewijst controle over één hostnaam, omdat de validatieserver een tokenbestand ophaalt van die specifieke naam. Een wildcard dekt elke naam op het eerste niveau onder het domein, dus Let's Encrypt vereist hiervoor de DNS-01-challenge. De authenticators --nginx, --apache, --webroot en --standalone zijn allemaal gebaseerd op HTTP. De enige route is een TXT-record op _acme-challenge.example.com (of in de zone waarnaar dit via CNAME is gedelegeerd), handmatig geplaatst of via een DNS-plugin.

Dekt een wildcard-certificaat het hoofddomein?

Nee. De wildcard komt overeen met precies één label. Daarom dekt *.example.com wel www.example.com, maar niet het kale example.com en ook niet a.b.example.com. Vraag beide namen aan op één certificaat met -d example.com -d '*.example.com'. Dat creëert twee challenges, en beide TXT-records staan op dezelfde _acme-challenge.example.com-naam; voeg dus het tweede record toe zonder het eerste te verwijderen.

Waarom vernieuwt mijn wildcard-certificaat niet automatisch?

Omdat het is uitgegeven met --manual. Elke vernieuwing vereist een gloednieuwe TXT-waarde, en de automatische timer heeft geen manier om deze in te voeren, waardoor de vernieuwing stopt met de foutmelding An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Vraag het certificaat opnieuw aan met een DNS-plugin zoals certbot-dns-cloudflare, of lever --manual-auth-hook en --manual-cleanup-hook-scripts die het record bewerken via de API van uw provider.

Hoe lang duurt het voordat het _acme-challenge TXT-record verschijnt?

Dit hangt af van uw DNS-provider: van enkele seconden tot enkele minuten. Validatie leest de autoritatieve servers van uw zone; controleer dit met dig +short TXT _acme-challenge.example.com @1.1.1.1 en wacht tot de verwachte waarde verschijnt voordat u doorgaat met een handmatige uitvoering. Verhoog bij een plugin de ingebouwde wachttijd via de propagatie-optie van de plugin, bijvoorbeeld --dns-cloudflare-propagation-seconds 60, als de validatie meldt dat het record niet is gevonden.

Is een wildcard-certificaat minder veilig dan een normaal certificaat?

De cryptografie is identiek. De verschillen zijn operationeel: één privésleutel dekt elk subdomein, waardoor een inbreuk grotere gevolgen heeft. Bovendien zijn de DNS API-inloggegevens die automatisering vereist, zelf gevoelige geheimen die op de server worden opgeslagen. Als u slechts enkele bekende subdomeinen beheert, voorkomt een SAN-certificaat beide zorgen. Dat is precies het moment waarop deze handleiding adviseert om de wildcard over te slaan.