From 445cbc7f33f9d346f4172f34bc91a5913d820630 Mon Sep 17 00:00:00 2001 From: Miguel Angel Nubla Date: Mon, 2 Nov 2026 00:15:49 +0100 Subject: [PATCH] Document revoking a compromised key in step-ca A revocation with reason keyCompromise also revokes the certificate's key (smallstep/certificates#2838): renewals of any certificate with it, rekeys to it and new certificates for it are refused. New section on the revocation page, and a pointer from renewal after expiry, where it matters most. --- step-ca/renewal.mdx | 2 ++ step-ca/revocation.mdx | 29 +++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/step-ca/renewal.mdx b/step-ca/renewal.mdx index 6d61cb01..82255717 100644 --- a/step-ca/renewal.mdx +++ b/step-ca/renewal.mdx @@ -416,6 +416,8 @@ This is not the default behavior, but it's useful if you have devices with intermittent network connectivity. The device will be able to renew its certificate the next time it has network access, provided the certificate has not been revoked. +If a device's key is compromised, [revoke the key](./revocation.mdx#revoking-a-compromised-key), not only one certificate: +otherwise its other certificates can still be renewed. To configure renewal after expiry for a provisioner, pass the `--allow-renewal-after-expiry` flag to the [`step ca provisioner`](../step-cli/reference/ca/provisioner) management commands. See [managing provisioners](./provisioners.mdx#managing-provisioners). diff --git a/step-ca/revocation.mdx b/step-ca/revocation.mdx index 4efce0a8..58e8f976 100644 --- a/step-ca/revocation.mdx +++ b/step-ca/revocation.mdx @@ -178,6 +178,35 @@ $ step ca revoke --offline --cert localhost.crt --key localhost.key Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked. ``` +### Revoking a compromised key + +A renewal keeps the key of the certificate it renews. +Revoking one certificate therefore doesn't stop someone who holds its private key +from renewing another certificate with the same key: +one renewed from it, or an earlier one. +With [renewal after expiry](./renewal.mdx#renewal-after-expiry-for-intermittently-connected-devices) enabled, +even expired certificates with that key can still be renewed. + +To revoke the key itself, revoke any one of its certificates with the reason code `keyCompromise` (1): + +```shell-session nocopy +$ step ca revoke --reasonCode=1 --reason="laptop stolen" 59636004850364466675608080466579278406 +Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked. +``` + +The CA records the certificate's public key as revoked, and from then on it refuses: + +- renewals of any certificate with that key, valid or expired +- rekeys to that key +- new certificates for that key + +The CA finds the key from the certificate it stored when it issued it, +so this needs the CA's database. +Other reason codes revoke only the certificate, as before. +Use them when a certificate is replaced but its key stays in use. + +There's no way to undo a key revocation. + ### Further reading - [Good Certificates Die Young](https://smallstep.com/blog/passive-revocation/)