Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

ACME challenges: HTTP-01 and DNS-01

After this lesson: I can work out the value an HTTP-01 or DNS-01 challenge publishes and say which challenge a name needs.

65 min lesson3 commandsCertificate automation lab: ACME, short-lived TLS certificates and automatic renewal with a private CA

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

WordWhat it means
Thumbprinta short hash that stands for the account key
Key authorisationthe CA's value, a full stop and the thumbprint
HTTP-01a proof served on port 80 at a fixed path
DNS-01a proof published in a TXT record
TXT recorda DNS record that holds plain text
Wildcarda 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

Command
docker exec python python3 steps/challenges.py

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

What the model prints

LineWhat it means
key authorisation: e8Kq2LvX0n4RcT7wYb1mPz9hJd3s.jW5aL0b7Qm3x...The CA's value, a full stop, the thumbprint
http://shop.example/.well-known/acme-challenge/e8Kq2LvX0n4RcT7wYb1mPz9hJd3sWhere HTTP-01 is fetched
_acme-challenge.shop.example TXT vmbbIVBfAfWejbz8l4MJmQwQ6JlM5mjoPCqB4qPA2HwThe DNS-01 record
43 charactersA SHA-256 hash in base64url, no padding
*.shop.example dns-01 onlyA 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 situationChallengeWhy
shop.example on a public web serverHTTP-01Port 80 is already open
*.shop.exampleDNS-01A wildcard can only be proven in DNS
A staff server not reachable from outsideDNS-01The CA never connects to it
Port 80 blocked, port 443 openTLS-ALPN-01A 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

Command
docker exec client step ca certificate bank bank.crt bank.key --provisioner acme --standalone

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Ask for a name somebody else serves

Command
docker exec client step ca certificate shop mine.crt mine.key --provisioner acme --standalone

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

What the two failures print

NameLast lineWhat happened
bankUnable to validate challenge: The server could not connect to validation targetNobody answered on port 80
shopUnable to validate challenge: The server will not issue certificates for the identifierCaddy answered, not your client, so the proof was wrong

The cells students fill in are left blank in this preview.

About this lab and its source: Certificate automation lab: ACME, short-lived TLS certificates and automatic renewal with a private CA

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.