Wildcardcertificaat met Certbot via DNS-01 instellen

Waarom een wildcardcertificaat DNS-01 vereist

Een wildcardcertificaat dekt elk subdomein op 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 ligt. Let's Encrypt geeft wildcardcertificaten alleen uit via de DNS-01-challenge. Certbot moet daarom aantonen dat u controle hebt over de DNS van het domein door een TXT-record te publiceren op _acme-challenge.example.com. De HTTP-01-challenge kan hiervoor niet worden gebruikt, omdat het aanbieden van een tokenbestand alleen controle bewijst over één hostnaam: de hostnaam waarvan de validatieserver het bestand heeft opgehaald. Een wildcard is een claim over elke mogelijke naam onder het domein. Alleen DNS bevat een openbaar record dat voor de volledige naamruimte staat.

Deze ene vereiste bepaalt al het andere op deze pagina. Voor DNS-01 moet u TXT-records kunnen aanmaken in de zone van het domein. Dat kan handmatig of via de API (application programming interface) van uw DNS-provider. De handmatige methode werkt eenmalig en mislukt daarna bij de vernieuwing. Hieronder wordt de concrete oorzaak daarvan uitgelegd. De API-methode gebruikt een Certbot DNS-plugin, vernieuwt het certificaat zonder tussenkomst en is de configuratie die u uiteindelijk moet gebruiken.

Dit is het hoofdstuk over wildcardcertificaten in onze Certbot-handleidingen. 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 24.04-archief bevat alleen plugins voor een beperkt aantal providers, waaronder Cloudflare, Route 53, DigitalOcean en de generieke RFC 2136-interface. Voer apt search certbot-dns uit om de lijst weer te geven. Als uw provider ontbreekt, wijkt u hier als enige af van het advies om apt te gebruiken: installeer Certbot en de plugin in plaats daarvan via snap en verwijder eerst Certbot uit apt, zodat twee vernieuwings-timers nooit tegelijk /etc/letsencrypt beheren:

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 werkt alleen met Certbot uit snap. De plugin kan Certbot uit apt niet uitbreiden. Daarom mogen beide installaties niet naast elkaar bestaan. Als uw DNS-host helemaal geen API aanbiedt, zijn uw realistische opties het DNS-beheer van het domein verplaatsen naar een provider die wel een API heeft, of uw eigen nameserver uitvoeren en de rfc2136-plugin daarnaar laten verwijzen.

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 wildcardcertificaat uitgeven met HTTP-01?

Nee. HTTP-01 bewijst de controle over één hostnaam, omdat de validatieserver een tokenbestand op die exacte naam ophaalt. Een wildcard dekt elke naam onder het domein. Daarom vereist Let's Encrypt hiervoor de DNS-01-challenge. De authenticators --nginx, --apache, --webroot en --standalone werken allemaal via HTTP. De enige optie is een TXT-record op _acme-challenge.example.com, dat u handmatig of met een DNS-plugin plaatst.

Dekt een wildcardcertificaat het hoofddomein?

Nee. De wildcard komt exact overeen met éé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 op één certificaat aan met -d example.com -d '*.example.com'. Daarmee ontstaan twee challenges. Beide TXT-records gebruiken dezelfde naam _acme-challenge.example.com. Voeg het tweede record daarom toe zonder het eerste te verwijderen.

Waarom wordt mijn wildcardcertificaat niet automatisch vernieuwd?

Omdat het is uitgegeven met --manual. Voor elke vernieuwing is een volledig nieuwe TXT-waarde nodig. De unattended timer kan deze waarde niet invoeren. Daarom stopt de vernieuwing met de foutmelding An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Geef het certificaat opnieuw uit met een DNS-plugin zoals certbot-dns-cloudflare. U kunt ook scripts --manual-auth-hook en --manual-cleanup-hook opgeven die het record via de API van uw provider aanpassen.

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

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

Is een wildcardcertificaat minder veilig dan een normaal certificaat?

De cryptografie is identiek. De verschillen zijn operationeel. Eén privésleutel dekt elk subdomein. Bij een inbreuk kan de aanvaller daardoor meer systemen bereiken. Daarnaast is de DNS API-credential die automatisering vereist zelf een gevoelig geheim dat op de server wordt opgeslagen. Als u slechts enkele bekende subdomeinen gebruikt, voorkomt een SAN-certificaat beide problemen. Dat is precies de situatie waarin deze handleiding adviseert de wildcard over te slaan.