Renew and revoke certificates

When to use this

Use this page to know who renews what and to take a certificate out of service. Renewal is a new certificate with a new key for the same names; revocation is final and puts the serial number on the CRL of the issuing CA, the list that clients check.

• When to use this
• Renewal: who does it
• Steps: revoke in the UI
• When the CRL lists it
• Check it worked
• When it fails
• Next steps

Renewal: who does it

In the UI the successor gets the same CA, preset, subject and names, and always a new key. If the server holds the key you choose the algorithm of the new one; if the original came from a request, you paste a new request made on the device. The form also asks what happens to the old certificate (below). Over the API: POST /api/v1/certificates/{id}/renew (role operator; an API token may do it).

What happens to the old certificate is the predecessor rule. For an ACME client a completed order replaces an older valid order of the same account with the identical set of names. The tenant’s Other certificates default then applies: at once, after 1 to 30 days, or never; the factory value is seven days. For the agent the default is at once, after the new certificate is confirmed as deployed and served. An admin can change the defaults in Administration → Tenant settings and override them per ACME account or agent (§10.6). Use one account per host: hosts that share an account and the same names retire each other’s certificates. A test order counts too: a certbot renew --dry-run or an acme.sh --renew --force is a real renewal for this rule.

Steps: revoke in the UI

1. Open the certificate (Certificates) and press Revoke now. You need the role operator or admin at the issuing CA, and a fresh second factor (step 4).
2. Choose the reason. The UI offers superseded, cessationOfOperation, keyCompromise, affiliationChanged, privilegeWithdrawn and unspecified. There is no certificateHold: a revocation cannot be undone.
3. For keyCompromise you may enter Compromised since (YYYY-MM-DD or an RFC 3339 time). The key is then blocked for every later request.
4. Tick the confirmation and press Revoke. If your second factor is not fresh, the UI now sends you to the step-up page and carries out the revocation after you confirm. The message says “Revoked. The CRL of … lists it now.”

Plan revocation on the same page revokes as superseded after 1 to 30 days; Cancel planned revocation withdraws the plan before it runs. A planned revocation shows as “Revocation planned” in the lists.

Over the API the operation is POST /api/v1/certificates/{id}/revoke with a body of reason and an optional invalidity_date. It needs the second factor too, and an API token never has it, so a script with a token gets 403 (REST API). Revoke from the UI, or from the ACME client.

From an ACME client, with the account that ordered the certificate (the certificate’s own key may revoke it as well, for example after a leak, without the account):

certbot revoke --cert-path /etc/letsencrypt/live/nas.homelab.lan/cert.pem

lego certificates revoke --server https://pki.homelab.lan/acme/directory --path /var/lib/lego --email admin@homelab.lan --cert.name nas.homelab.lan --reason 4 --keep

Revoking an agent (Revoke agent) does not revoke the certificates it deployed; revoke those separately. Certificates stored as external were not issued here and cannot be revoked here.

When the CRL lists it

• At once. A revocation signs a new CRL of the issuing CA in the same step while the server is unsealed. While it is sealed, the revocation is stored and audited, and the CRL is signed at the next unseal; only then clients see it (§10.8).
• Caches. The public listener lets a CRL be cached for 15 minutes, so a client or proxy may still hold the old list for that long.
• Regular renewal. Every 15 minutes the server checks all CRLs of its online CAs and signs a new one when a third of its lifetime has passed. The default lifetime is 7 days for an intermediate and 30 days for an online root. An offline root signs its CRL on the offline machine (180 days by default) and you upload it.
• How long an entry stays. After the certificate expires, the serial remains on the CRL until its expiry plus the CA’s CRL lifetime, so that a regular CRL has listed it.
• A CRL that is not renewed is an alert (crl), see Monitoring.

Check it worked

The address of the CRL is in the certificate, and the serial number is in the certificate:

openssl x509 -in nas.homelab.lan-fullchain.pem -noout -serial -ext crlDistributionPoints

Fetch the CRL (it is DER) and print it:

curl -o issuing.crl http://pki.homelab.lan/crl/issuing/1.crl

openssl crl -inform DER -in issuing.crl -noout -text

Look for the serial under Revoked Certificates, with its revocation date and reason. Last Update, Next Update and CRL Number show when it was signed. Or let OpenSSL decide: it needs the CRL as PEM and fails with “certificate revoked” for a listed serial:

openssl crl -inform DER -in issuing.crl -out issuing.crl.pem

openssl verify -crl_check -CAfile root.pem -untrusted nas.homelab.lan-chain.pem -CRLfile issuing.crl.pem nas.homelab.lan.pem

When it fails

More in Troubleshooting.

Next steps

• Keep CRLs fresh: Monitoring; the offline root’s CRL is on the schedule of Best practices.
• Renewal of agents and what the agent reports: Adding hosts.
• Clients: certbot, lego.