diff --git a/certificate-manager/basic-ops.mdx b/certificate-manager/basic-ops.mdx index 8c277261..8e209c05 100644 --- a/certificate-manager/basic-ops.mdx +++ b/certificate-manager/basic-ops.mdx @@ -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. diff --git a/certificate-manager/how-it-works.mdx b/certificate-manager/how-it-works.mdx index a9477ca6..ff69f013 100644 --- a/certificate-manager/how-it-works.mdx +++ b/certificate-manager/how-it-works.mdx @@ -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