Operations: renewal, rotation & troubleshooting
Keep a PKI healthy: automate renewal, rotate keys, revoke, and debug common errors.
A certificate is not a one-time job. It is issued, renewed, sometimes revoked, and always expires. This module runs that whole cycle on your CA from module 2, then teaches you to debug the errors you’ll see in real life.
Keep the CA running. Work in a new folder:
mkdir -p ~/pki-lab/ops && cd ~/pki-lab/opsIf you did module 5, your CA has two JWK provisioners. When step asks which one to use, pick admin@example.com.
Get a certificate to work with:
step ca certificate web.example.com web.crt web.key \ --san web.example.com --san localhostWhy lifetimes keep shrinking
Section titled “Why lifetimes keep shrinking”Short lifetimes limit the damage of a stolen key and force teams to automate. The public web is heading the same way. The CA/Browser Forum’s ballot SC-081 cut the maximum public TLS lifetime to 200 days in March 2026. It drops to 100 days in March 2027 and 47 days in March 2029. Let’s Encrypt plans to move to 64 days in 2027 and 45 days in 2028.
step-ca already defaults to 24 hours. If you can renew daily, you can handle anything the public web throws at you.
1. Ask whether a certificate needs renewal
Section titled “1. Ask whether a certificate needs renewal”step certificate needs-renewal web.crtecho $?1Exit code 1 means “not yet”. By default, a certificate needs renewal after two thirds of its lifetime. Pretend it expires within 25 hours:
step certificate needs-renewal web.crt --expires-in 25hecho $?0Exit code 0 means “renew now”. Scripts use this to decide what to do.
2. Renew by hand
Section titled “2. Renew by hand”step ca renew --force web.crt web.keyYour certificate has been saved in web.crt.No password was needed. step proved its identity with the current certificate and key, over mTLS. The CA issued a new certificate with a new serial number and new dates for the same names.
--force skips the overwrite prompt. Without it, step asks before it replaces web.crt.
3. Renew automatically
Section titled “3. Renew automatically”Run renewal as a daemon:
step ca renew --daemon web.crt web.keyINFO: 2026/11/16 04:00:34 first renewal in 15h12m46sThe daemon renews at about two thirds of the lifetime, with some random jitter. The jitter stops a fleet of machines from all hitting the CA at the same second.
A renewed certificate is useless until the service loads it. --exec runs a command after each renewal. Stop the daemon with Ctrl+C, then try a fast demo:
step ca renew --daemon --renew-period 5s \ --exec "echo reload nginx here" web.crt web.keyINFO: 2026/11/16 04:00:36 first renewal in 5sINFO: 2026/11/16 04:00:41 web.example.com certificate renewed, next in 5sreload nginx hereINFO: 2026/11/16 04:00:46 web.example.com certificate renewed, next in 5sreload nginx herePress Ctrl+C to stop it. In production, use --exec "systemctl reload nginx" or a systemd timer. The step-ca renewal docs include ready-made systemd units.
Break it: let a certificate expire
Section titled “Break it: let a certificate expire”Get a certificate with the shortest lifetime the CA allows:
step ca certificate old.example.com old.crt old.key --not-after 5mWait six minutes. Then verify it:
step certificate verify old.crt --roots $(step path)/certs/root_ca.crtfailed to verify certificate: x509: certificate has expired or is not yet valid: current time 2026-11-16T04:05:50Z is after 2026-11-16T04:05:49ZTry to renew it:
step ca renew --force old.crt old.keyThe request lacked necessary authorization to be completed: certificate expired on 2026-11-16 04:05:49 +0000 UTCRe-run with STEPDEBUG=1 for more info.An expired certificate can’t prove anything, so it can’t renew itself. You must issue a new one with the provisioner password. This is why renewal runs well before expiry, never at the last minute.
step-ca can allow late renewal with the allowRenewalAfterExpiry claim. Leave it off unless you have a strong reason.
4. Revoke a certificate (passive)
Section titled “4. Revoke a certificate (passive)”Imagine a laptop is lost. Issue a certificate to play its part:
step ca certificate laptop42.example.com laptop42.crt laptop42.keyRevoke it, using the certificate itself to authorize the request:
step ca revoke --cert laptop42.crt --key laptop42.key --reason "laptop lost"✔ CA: https://localhost:9000Certificate with Serial Number 325394138822214975015869222951509457176 has been revoked.When you don’t have the key, revoke by serial number. step asks you to pick a provisioner and enter its password instead:
step ca revoke --reasonCode KeyCompromise <serial-number>Find a serial number with step certificate inspect <file> --format json. It’s the serial_number field.
Now try to renew the revoked certificate:
step ca renew --force laptop42.crt laptop42.keyThe request lacked necessary authorization to be completed. Please see the certificate authority logs for more info.Re-run with STEPDEBUG=1 for more info.The CA’s log is clearer:
error="cahandler.Renew: authority.authorizeRenew: certificate has been revoked"But the certificate still verifies:
step certificate verify laptop42.crt --roots $(step path)/certs/root_ca.crtecho $?0This is passive revocation, step-ca’s default. The CA won’t extend the certificate, but clients don’t check with the CA. The certificate dies at its expiry time, at most 24 hours later. With short lifetimes, that’s often good enough.
5. Revoke a certificate (active, with a CRL)
Section titled “5. Revoke a certificate (active, with a CRL)”Sometimes “within 24 hours” is too slow. Active revocation means the CA publishes a signed Certificate Revocation List (CRL) and clients check it.
Two parts must agree:
- The CA publishes a CRL, and stamps it with its own address in the Issuing Distribution Point.
- Each leaf certificate carries the same address in its CRL Distribution Points extension, so clients know where to look.
Turn on the CRL
Section titled “Turn on the CRL”Open $(step path)/config/ca.json in an editor. Add this block at the top level, next to "db":
"crl": { "enabled": true, "generateOnRevoke": true, "idpURL": "https://localhost:9000/1.0/crl"},Add the CRL address to new certificates
Section titled “Add the CRL address to new certificates”Create a leaf template. It’s the step-ca default plus one line:
{ "subject": {{ toJson .Subject }}, "sans": {{ toJson .SANs }},{{- if typeIs "*rsa.PublicKey" .Insecure.CR.PublicKey }} "keyUsage": ["keyEncipherment", "digitalSignature"],{{- else }} "keyUsage": ["digitalSignature"],{{- end }} "extKeyUsage": ["serverAuth", "clientAuth"], "crlDistributionPoints": ["https://localhost:9000/1.0/crl"]}Attach it to your admin provisioner:
step ca provisioner update admin@example.com --x509-template leaf-crl.tplRestart step-ca so it picks up both changes. Then issue a new certificate:
step ca certificate laptop44.example.com laptop44.crt laptop44.keyopenssl x509 -in laptop44.crt -noout -ext crlDistributionPointsX509v3 CRL Distribution Points: Full Name: URI:https://localhost:9000/1.0/crlRevoke it and read the list
Section titled “Revoke it and read the list”step ca revoke --reasonCode KeyCompromise <laptop44-serial>step lists your JWK provisioners. Pick any of them and enter its password: any JWK provisioner can revoke any certificate.
✔ Provisioner: wifi (JWK) [kid: c703dzooi6hSNFaz00eax8xRxcQuzObfwvOAbKiInGA]✔ CA: https://localhost:9000Certificate with Serial Number 167336704577127535296999873164195410580 has been revoked.Download the CRL and read it:
curl -s --cacert $(step path)/certs/root_ca.crt https://localhost:9000/1.0/crl -o ca.crlopenssl crl -inform DER -in ca.crl -noout -textCertificate Revocation List (CRL): Version 2 (0x1) Signature Algorithm: ecdsa-with-SHA256 Issuer: O = Lab CA, CN = Lab CA Intermediate CA Last Update: Nov 16 04:01:20 2026 GMT Next Update: Nov 17 04:01:20 2026 GMT CRL extensions: X509v3 Authority Key Identifier: 1B:7A:83:36:88:1C:E2:E6:78:50:0A:39:5F:5D:68:AC:A5:7F:9B:F0 X509v3 CRL Number: 1 X509v3 Issuing Distribution Point: critical Full Name: URI:https://localhost:9000/1.0/crlRevoked Certificates: Serial Number: 7DE3E083FD99626EB860E37FF7503294 Revocation Date: Nov 16 04:01:20 2026 GMT CRL entry extensions: X509v3 CRL Reason Code: Key Compromise Serial Number: F4CCA1AE7A7CB4CC115201FCFF927918 Revocation Date: Nov 16 04:00:50 2026 GMTThe CRL lists every revoked serial in hexadecimal, including laptop42, which you revoked passively earlier. It’s signed by the intermediate, so nobody can forge it.
Check it like a client
Section titled “Check it like a client”step can fetch and check the CRL for you:
step certificate verify laptop44.crt \ --roots $(step path)/certs/root_ca.crt \ --issuing-ca $(step path)/certs/intermediate_ca.crt \ --verify-crlcertificate marked as revoked in CRL https://localhost:9000/1.0/crlOpenSSL agrees. Convert the CRL to PEM first:
openssl crl -inform DER -in ca.crl -out ca.crl.pemopenssl verify -crl_check \ -CAfile $(step path)/certs/root_ca.crt \ -untrusted $(step path)/certs/intermediate_ca.crt \ -CRLfile ca.crl.pem laptop44.crtCN = laptop44.example.comerror 23 at 0 depth lookup: certificate revokederror laptop44.crt: verification failedBreak it: a certificate without a CRL address
Section titled “Break it: a certificate without a CRL address”Check web.crt the same way. You issued it before you added the template:
openssl verify -crl_check \ -CAfile $(step path)/certs/root_ca.crt \ -untrusted $(step path)/certs/intermediate_ca.crt \ -CRLfile ca.crl.pem web.crtCN = web.example.comerror 44 at 0 depth lookup: different CRL scopeerror web.crt: verification failedThe CRL says “I cover certificates that point to this URL.” web.crt doesn’t point anywhere, so OpenSSL refuses to use the list. Renew or reissue older certificates after you turn on CRLs.
6. Troubleshoot TLS like a pro
Section titled “6. Troubleshoot TLS like a pro”openssl s_client shows exactly what a server sends. Start a throwaway test server in one terminal. It serves web.crt with the intermediate:
openssl s_server -accept 8443 -cert web.crt -key web.key \ -cert_chain $(step path)/certs/intermediate_ca.crt -wwwIn another terminal, connect and check the name:
openssl s_client -connect localhost:8443 -servername web.example.com \ -CAfile $(step path)/certs/root_ca.crt \ -verify_hostname web.example.com -brief </dev/nullCONNECTION ESTABLISHEDProtocol version: TLSv1.3Ciphersuite: TLS_AES_256_GCM_SHA384Peer certificate: CN = web.example.comHash used: SHA256Signature type: ECDSAVerification: OKVerified peername: web.example.comServer Temp Key: X25519, 253 bitsDONEVerification: OK and Verified peername are what you want. Drop -brief to see the full chain the server sent.
Break it: read the error numbers
Section titled “Break it: read the error numbers”Stop s_server with Ctrl+C. Restart it without -cert_chain, so it sends only the leaf:
openssl s_server -accept 8443 -cert web.crt -key web.key -wwwConnect again from the other terminal:
openssl s_client -connect localhost:8443 -servername web.example.com \ -CAfile $(step path)/certs/root_ca.crt \ -verify_hostname web.example.com -brief </dev/nulldepth=0 CN = web.example.comverify error:num=20:unable to get local issuer certificatedepth=0 CN = web.example.comverify error:num=21:unable to verify the first certificateCONNECTION ESTABLISHEDNotice the last line. s_client reports problems but connects anyway. Add -verify_return_error to make it stop, like a browser would. curl fails straight away:
curl -sS --cacert $(step path)/certs/root_ca.crt https://localhost:8443/curl: (60) SSL certificate problem: unable to get local issuer certificateHere are the OpenSSL errors you’ll meet most:
| Error | Meaning | Usual fix |
|---|---|---|
20: unable to get local issuer certificate |
No path to a trusted root. | Serve the intermediate. Or trust the right root. |
21: unable to verify the first certificate |
Same root cause as 20, seen on the leaf. | Serve the full chain. |
10: certificate has expired |
Outside the validity window. | Renew. Check automation and the clock. |
18: self-signed certificate |
The server sent a self-signed certificate. | Use a CA-issued certificate, or trust that exact one. |
23: certificate revoked |
Listed in the CRL. | Issue a new certificate. |
26: unsuitable certificate purpose |
Wrong Key Usage or EKU for the job. | Reissue with the right EKU. |
62: hostname mismatch |
The name isn’t in the SAN. | Reissue with the name. Check the URL. |
7. Rotate the intermediate CA
Section titled “7. Rotate the intermediate CA”Intermediates should change from time to time. Clients trust the root, so a new intermediate signed by the same root needs no client changes.
Create a new intermediate. You need the root key, so this is a rare, careful job:
step certificate create "Lab CA Intermediate CA 2" int2.crt int2.key \ --profile intermediate-ca \ --ca $(step path)/certs/root_ca.crt \ --ca-key $(step path)/secrets/root_ca_keyEnter the root key password, then choose a password for the new key. Use the same password as your CA so step-ca can start with one password.
Your certificate has been saved in int2.crt.Your private key has been saved in int2.key.step certificate inspect int2.crt --shortX.509v3 Intermediate CA Certificate (ECDSA P-256) [Serial: 1993...5668] Subject: Lab CA Intermediate CA 2 Issuer: Lab CA Root CA Valid from: 2026-11-16T04:02:18Z to: 2036-11-13T04:02:18ZMove the files into place:
cp int2.crt $(step path)/certs/intermediate_ca_2.crtcp int2.key $(step path)/secrets/intermediate_ca_2_keyIn ca.json, change "crt" and "key" to the two new paths. Restart step-ca. The root fingerprint in the startup log hasn’t changed.
Renew a certificate the old intermediate issued:
step ca renew --force web.crt web.keystep certificate inspect web.crt --bundle --shortX.509v3 TLS Certificate (ECDSA P-256) [Serial: 1919...3580] Subject: web.example.com localhost Issuer: Lab CA Intermediate CA 2 Provisioner: admin@example.com [ID: Cd7t...AS_E] Valid from: 2026-11-16T04:01:22Z to: 2026-11-17T04:02:22ZX.509v3 Intermediate CA Certificate (ECDSA P-256) [Serial: 1993...5668] Subject: Lab CA Intermediate CA 2 Issuer: Lab CA Root CA Valid from: 2026-11-16T04:02:18Z to: 2036-11-13T04:02:18ZThe renewal worked, and the new certificate comes from the new intermediate. Every client keeps working because the root is the same. Keep the old intermediate’s files until every certificate it signed has expired.
From now on, the new intermediate also signs the CRL. Pass intermediate_ca_2.crt to --issuing-ca and -untrusted when you check new certificates.
Go deeper
Section titled “Go deeper”Check yourself
Tap a card to flip it. Nothing is scored or saved.
Progress is saved in this browser only.