Skip to content

Document revoking a compromised key in step-ca #576

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
miguelangel-nubla wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Document revoking a compromised key in step-ca #576

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions step-ca/renewal.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
29 changes: 29 additions & 0 deletions step-ca/revocation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
Expand Down