Hoe Let's Encrypt automatisch certificaten uitgeeft: ACME
Het certificaat van deze site loopt 90 dagen. Niemand vraagt het aan, niemand betaalt ervoor en niemand vernieuwt het met de hand. Een programmaatje op de server praat met Let's Encrypt via een protocol dat ACME heet. Dat protocol bewijst dat de server het domein echt beheert en haalt daarna een nieuw certificaat op. Zo geeft Let's Encrypt automatisch certificaten uit, en dat is precies de bedoeling.
Hieronder loop ik ACME stap voor stap door, zoals het in RFC 8555 staat. Ik heb het ook zelf gedaan, met een klein Python-script tegen de testserver van Let's Encrypt: account aanmaken, certificaat bestellen en challenges ophalen. Hoe de browser het daarna controleert, staat in Hoe je browser een certificaat vertrouwt.
Een adresboek als startpunt
Een ACME-client hoeft maar één URL te kennen: de directory. Dat is een JSON-bestand met de adressen van alle andere functies. Bij Let's Encrypt is dat https://acme-v02.api.letsencrypt.org/directory. Daarin staan onder meer newNonce, newAccount, newOrder en revokeCert, plus een lijst profielen: classic, tlsserver en shortlived.
Een ACME-account is een sleutelpaar
ACME kent geen wachtwoord of API-sleutel. Je account is een sleutelpaar dat de client zelf maakt. Elk verzoek is een POST met een JWS: een JSON-object met een header, de inhoud en een handtekening over beide. Bij het eerste verzoek, newAccount, zit de publieke sleutel zelf in de header. De server antwoordt met een account-URL, bij mij .../acme/acct/364048313, en vanaf dan verwijst elk verzoek naar die URL in plaats van naar de sleutel.
Nonces tegen herhaalde verzoeken
Een onderschept ondertekend verzoek kun je niet aanpassen, wel opnieuw versturen. Daarom moet elk verzoek een nonce bevatten: een eenmalige waarde die de server in de header Replay-Nonce meegeeft. De eerste haal je op met een HEAD-verzoek op newNonce. Daarna zit er bij elk geslaagd antwoord op een POST een nieuwe bij.
Ik heb een nonce bewust twee keer gebruikt. Het tweede verzoek werd geweigerd met status 400 en het fouttype urn:ietf:params:acme:error:badNonce.
De bestelling: een order
Een certificaat vraag je aan met newOrder, met de domeinnamen erin. Ik vroeg op de testserver om wallieweb.nl. Het antwoord:
{
"status": "pending",
"expires": "2026-11-10T04:31:34Z",
"identifiers": [{"type": "dns", "value": "wallieweb.nl"}],
"authorizations": [".../acme/authz/364048313/6442591403"],
"finalize": ".../acme/finalize/364048313/53206661313"
}
Per domeinnaam krijg je een authorization: de vraag om te bewijzen dat je die naam beheert. De order heeft een eigen levenscyclus: pending tot alle authorizations geldig zijn, dan ready, na het indienen van de aanvraag processing en tot slot valid. Gaat er onderweg iets mis, dan wordt het invalid. De order verliep in mijn geval na zeven dagen.
De challenge: bewijs dat het domein van jou is
In de authorization staan challenges, verschillende manieren om het bewijs te leveren. De testserver bood er vier: http-01, dns-01, tls-alpn-01 en de nieuwere dns-persist-01, waarbij het TXT-record niet bij elke vernieuwing hoeft te veranderen. De eerste drie hadden hetzelfde token van 43 tekens. In base64url is dat 256 bits, ruim boven de 128 bits die de RFC als minimum eist.
Het antwoord op elke challenge begint met de key authorization: het token, een punt, en een SHA-256-vingerafdruk van je publieke accountsleutel. Daardoor hoort het bewijs bij jouw account. Iemand anders die hetzelfde token ziet, kan er met zijn eigen sleutel niets mee.
http-01
De client zet de key authorization in een bestand op de webserver, op een vaste plek:
http://wallieweb.nl/.well-known/acme-challenge/aEKUp4cqCYzy6U2zIoIfwo9tswb_kP7Tqr2fa105kDQ
Daarna laat de client met een lege POST op de challenge-URL weten dat hij klaar is. Let's Encrypt haalt het bestand altijd op via poort 80. Redirects volgt het tot tien keer, maar alleen naar http of https op poort 80 of 443. Dat is handig, want wallieweb.nl stuurt /.well-known/acme-challenge/ met een 301 door naar https, en dat mag gewoon. Wildcardcertificaten zoals *.wallieweb.nl kun je met http-01 niet krijgen.
dns-01
Hier zet je een TXT-record onder _acme-challenge. plus de domeinnaam. De waarde is niet de key authorization zelf, maar de base64url-gecodeerde SHA-256-hash ervan. Bij mij:
_acme-challenge.wallieweb.nl. TXT "SzuJk42JH-YTC3t8sizi4f5QWFAQ0mYgpfw1r5DzVNI"
Dit is de enige van de drie klassieke methodes waarmee je een wildcard krijgt. Het werkt ook voor servers die niet vanaf het internet bereikbaar zijn, zoals een homelab achter NAT. Je kunt _acme-challenge met een CNAME naar een andere zone laten wijzen. Let's Encrypt raadt dat ook aan, want een DNS-API-sleutel met volledige rechten op je webserver vergroot de schade bij een inbraak flink.
tls-alpn-01
De derde variant werkt via poort 443. De server laat bij een TLS-verbinding met het speciale ALPN-protocol acme-tls/1 een tijdelijk certificaat zien. Daarin staat de hash van de key authorization in een aparte extensie. Weinig clients ondersteunen dit, en wildcards kan het ook niet.
Hoe Let's Encrypt de controle uitvoert
Een aanvaller die het verkeer naar jouw server tijdelijk omleidt, bijvoorbeeld met een gekaapte BGP-route, zou de http-01-check zelf kunnen beantwoorden. Daarom controleert Let's Encrypt sinds februari 2020 vanaf meerdere netwerkplekken tegelijk: vanuit het eigen datacenter en vanaf externe meetpunten. Een omleiding van één pad is dan niet meer genoeg.
Vóór de uitgifte kijkt de CA ook naar CAA-records in DNS. Daarin staat welke CA's voor een domein mogen uitgeven. In de directory van Let's Encrypt staat daarvoor "caaIdentities": ["letsencrypt.org"]. google.com staat alleen pki.goog toe. wallieweb.nl heeft geen CAA-record, en dan geldt er geen beperking.
Afronden: CSR insturen en certificaat ophalen
Zijn alle authorizations geldig, dan stuurt de client een CSR naar de finalize-URL. Daarin staan de publieke sleutel die in het certificaat komt en precies dezelfde namen als in de order. De RFC houdt dat sleutelpaar los van de accountsleutel, en die laatste is de gevoeligste: wie de accountsleutel steelt, kan volgens de RFC met bestaande authorizations certificaten laten uitgeven, ze intrekken en je account overnemen. Te vroeg indienen mag niet. Ik probeerde het terwijl de order nog pending was en kreeg een 403 met orderNotReady: Order's status ("pending") is not acceptable for finalization. Na een geslaagde finalize staat er in de order een certificate-URL waar je de keten ophaalt.
Wanneer vernieuwen?
Het profiel classic geeft nu certificaten van 90 dagen uit, tlsserver van 45 dagen en shortlived van 160 uur. Op 10 februari 2027 gaat classic naar 64 dagen en op 16 februari 2028 naar 45 dagen. De tijd dat een geslaagde authorization opnieuw gebruikt mag worden, daalt in dezelfde stappen: van 30 dagen naar 10 dagen en daarna naar 7 uur.
Wanneer je moet vernieuwen, vertelt de CA je zelf via ACME Renewal Information (RFC 9773). Met een gewone GET vraag je een vernieuwingsvenster op, op basis van de sleutel-ID van de uitgever en het serienummer. Voor het huidige certificaat van deze site, geldig van 21 september tot 20 december:
{"suggestedWindow": {"start": "2026-11-19T09:53:55Z", "end": "2026-11-21T05:04:44Z"}}
Dat venster begint na 59 van de 90 dagen, met nog ongeveer 31 dagen te gaan. Een Retry-After van 23.683 seconden, ruim zes en een half uur, zegt wanneer je opnieuw moet kijken. Volgens de RFC kan een CA het venster naar voren schuiven, bijvoorbeeld vlak voor een massale intrekking. Clients zonder ARI raadt Let's Encrypt aan te vernieuwen op twee derde van de looptijd.
Zelf proberen
Een nonce ophalen kan zonder account:
curl -4 -sI https://acme-v02.api.letsencrypt.org/acme/new-nonce | grep -i replay-nonce
replay-nonce: GcZg_iwVf7ScMCWpRwRZoWyBY5DKlWvuB_66MF6v--jFORgiws8
Het vernieuwingsvenster van een certificaat vraag je ook zonder account op. Bereken eerst de ID uit het certificaat (bewaard als cert.pem):
python3 -c "
from cryptography import x509; import base64
c = x509.load_pem_x509_certificate(open('cert.pem','rb').read())
aki = c.extensions.get_extension_for_class(x509.AuthorityKeyIdentifier).value.key_identifier
s = c.serial_number; sb = s.to_bytes((s.bit_length() + 8) // 8, 'big')
b = lambda x: base64.urlsafe_b64encode(x).rstrip(b'=').decode()
print(b(aki) + '.' + b(sb))"
uyDKRwv-1-Wc-Y8JKqOMN0WxvNg.Bb_b3sqXDvfy9DHw4rs5QbD2
curl -4 -s https://acme-v02.api.letsencrypt.org/acme/renewal-info/uyDKRwv-1-Wc-Y8JKqOMN0WxvNg.Bb_b3sqXDvfy9DHw4rs5QbD2
Wil je de hele flow zien zonder iets kapot te maken, gebruik dan de staging-directory https://acme-staging-v02.api.letsencrypt.org/directory. De meeste clients hebben daar een optie voor. Mijn eigen script was 56 regels Python met de cryptography-bibliotheek.
Tot slot
Wat me verraste, is hoe weinig er nodig is. Mijn script maakte op de testserver binnen 1,2 seconden een account aan, zonder e-mailadres en zonder iets anders dan een sleutelpaar en een vinkje bij de voorwaarden. Al het vertrouwen zit in de challenge. Daarom gaat de meeste moeite van Let's Encrypt naar het controleren van die ene HTTP-request of dat ene TXT-record vanaf meerdere plekken, en veel minder naar wie er om het certificaat vraagt.