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

Free lesson

How the ACME protocol works

After this lesson: I can describe the steps of an ACME order from account to downloaded certificate.

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

ACME gets a certificate with nobody typing

ACME, the Automatic Certificate Management Environment, is the protocol a program uses to get a certificate from a CA with no person involved. It is defined in RFC 8555.

Without it, a 47-day certificate means a person renewing every few weeks, for every name. With it, renewal is a job that runs by itself.

By the end of this lesson

Note

I can describe the steps of an ACME order from account to downloaded certificate.

Key words

WordWhat it means
Directorythe CA's list of ACME addresses
Accounta key pair the CA knows the client by
Ordera request for one certificate and its names
Authorisationthe CA's record of proving one name
Finalizesending the signing request once every name is proven
CSRa certificate signing request holding the public key

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

Everything starts at the directory

A client is given one address, the directory. It reads it and finds every other address there. They say where to get a nonce, make an account, place an order, revoke and change keys.

A nonce is a number used once. Every request carries a fresh one, so an old request cannot be sent again by somebody else.

Read the lab CA's directory

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.

What the directory lists

Name in the replyWhat the client uses it for
newNonceGet a fresh nonce before a request
newAccountRegister the account key
newOrderAsk for a certificate for some names
revokeCertSay a certificate must not be trusted any more
keyChangeSwap the account key for a new one

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

An order moves through five states

Every request is signed with the account key. The client places an order for some names. Each name gets an authorisation, which offers challenges.

The order is pending until every name is proven, then ready. The client finalizes with a CSR, and the order is processing, then valid. A failed proof makes it invalid.

Print one recorded order step by step

Command
docker exec python python3 steps/order.py

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

What the recorded order shows

StepStateWhat happened
1 new-accountaccount validThe client's key is now an account
2 new-orderorder pendingAsks for a certificate for shop
3 and 4 authorization, challengepending, then processingThe client says: come and look
5 authorizationvalidThe CA fetched the proof and it matched
6 to 8 order, finalize, orderready, processing, validThe CSR is signed
9 certificateissuedThe client downloads the chain

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

A common mistake

Warning

Many people think the CA makes the server's key and sends it. The client makes its own key pair and sends only the public half, inside the CSR. The private key never leaves the server.

Now place a real order

The client container has the step command, told where the CA is and which root to trust. The next Run makes an account, orders a certificate for the name client, proves it with http-01 and finalizes.

It prints done! for the challenge, the wait for ready and the finalize step, then names client.crt and client.key.

Order a certificate for client

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.

Look at what you were given

Command
docker exec client step certificate inspect client.crt --short

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

Your certificate, in short

The short view names Subject: client, Issuer: Lab Private CA Intermediate CA and Provisioner: acme, with your own serial and dates a day apart.

The shop did the same by itself when it started. Run docker logs shop in the terminal to see its account, order, challenge and finalize lines. Its times and ids are its own.

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.