How a CA checks the name is yours
An ACME challenge is the test a CA sets to prove you control a domain name before it signs a certificate for it. HTTP-01 asks you to publish a value on a web address, and DNS-01 asks you to publish it in a DNS record.
Pick the wrong one and renewal fails at three in the morning.
By the end of this lesson
Note
I can work out the value an HTTP-01 or DNS-01 challenge publishes and say which challenge a name needs.
Key words
| Word | What it means |
|---|---|
| Thumbprint | a short hash that stands for the account key |
| Key authorisation | the CA's value, a full stop and the thumbprint |
| HTTP-01 | a proof served on port 80 at a fixed path |
| DNS-01 | a proof published in a TXT record |
| TXT record | a DNS record that holds plain text |
| Wildcard | a name such as *.shop.example covering one level |
The cells students fill in are left blank in this preview.
Both challenges publish a key authorisation
The CA picks a random value for each challenge. The client joins it to its account key's thumbprint with a full stop. The result is the key authorisation.
Only the holder of the account key can make it. Publishing it proves two things at once: you control the name, and you are this account.
HTTP-01 serves it on port 80
For HTTP-01 the CA fetches http://<name>/.well-known/acme-challenge/<value> on port 80. The reply must be the key authorisation.
It suits a web server that is already reachable at that name. It cannot prove a wildcard, and it fails when port 80 is closed or the name points somewhere else.
Work out both proofs in Python
docker exec python python3 steps/challenges.pyShown here, not run. Press Start lab to type it into your own lab’s terminal.
What the model prints
| Line | What it means |
|---|---|
| key authorisation: e8Kq2LvX0n4RcT7wYb1mPz9hJd3s.jW5aL0b7Qm3x... | The CA's value, a full stop, the thumbprint |
| http://shop.example/.well-known/acme-challenge/e8Kq2LvX0n4RcT7wYb1mPz9hJd3s | Where HTTP-01 is fetched |
| _acme-challenge.shop.example TXT vmbbIVBfAfWejbz8l4MJmQwQ6JlM5mjoPCqB4qPA2Hw | The DNS-01 record |
| 43 characters | A SHA-256 hash in base64url, no padding |
| *.shop.example dns-01 only | A wildcard needs DNS-01 |
The cells students fill in are left blank in this preview.
DNS-01 puts a hash in DNS
For DNS-01 the client hashes the key authorisation with SHA-256 and writes it, in base64url, as a TXT record at _acme-challenge.<name>. The CA looks the record up.
Nothing needs to be reachable from the internet, so an internal server can prove its name. It is the only challenge for a wildcard. The cost: the client needs a key to change your DNS.
Worked example: choosing a challenge
| Name or situation | Challenge | Why |
|---|---|---|
| shop.example on a public web server | HTTP-01 | Port 80 is already open |
| *.shop.example | DNS-01 | A wildcard can only be proven in DNS |
| A staff server not reachable from outside | DNS-01 | The CA never connects to it |
| Port 80 blocked, port 443 open | TLS-ALPN-01 | A third challenge, proven over TLS on 443 |
The cells students fill in are left blank in this preview.
A common mistake
Warning
Many people think HTTP-01 is checked on port 443 because the site runs HTTPS. The CA always fetches plain HTTP on port 80. Close port 80 and every HTTP-01 renewal fails, however good the HTTPS setup is.
Watch HTTP-01 fail twice
In lesson 2 the name client passed, because the CA reached the client container. Now ask for two names that are not yours.
Nothing in the lab answers to bank. The name shop answers, but the web server there is not your client, so it cannot serve your proof.
Ask for a name nothing answers
docker exec client step ca certificate bank bank.crt bank.key --provisioner acme --standaloneShown here, not run. Press Start lab to type it into your own lab’s terminal.
Ask for a name somebody else serves
docker exec client step ca certificate shop mine.crt mine.key --provisioner acme --standaloneShown here, not run. Press Start lab to type it into your own lab’s terminal.
What the two failures print
| Name | Last line | What happened |
|---|---|---|
| bank | Unable to validate challenge: The server could not connect to validation target | Nobody answered on port 80 |
| shop | Unable to validate challenge: The server will not issue certificates for the identifier | Caddy answered, not your client, so the proof was wrong |
The cells students fill in are left blank in this preview.