Certbot wildcard certificate DNS-01 maken

Waarom een wildcard certificate DNS-01 nodig heeft

Een wildcard certificate dekt elk eerste-niveau subdomain van een domein: *.example.com komt overeen met app.example.com, blog.example.com en elke andere naam met één label. Let's Encrypt geeft wildcard certificates alleen uit via de DNS-01 challenge. Certbot moet daarom het beheer van de DNS van het domein bewijzen door een TXT record te publiceren op _acme-challenge.example.com. De HTTP-01 challenge is niet geschikt. Het serveren van een token file bewijst namelijk alleen het beheer van één hostname, namelijk de hostname waar de validatieserver het bestand ophaalt. Een wildcard is een claim over elke mogelijke naam onder het domein. Het enige publieke record dat het volledige namespace dekt, is DNS zelf.

Deze vereiste bepaalt alle andere zaken op deze pagina. Om DNS-01 te voltooien, moet u TXT records kunnen aanmaken in de zone van het domein. Dit kan handmatig of via de API (application programming interface) van uw DNS-provider. De handmatige methode werkt eenmalig, maar faalt bij verlenging door de reden die hieronder wordt beschreven. De API-methode via een Certbot DNS plugin werkt automatisch bij verlenging. Dit is de configuratie die u moet gebruiken.

Dit is het wildcard hoofdstuk van onze Certbot handleidingen. Gewone single-hostname certificates, de webserver configuratie en de port 80 regels worden behandeld in Certbot met nginx op Ubuntu 24.04 en Certbot met Apache op Ubuntu 24.04.

Hoe de _acme-challenge TXT record werkt

Wanneer Certbot om *.example.com vraagt, antwoordt Let's Encrypt met een willekeurige token. Certbot combineert deze token met uw ACME (automatic certificate management environment) account key. Vervolgens wordt het resultaat gehasht met SHA-256 om een korte tekstwaarde te genereren. Deze waarde moet als TXT record aanwezig zijn op _acme-challenge.example.com. Let's Encrypt bevraagt vervolgens de authoritative name servers van uw domein vanuit de eigen infrastructuur. Als de gelezen record overeenkomt met de verwachte waarde, heeft u bewezen dat u de zone beheert. Controle over de zone wordt geaccepteerd als controle over alle subdomeinen daaronder.

De volgende twee details veroorzaken de meeste fouten:

• Het aanvragen van example.com en *.example.com voor hetzelfde certificaat betekent twee afzonderlijke challenges. Beide TXT records staan op dezelfde naam, _acme-challenge.example.com. Beide records moeten tegelijkertijd aanwezig zijn. Het toevoegen van het tweede record is de juiste methode; het vervangen van het eerste record door het tweede zorgt ervoor dat de eerste challenge mislukt.
• Validatie leest uw authoritative servers, maar controlepanelen van providers kunnen er een minuut of langer over doen om een nieuwe record te publiceren. Controleer de status vanaf een externe locatie voordat u de validatie start:

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

Wanneer de opdracht de waarde weergeeft waar Certbot om heeft gevraagd, kan de validatie slagen. Wanneer de opdracht niets weergeeft, moet u wachten en de opdracht opnieuw uitvoeren.

Test het eenmalig uit: handmatige modus

In de handmatige modus moet u de DNS-wijziging zelf uitvoeren. Dit is de beste manier om het mechanisme te begrijpen voordat u het 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 dit TXT-record aan in het paneel van uw DNS-provider. Controleer of het zichtbaar is met het dig commando hierboven. Druk pas daarna op Enter. Omdat deze uitvoering om zowel het basisdomein als de wildcard vraagt, vraagt Certbot twee keer om actie; laat beide records staan totdat de certificaatverstrekking is voltooid. Een succesvolle uitvoering eindigt 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 uitdaging met een nieuwe token, waardoor de TXT-waarde telkens verandert. De record die u vandaag heeft geplakt, is over 60 dagen onbruikbaar. De vernieuwings-timer van Certbot draait twee keer per dag onafhankelijk. Omdat er niemand bij het toetsenbord zit om de nieuwe waarde te plakken, mislukt de vernieuwing van een handmatig uitgegeven certificaat met deze foutmelding:

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, maar op dat punt bouwt u handmatig een DNS-plugin. Gebruik de handmatige modus om het proces te leren, of voor een eenmalige actie op een domein waarvan u de DNS nog niet kunt automatiseren. Stel een herinnering in ruim voordat dag 90 is bereikt, omdat Let's Encrypt geen e-mails over de vervaldatum meer verzendt. Gebruik voor alle andere gevallen een plugin.

De plugin-methode: certbot-dns-cloudflare op Ubuntu 24.04

Een DNS-plugin bevat een API-credential voor uw DNS-provider. De plugin voert de volledige TXT-record procedure zelf uit tijdens de initiële uitgifte en bij elke verlenging. Cloudflare is hier het voorbeeld, omdat dit de meest gebruikte provider-plugin is en deze in Ubuntu is verpakt.

Onze Certbot-handleidingen adviseren het gebruik van de apt-packages op Ubuntu 24.04. Dit geldt ook voor Cloudflare:

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

Een opmerking over versies. Het 24.04-archief levert deze plugin in versie 2.0.0 samen met Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare toont uw versie. Deze mismatch is onschadelijk. Scoped API-tokens werken, omdat de onderliggende python3-cloudflare-bibliotheek in 24.04 versie 2.11.1 is. Dit is hoger dan de versie 2.3.1 die de plugin nodig heeft voor token-ondersteuning. Bij oudere Ubuntu-versies was die bibliotheek te oud voor tokens. Dit is de reden voor waarschuwingen online over de apt-plugin die de Global API Key afdwingt. Op 24.04 zijn deze waarschuwingen niet meer van toepassing.

Maak in het Cloudflare-dashboard een scoped API-token aan in plaats van de Global API Key: My Profile, dan API Tokens, dan Create Token. Gebruik de enkele permissie Zone / DNS / Edit, beperkt tot de specifieke zone waarvoor u het certificaat uitgeeft. Plaats dit in een bestand dat alleen door root gelezen kan worden:

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 bestandsrechten en geeft een waarschuwing over Unsafe permissions on credentials configuration file als het bestand leesbaar is voor anderen. Voer nu uit:

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

De plugin maakt de TXT-records aan via de API, wacht een korte propagatieperiode af, voert de validatie uit en verwijdert de records vervolgens weer. Als de nameservers van uw zone traag zijn met het verwerken van wijzigingen, verhoog dan de wachttijd met --dns-cloudflare-propagation-seconds 60. Het certificaat wordt opgeslagen in /etc/letsencrypt/live/example.com/. U wijst nginx of Apache naar fullchain.pem en privkey.pem zoals beschreven in de basishandleidingen, 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. Hieronder vallen 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, wijkt ons advies af van de standaard 'apt-first' methode: installeer Certbot en de plugin via snap. Verwijder eerst de apt-versie van Certbot, zodat twee renewal-timers niet tegelijkertijd om /etc/letsencrypt strijden:

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 uitsluitend met de snap-versie van Certbot; deze kan de apt-versie niet uitbreiden. Daarom mogen deze twee installaties niet naast elkaar bestaan. Als uw DNS-host geen API biedt, zijn uw opties beperkt tot het verplaatsen van de DNS van het domein naar een provider met een API, of het draaien van een eigen nameserver en het koppelen van de rfc2136-plugin aan deze server.

Verlenging: bewijs het nu, niet over 60 dagen

Certbot registreert hoe elk certificaat is uitgegeven in /etc/letsencrypt/renewal/example.com.conf, inclusief authenticator = dns-cloudflare en het pad naar de credentials, zodat de standaard timer die twee keer per dag draait de verlenging zonder uw tussenkomst uitvoert. Test het volledige proces in de staging-omgeving:

sudo certbot renew --dry-run

Een geslaagde test betekent dat de credentials werken en de validatie volledig is voltooid; de echte verlenging over 60 dagen volgt hetzelfde proces. Het is raadzaam om vandaag twee vervolgstappen te nemen. Ten eerste: een verlengd certificaat op de schijf verandert niets totdat de webserver het opnieuw laadt. Configureer daarom de deploy hook zoals beschreven in de nginx en Apache handleidingen. Ten tweede: behandel het credentials-bestand met zorg: iedereen die het kan lezen, kan uw DNS-zone wijzigen. Dit is voldoende om uw e-mail om te leiden of eigen DNS-01 challenges te passeren. Houd het bestand op mode 600 onder /root, beperk de token tot één zone, en roteer deze als u een lek vermoedt.

Wanneer u geen wildcard nodig heeft

Een wildcard is het juiste hulpmiddel voor veel subdomeinen, of voor subdomeinen die u niet kunt voorspellen. Voor alle andere gevallen is het een onjuiste standaardinstelling.

• Eén subdomein, of een handvol bekende subdomeinen: een normale SAN (subject alternative name) certificaat is eenvoudiger. certbot --nginx -d example.com -d www.example.com -d app.example.com dekt tot 100 namen via HTTP-01, en er hoeft nooit een DNS API-credential op de server te staan.
• Een wildcard komt exact één label overeen. *.example.com dekt de kale example.com niet, daarom vragen de bovenstaande commando's beide aan, en het dekt ook a.b.example.com niet; daarvoor is *.b.example.com nodig.
• Er staat één private key achter elk subdomein. Als de machine waar deze op staat gecompromitteerd wordt, zijn alle namen die de wildcard dekt in één keer getroffen.
• Als Traefik TLS (transport layer security) termineert voor uw containers, heeft u Certbot helemaal niet nodig: Traefik vraagt zelf wildcard-certificaten aan via DNS-01, waarbij dezelfde soort provider-token wordt gebruikt.

Wanneer een wildcard echt nuttig is: subdomeinen per klant of per app die sneller worden aangemaakt dan u certificaten wilt heruitgeven, en interne hosts zonder publieke poort 80, zoals services die alleen bereikbaar zijn via een WireGuard VPN. DNS-01 maakt nooit verbinding met de gecertificeerde host, waardoor zelfs een volledig privé-machine een publiek vertrouwd certificaat kan hebben.

FAQ

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

Nee. HTTP-01 bewijst de controle over één hostname, omdat de validatieserver een token-bestand ophaalt van die specifieke naam. Een wildcard dekt elke naam onder het domein. Daarom vereist Let's Encrypt de DNS-01 challenge voor wildcards. De authenticators --nginx, --apache, --webroot en --standalone zijn allemaal HTTP-gebaseerd. De enige methode is een TXT-record bij _acme-challenge.example.com, handmatig geplaatst of via een DNS-plugin.

Dekt een wildcard-certificaat de root-domein?

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

Waarom wordt mijn wildcard-certificaat niet automatisch vernieuwd?

Omdat het is uitgegeven met --manual. Elke vernieuwing vereist een nieuwe TXT-waarde. De unattended timer kan deze waarde niet plakken, waardoor de vernieuwing stopt met de foutmelding An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Voer het certificaat opnieuw uit met een DNS-plugin zoals certbot-dns-cloudflare, of gebruik --manual-auth-hook en --manual-cleanup-hook scripts die het record bewerken via de API van de provider.

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

Dit hangt af van de DNS-provider: van enkele seconden tot enkele minuten. Validatie leest de authoritative servers van de zone. Controleer dit met dig +short TXT _acme-challenge.example.com @1.1.1.1 en wacht tot de verwachte waarde verschijnt voordat u een handmatige run voortzet. Gebruik bij een plugin de ingebouwde wachtfunctie via de propagation-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 private key dekt elk subdomain, waardoor een compromis een grotere impact heeft. Daarnaast is de DNS API-credential die automatisering vereist zelf een gevoelig geheim dat op de server staat. Als u slechts enkele bekende subdomains gebruikt, voorkomt een SAN-certificaat beide risico's. Dit is de reden waarom deze gids aanbeveelt om wildcards over te slaan in die gevallen.