gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-11 23:28:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: production hardening II — DR runbook + crl-ocsp updates + features.md env vars (Phase 10)

Browse Source 
Production hardening II Phase 10 — operator-facing documentation
that codifies the new V2 surfaces shipped in Phases 1-8.

NEW docs/disaster-recovery.md (8 sections, ~280 lines):
  - Overview of automatic fail-safes already in code
  - CRL cache recovery (delete row + scheduler regenerates)
  - OCSP responder cert recovery (delete row + ensureOCSPResponder
    re-bootstraps on next request)
  - OCSP response cache recovery (delete row + read-through fallback)
  - CA private-key rotation procedure (9-step playbook)
  - Postgres restore (with explicit list of operator-managed
    artifacts NOT in DB)
  - Trust-bundle reload semantics (SCEP / EST / Intune SIGHUP-
    equivalent fail-safe behavior)
  - DR checklist (printable; pin near on-call)

This is the SOC 2 / PCI procurement-team deliverable. Auditors and
on-call operators get a single document that tells them what to do
when state corrupts, when keys need rotation, when Postgres needs
restoring. Nothing in the runbook requires new code — it codifies
behaviors already in the codebase.

UPDATED docs/crl-ocsp.md:
  - New "Production hardening II additions" section: OCSP nonce
    extension, OCSP pre-signed cache (with the load-bearing security
    wire called out), per-source-IP OCSP rate limit, per-actor cert-
    export rate limit, CRL HTTP caching headers (RFC 7232), CRL
    DistributionPoints auto-injection, cert-export typed audit
    codes, per-area Prometheus metrics with operator alert
    recommendations.
  - Pruned the V3-Pro deferral list to remove items that this
    bundle SHIPPED (OCSP rate-limiting moved out; remaining V3-Pro:
    delta CRLs, OCSP stapling, OCSP request signature verification,
    HA / multi-region replication, IDP extension for sharded CRLs).

UPDATED docs/features.md:
  - CERTCTL_OCSP_RATE_LIMIT_PER_IP_MIN row (default 1000)
  - CERTCTL_CERT_EXPORT_RATE_LIMIT_PER_ACTOR_HR row (default 50)

G-3 docs-drift CI guard reproduced clean: every new CERTCTL_* env
var documented in features.md AND consumed in Go source. S-1 stale-
counts guard clean (no literal-number prose for current-state
counts in README/docs).
This commit is contained in:
shankar0123
2026-04-30 05:19:56 +00:00
parent efce2363f7
commit 67593604f1
3 changed files with 445 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features.md
+2
View File
@@ -413,6 +413,8 @@ Self-signed or sub-CA mode using `crypto/x509`.
| `CERTCTL_OCSP_RESPONDER_KEY_DIR` | (none) | **Operator MUST set in production.** Directory where the FileDriver persists each issuer's OCSP responder key (`ocsp-responder-<issuer_id>.key`). When unset, the responder service uses a temporary directory that does NOT survive restarts — fine for dev, NEVER for prod. |
| `CERTCTL_OCSP_RESPONDER_ROTATION_GRACE` | `7d` | When the responder cert's `NotAfter` falls within this window, `EnsureResponder` rotates to a fresh cert+key on the next OCSP request or scheduler tick. |
| `CERTCTL_OCSP_RESPONDER_VALIDITY` | `30d` | How long each newly-issued responder cert is valid for. Short by design: relying parties cache OCSP responses, not the responder cert chain, and `id-pkix-ocsp-nocheck` blocks recursive revocation checking on the responder itself. |
| `CERTCTL_OCSP_RATE_LIMIT_PER_IP_MIN` | `1000` | **Production hardening II Phase 3.** Per-source-IP cap on OCSP requests per minute. Zero disables the limit. Trip returns the canonical OCSP "unauthorized" status (RFC 6960 §2.3) plus `Retry-After: 60`. The limiter does NOT honor `X-Forwarded-For` (OCSP is publicly reachable; spoofed headers would bypass the cap). |
| `CERTCTL_CERT_EXPORT_RATE_LIMIT_PER_ACTOR_HR` | `50` | **Production hardening II Phase 3.** Per-actor cap on cert-export requests (PEM + PKCS#12) per hour. Zero disables. Trip returns HTTP 429 + JSON `{"error":"rate_limit_exceeded","retry_after_seconds":3600}` plus `Retry-After: 3600`. Defends against bulk-export from a compromised admin token. |
Sub-CA mode validates `IsCA=true` and `KeyUsageCertSign` on the loaded certificate. Falls back to self-signed when paths are not set. Supports CRL generation (`GenerateCRL`) and OCSP response signing (`SignOCSPResponse`). All CA-key signing flows through the `signer.Signer` interface (`internal/crypto/signer/`); the OCSP responder cert is signed by the CA via the existing issuance pipeline and OCSP responses are signed by the responder key (NOT the CA key directly) per RFC 6960 §2.6.