Skip to content

Document how fast a revocation takes effect #579

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

Open
tashian wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document how fast a revocation takes effect #579

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
3 changes: 2 additions & 1 deletion certificate-manager/basic-ops.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,9 +106,10 @@ And short-lived certificates encourage certificate automation and on-demand work

If your security model demands active revocation, Certificate Manager Advanced Authorities support CRL and OCSP.
Advanced Authorities use a pull model to implement OCSP and CRL:
a revocation service periodically queries the CA for revoked certificates and builds a CRL,
one time each day, a revocation service queries the CA for revoked certificates and builds a CRL,
which is signed and shipped to a cloud bucket.
OCSP responses are built, signed, and served on-demand.
See [How fast a revocation takes effect](./how-it-works.mdx#how-fast-a-revocation-takes-effect).

Whether you're using passive or active revocation, the process for revoking a certificate is the same.

Expand Down
14 changes: 14 additions & 0 deletions certificate-manager/how-it-works.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,20 @@ $ TOKEN=$(step ca token --provisioner jwk-provisioner --revoke $SERIAL)
$ step ca revoke --token $TOKEN $SERIAL
```

#### How fast a revocation takes effect

Smallstep records a revocation immediately. The time until a system refuses the certificate depends on the method that the system uses to check it.

**OCSP.** The OCSP responder reads the current status for each request. A new request gets the `revoked` status a short time after the revocation. Each OCSP response has a `Next Update` time that is 24 hours after the response. A system that caches OCSP responses can continue to accept a revoked certificate until that time, unless you clear its cache.

**CRL.** Smallstep makes each CRL again one time each day, at 00:00 UTC. A revocation is not in the CRL until the subsequent run is complete. Each CRL has a `Next Update` time that is 24 hours after its issue. Thus a system that uses only the CRL can continue to accept a revoked certificate for up to 24 hours, and for longer if it caches the CRL.

If a revocation must take effect quickly:

- Use OCSP, not the CRL, on the system that checks the certificate.
- Find how long that system caches OCSP responses, and how to clear the cache.
- Use short-lived certificates. The certificate lifetime is the upper limit for all of these delays.

## Observability & alerting

Certificate Manager is designed to support large, rapidly evolving
Expand Down
Loading