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

Free lesson

Certificate Automation Basics

The whole lesson is free and interactive. Read it here, or press Start lab to run it for real in a live lab, with no account needed.

Container lab11 min read7 commands

Why does the padlock never run out?

Every website with a padlock shows a certificate, and every certificate has an end date. Soon the longest a public one may last is 47 days. Nobody renews thousands of those by hand, so a program asks for a new one before the old one runs out. This lab shows how.

By the end of this lesson

Note

I can ask a private certificate authority for a certificate over ACME and check when it needs renewing.

Key words

  • Certificate: a signed file that ties a name, such as shop, to a public key.
  • Certificate authority (CA): the service that checks a request and signs certificates.
  • ACME: the protocol a program uses to ask a CA for a certificate with no person involved.
  • Challenge: the test the CA sets to prove you control the name you asked for.
  • Chain: your certificate, then the CA certificates above it, up to a root you trust.
  • Renewal: getting a fresh certificate before the old one ends.

Starter: what you already know

Note

Answer in your head. 1. What does the S in HTTPS add? 2. Who decides that a website really is the one it says? 3. What happens when something you rely on expires and nobody notices? Answers: encryption and a check of who the server is; a certificate authority your browser trusts; it stops working, often at the worst moment.

Before you start

Note

Press Start the lab on the bar at the top of this lesson and wait until it says it is running. There are four containers, ca, shop, client and python, and the terminal reaches each with docker exec <name>, which runs one command inside it. Each Run button below types its command into your lab's terminal, one after another in the same session. To watch them, or to type your own, press Open terminal on the bar.

The CA lists its ACME addresses in a directory

An ACME client starts by reading the CA's directory, a short list of addresses. This one asks for it with curl, trusting the lab's own root. The reply names newNonce, newAccount, newOrder, revokeCert and keyChange: one address for each job. A client needs to know only the directory's address to find the rest.

Command
docker exec client curl -s https://ca:9000/acme/acme/directory --cacert /ca/certs/root_ca.crt

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

The shop already has a certificate it got by itself

Nobody gave the shop its certificate. When it started, it asked the CA over ACME and proved it controls the name shop. The first Run fetches the page over HTTPS and prints "The shop is open". The second reads the certificate: it is valid for DNS:shop, the issuer is Lab Private CA Intermediate CA, the lifetime is 24 hours and the subject is empty, because the name that counts is in the list of names.

Command
docker exec client curl -sS --cacert /ca/certs/root_ca.crt https://shop

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

Command
docker exec python python3 steps/read_shop.py

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

Check

Tip

Why does curl need --cacert here? Answer: the lab's root is not one your computer already trusts, so curl is told which root to check the chain against. Without it, it refuses with error 60.

Ask for a certificate by hand

Now you are the client. step makes an account, places an order for the name client, answers the http-01 challenge by listening on port 80 for a moment, then sends a request to sign. It prints done! for the challenge, the wait and the finish, then names the two files it wrote: client.crt and client.key. The name client works because the CA reaches this very container when it looks it up.

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

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

A name you do not control is refused

Ask for bank, a name nothing in the lab answers to. The CA tries to fetch the proof from bank, finds nobody there and stops: Unable to validate challenge: The server could not connect to validation target. No certificate is written. That refusal is the whole point of a challenge.

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.

Check whether it needs renewing

needs-renewal says yes once two thirds of the lifetime has passed. Your certificate is a minute old, so the first Run prints certificate does not need renewal. The second asks whether it ends within the next 25 hours. It ends within 24, so it prints certificate needs renewal. A renewal job asks this question on a timer and acts on the answer.

Command
docker exec client step certificate needs-renewal client.crt --verbose

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

Command
docker exec client step certificate needs-renewal client.crt --expires-in 25h --verbose

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

A common mistake

Warning

Many people think a certificate proves a website is safe or honest. It proves only that whoever holds the key controlled the name when the CA checked. That is why the check is repeated at every renewal, and why short lifetimes matter.

Exit check

Tip

Answer without looking back. 1. What does a client read first to find a CA's addresses? 2. What did the CA do to check the name client? 3. Why was bank refused? 4. When does needs-renewal say yes by default? Answers: the directory; it fetched a proof over HTTP from that name; nothing answered at that name; after two thirds of the lifetime.

For teachers

Tip

This lesson is a small example of a lesson worked in a lab: the steps and the Run buttons are the lesson, and the lab is each student's own copy. The lab is four containers: step-ca as a private CA with ACME, Caddy as a web server that gets and renews its own certificate, the step client and Python with OpenSSL. Nothing marks itself: the student hands in a short report. Key learning points: 1. ACME lets a program get a certificate with no person involved. 2. A challenge proves control of a name. 3. Renewal is due after two thirds of the lifetime. Common mistake: reading a certificate as proof that a site is honest. Serials and dates differ for every student; the lifetime does not. Equipment: the lab and a browser. Tip: ask students what would happen to the shop if its renewal stopped working today. Copy it into your own module and change it, or build one from scratch with the Lab menu in the lesson builder.

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 these lessons for your students with marking and a lab for every student.