docs: README + concepts + features reflect CRL/OCSP responder bundle

Audit pass against cowork/crl-ocsp-responder-prompt.md found three
operator-facing docs still describing the pre-bundle CRL/OCSP surface
(GET-only OCSP, CA-key-direct signing, no scheduler-driven cache). Each
claim updated below was ground-truthed against repo HEAD before edit.

README.md
  * Standards & Revocation table — CRL row now mentions
    scheduler-pre-generated cache (CERTCTL_CRL_GENERATION_INTERVAL,
    crl_cache table); OCSP row mentions GET + POST forms, dedicated
    responder cert per RFC 6960 §2.6, id-pkix-ocsp-nocheck per
    §4.2.2.2.1, 7d auto-rotation grace.
  * Revocation paragraph — corrected the 'Embedded OCSP responder'
    one-liner to call out the dedicated-responder-cert design (the CA
    private key is never used directly for OCSP signing, which is the
    load-bearing security property for the future PKCS#11/HSM driver
    path) and added the link to the relying-party guide.

docs/concepts.md
  * CRL paragraph — added the scheduler pre-generation + singleflight
    coalescing detail. Kept the existing 24h validity claim (verified
    against internal/connector/issuer/local/local.go:956 — 'NextUpdate:
    now.Add(24 * time.Hour)').
  * OCSP paragraph — corrected the description so it covers both GET
    and POST forms (POST per RFC 6960 §A.1.1 is what production
    clients use: Firefox, OpenSSL s_client -status, cert-manager,
    Intune); added the dedicated-responder-cert + nocheck-extension +
    auto-rotation explanation; cross-link to docs/crl-ocsp.md.

docs/features.md
  * Revocation Infrastructure section — CRL Endpoint, OCSP Responder,
    new Admin Cache Observability subsection, new GUI Revocation
    Endpoints Panel subsection. Corrected the previously-wrong 'Signs
    with the issuing CA key' OCSP claim — the bundle's load-bearing
    security improvement is exactly that the CA key is NOT used
    directly. Cross-link to crl-ocsp.md.
  * Local CA env vars table — added all four new
    CERTCTL_CRL_GENERATION_INTERVAL / CERTCTL_OCSP_RESPONDER_KEY_DIR
    (with the prod 'MUST set' callout) / _ROTATION_GRACE / _VALIDITY
    rows. Closes the G-3 'env var defined in Go but never documented'
    drift that broke CI on commit 0ffd9ea.
  * Migrations table — added 000019_crl_cache and 000020_ocsp_responder
    rows so the table reflects the bundle's persisted surface area;
    also clarified the table is illustrative + pointed readers at
    'ls migrations/*.up.sql' for the full sequence (the table had
    drifted behind reality at 000010 even before this bundle).

docs/architecture.md was already updated in commit 0a548aa with the
same content scope, so no further architecture edits.

Verification:
  * Local G-3 set difference: empty (Go-defined ∖ docs-mentioned for
    CRL/OCSP env vars).
  * 24h CRL validity claim verified against local.go:956 NextUpdate.
  * Migration numbers verified against 'ls migrations/000019* 000020*'.
  * id-pkix-ocsp-nocheck OID verified against
    internal/connector/issuer/local/ocsp_responder.go:60.
This commit is contained in:
certctl-copilot
2026-04-29 03:20:44 +00:00
parent 0a548aa1d6
commit 63d6ed256d
3 changed files with 33 additions and 8 deletions
+2 -2
View File
@@ -218,9 +218,9 @@ certctl implements revocation using three complementary mechanisms:
**Bulk Revocation** (Fleet-Level Incident Response): For large-scale incidents like CA compromise or team infrastructure decommissioning, `POST /api/v1/certificates/bulk-revoke` revokes all certificates matching filter criteria in a single operation. Filter by profile, owner, team, agent group, or issuer to target the affected certificate set. This is essential for incident response — instead of revoking certificates one-by-one, operators can revoke an entire fleet in minutes. Bulk revocation creates individual revocation jobs that reuse the existing revocation pipeline, ensuring every certificate is audited and notifications are sent.
**Certificate Revocation List (CRL)**: certctl serves DER-encoded X.509 CRLs per issuer at `GET /.well-known/pki/crl/{issuer_id}` (RFC 5280 §5 wire format, RFC 8615 well-known namespace). The endpoint is unauthenticated so any relying party — browser, TLS client, hardware appliance — can fetch it without a certctl API key. The CRL is signed by the issuing CA's key and has 24-hour validity; clients can download it periodically to check revocation status offline. The response carries `Content-Type: application/pkix-crl`.
**Certificate Revocation List (CRL)**: certctl serves DER-encoded X.509 CRLs per issuer at `GET /.well-known/pki/crl/{issuer_id}` (RFC 5280 §5 wire format, RFC 8615 well-known namespace). The endpoint is unauthenticated so any relying party — browser, TLS client, hardware appliance — can fetch it without a certctl API key. The CRL is signed by the issuing CA's key and has 24-hour validity; clients can download it periodically to check revocation status offline. The response carries `Content-Type: application/pkix-crl`. The CRL is **pre-generated** by a scheduler-driven loop (`crlGenerationLoop`, default interval 1 hour, configurable via `CERTCTL_CRL_GENERATION_INTERVAL`) and persisted in the `crl_cache` table — HTTP fetches read from the cache rather than rebuilding per request, so a busy CA does not DOS itself at scale. Concurrent regeneration requests for the same issuer are coalesced via an in-tree singleflight gate.
**OCSP Responder**: For real-time revocation checking, certctl includes an embedded OCSP responder at `GET /.well-known/pki/ocsp/{issuer_id}/{serial}` (RFC 6960). Like the CRL endpoint, it is unauthenticated and returns signed OCSP responses (good, revoked, or unknown) with `Content-Type: application/ocsp-response`, so clients can verify certificate status without downloading the full CRL.
**OCSP Responder**: For real-time revocation checking, certctl includes an embedded OCSP responder serving both forms RFC 6960 §A.1.1 defines: `GET /.well-known/pki/ocsp/{issuer_id}/{serial}` (URL-path lookup, useful for ops curl-debugging) and `POST /.well-known/pki/ocsp/{issuer_id}` with a binary `application/ocsp-request` body (the form most production clients use — Firefox, OpenSSL `s_client -status`, cert-manager, Intune device-state validators). Both forms are unauthenticated and return signed OCSP responses (good, revoked, or unknown) with `Content-Type: application/ocsp-response`. OCSP responses are signed by a **dedicated per-issuer OCSP responder cert** (RFC 6960 §2.6 / §4.2.2.2) — NOT by the CA private key directly — that carries the `id-pkix-ocsp-nocheck` extension (RFC 6960 §4.2.2.2.1) so OCSP clients do not recursively check the responder cert's own revocation status. The responder cert auto-rotates within 7 days of expiry (configurable via `CERTCTL_OCSP_RESPONDER_ROTATION_GRACE`), letting the responder key live on disk or rotate frequently while the CA key stays cold. See [`crl-ocsp.md`](crl-ocsp.md) for endpoint examples (curl, OpenSSL, Firefox, Intune) and the responder cert lifecycle.
Short-lived certificates (those assigned to profiles with TTL under 1 hour) are exempt from CRL and OCSP — their rapid expiry is considered sufficient revocation. This is a deliberate design choice to reduce infrastructure overhead for ephemeral machine-to-machine credentials.