mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 14:11:31 +00:00

Files

T

shankar0123 9b6294e83d auth-bundle-2 Phase 14: session + OIDC validation benchmarks (steady-state + cold paths) + auth-benchmarks.md operator doc + Makefile targets

Closes Phase 14 of cowork/auth-bundle-2-prompt.md. Ships four
benchmarks producing four numbers + the operator-doc table; three
default-tag benchmarks runnable on every CI runner, the fourth
(cold-cache OIDC) runnable on operator-side Docker hosts via the
new make target.

Files
=====

internal/auth/session/bench_test.go (NEW):
* BenchmarkSession_SteadyState (target p99 < 1ms; measured 5µs).
  Warm in-memory repo + warm session row. Pure CPU: parseCookie +
  HMAC verify + map lookup + sentinel checks.
* BenchmarkSession_ColdProcess (target p99 < 10ms; measured 7.1ms).
  Same pipeline but with a configurable per-call delay simulating
  a 1ms Postgres RTT on each repo call. Two repo calls per
  Validate (signing-key fetch + session-row fetch) = 2ms minimum;
  Go time.Sleep granularity adds ~1-2ms jitter. Documented why
  testcontainers Postgres isn't viable inside b.N: 30+ second
  container boot incompatible with per-iteration timing.
* slowSessionRepo + slowKeyRepo wrappers add the per-call delay
  via time.Sleep; they delegate to the existing in-memory stubs.
* reportPercentiles helper sorts + reports p50/p95/p99/max via
  b.ReportMetric (Go testing.B doesn't surface percentiles
  natively).

internal/auth/oidc/bench_test.go (NEW):
* BenchmarkOIDC_SteadyState (target p99 < 5ms; measured 1.5ms).
  Drives full HandleCallback against an in-process mockIdP
  (httptest.Server localhost loopback). Pre-warmed JWKS cache via
  RefreshKeys at setup. Pipeline: pre-login consume + state
  compare + token exchange (localhost ~50-200µs) + go-oidc
  Verify (RSA-2048 sig verify + alg pin) + service-layer iss/
  aud/azp/at_hash/exp/iat/nonce re-checks + group-claim
  resolution + group→role mapping + user upsert + session mint.
* The localhost-loopback /token call adds ~100-500µs of TCP
  overhead vs pure crypto; the prompt's "no network calls"
  steady-state framing accommodates this since the localhost
  loopback is the closest practical proxy for a same-region
  IdP /token call (which adds 5-15ms in production).

internal/auth/oidc/bench_keycloak_test.go (NEW, //go:build integration):
* BenchmarkOIDC_ColdCache (target p99 < 200ms; operator-runs).
  Drives RefreshKeys against a live Keycloak container from the
  Phase 10 testfixtures harness. Each iteration evicts the
  in-process cache + re-fetches discovery + re-fetches JWKS over
  real HTTP + re-runs the IdP-downgrade-attack defense.
* Network-bounded: the cold path is dominated by HTTPS RTT to
  the IdP discovery endpoint, NOT crypto. The 200ms cap
  accommodates a geographically-distant IdP (~150ms RTT) plus
  the in-process JWKS fetch + downgrade-defense logic (~5ms
  locally).
* Reuses the sharedKeycloak fixture from
  integration_keycloak_test.go (Phase 10) so the benchmark
  doesn't pay the 60-90s container boot cost separately. Skips
  with a clear message if invoked without the integration test
  setup.
* Reports p50/p95/p99/max in MILLISECONDS (vs the
  microsecond-granularity steady-state benchmarks) since the
  cold path is two orders of magnitude slower.

internal/auth/oidc/service_test.go (MODIFIED):
* Refactored newMockIdP(t *testing.T) to delegate to a new
  newMockIdPWithTB(t testing.TB) sibling. Standard Go pattern
  for sharing test fixtures between *testing.T and *testing.B.
  No behavior change for existing service_test.go tests; the
  benchmark file in bench_test.go calls newMockIdPWithTB(b)
  to get the same fixture.

docs/operator/auth-benchmarks.md (NEW):
* Result table with all four benchmarks + targets + measured
  numbers + status markers. Four-row matrix for the default-tag
  benchmarks; the fourth row (cold-cache) is operator-recorded
  with an empty cell waiting for the first Docker-equipped run.
* Hardware floor section pinning the 4 vCPU / 8 GiB RAM /
  Postgres 16 / Go 1.25 baseline. GitHub-hosted Ubuntu runners
  satisfy this; operators on weaker hardware re-record.
* "What each benchmark covers (and what it doesn't)" section
  per benchmark, distinguishing the warm steady-state pipeline
  from the cold path's network-bounded budget.
* "Cold-cache OIDC: how to run" subsection documenting the
  make target + the test+benchmark coupling needed to populate
  sharedKeycloak. Operator-recorded baseline table seeded
  empty for first runs.
* "Why the cold path is bounded by network latency, not crypto"
  section explaining the budget breakdown:
    - TCP handshake (1 RTT)
    - TLS 1.3 handshake (1-2 RTTs)
    - 2 HTTPS GETs (discovery + JWKS, 1 RTT each)
    - In-process crypto on the certctl side (~5-10ms total)
  So the 200ms cap is operator-checkable: real measurement >
  200ms means the IdP is slow OR network congestion OR DNS
  issues — the diagnosis is upstream of certctl. Real
  measurement < 200ms means the IdP is on a fast same-region
  link.
* Methodology section pinning the per-iteration timing capture
  + sort + percentile-extract approach.
* Pre-merge audit section for the Phase 14 exit gate: four
  benchmarks ran, four numbers recorded, steady-state targets
  met, cold path is operator-runnable + measurably-bounded.

Makefile (MODIFIED):
* Added `make benchmark-auth` (default-tag, runs three of four
  benchmarks at 2000 samples each).
* Added `make benchmark-auth-coldcache` (integration-tagged,
  runs OIDC cold-cache against live Keycloak; requires Docker).
* Both targets carry explanatory comment blocks.

docs/README.md (MODIFIED):
* Added the auth-benchmarks.md doc to the Operator nav table
  alongside performance-baselines.md.

Measured baselines at Phase 14 close (linux/arm64, 4 vCPU)
==========================================================

  BenchmarkSession_SteadyState     p99 = 5µs    (target < 1ms)   ✓ 200× under
  BenchmarkSession_ColdProcess     p99 = 7.1ms  (target < 10ms)  ✓
  BenchmarkOIDC_SteadyState        p99 = 1.5ms  (target < 5ms)   ✓ 3× under
  BenchmarkOIDC_ColdCache          operator-runs (Docker required)

Verification
============

* gofmt -l on three new bench files: clean.
* go vet ./internal/auth/session/... ./internal/auth/oidc/...: clean
  (default tag).
* go vet -tags integration ./internal/auth/oidc/...: clean (integration
  tag covers the bench_keycloak_test.go file).
* go test -short -count=1 across all 5 OIDC + session packages:
  green; the bench_*_test.go files compile but don't run under
  -short (testing.Short() guards + benchmarks are not selected
  by -run pattern).
* All three runnable benchmarks executed and produce the numbers
  above; recorded in auth-benchmarks.md.

2026-05-10 16:51:28 +00:00

10 KiB

Raw Blame History

certctl Documentation

Last reviewed: 2026-05-05

The full docs index, organized by audience. Pick the section that matches what you need to do; each link below opens a focused doc rather than a wall of text.

For the elevator pitch and quickstart commands, see the repo README.md at the root. For the marketing site, see certctl.io.

Getting Started

You're new to certctl, just cloned the repo, or want to understand what it does before installing.

Doc	What it covers
Concepts	TLS certificates explained for beginners — CAs, ACME, EST, private keys, the full glossary
Quickstart	Five-minute setup with Docker Compose, dashboard tour, API tour
Examples	Five turnkey scenarios — ACME+NGINX, wildcard DNS-01, private CA+Traefik, step-ca+HAProxy, multi-issuer
Advanced demo	End-to-end certificate lifecycle with technical depth at each step
Why certctl	Positioning vs ACME clients, agent-based SaaS, enterprise platforms; when to look elsewhere

Reference

You're operating certctl in production or building integrations and need authoritative technical detail.

Doc	What it covers
Architecture	System design, data flow, security model, deployment topologies
Profiles	CertificateProfile policy object — issuer wiring, EKUs, RequiresApproval gate (Phase 9 closure)
API	OpenAPI 3.1 spec, integration patterns, client SDK generation
CLI	certctl-cli command reference and CI/CD integration patterns
Configuration	`CERTCTL_*` environment variable reference (scheduler, rate limits, deploy verify, audit, agent)
MCP server	Model Context Protocol integration for AI assistants
Release verification	Cosign / SLSA / SBOM verification procedure
Intermediate CA hierarchy	Multi-level CA tree management — RFC 5280 §3.2/§4.2.1.9/§4.2.1.10 enforcement
Deployment model	Atomic write, post-deploy verify, rollback semantics across all targets
Vendor matrix	Tested vendor versions per target connector

Connectors

The connector index is the canonical catalog (interfaces, registry, scanners, plus an inline reference per built-in). Per-connector deep-dive siblings cover operator-grade material — vendor edges, troubleshooting, rotation playbooks, when-to-use vs alternatives.

Issuers (13 deep-dives): ACME · ADCS · AWS ACM Private CA · DigiCert · EJBCA / Keyfactor · Entrust · GlobalSign Atlas HVCA · Google CAS · Local CA · OpenSSL / Custom CA · Sectigo SCM · step-ca / Smallstep · Vault PKI

Targets (15 deep-dives): Apache · AWS Certificate Manager · Azure Key Vault · Caddy · Envoy · F5 BIG-IP · HAProxy · IIS · Java Keystore · Kubernetes Secrets · NGINX · Postfix / Dovecot · SSH (agentless) · Traefik · Windows Certificate Store

Protocols

Doc	What it covers
ACME server	Run certctl as an RFC 8555 + RFC 9773 ARI ACME server
ACME server threat model	Security posture for the ACME server endpoint
SCEP server	RFC 8894 native SCEP server — RA cert config, multi-profile dispatch, must-staple, mTLS sibling route
SCEP for Microsoft Intune	Intune-specific deployment guide — NDES replacement playbook
EST server	RFC 7030 EST server — 802.1X / Wi-Fi enrollment, IoT bootstrap, channel binding
CRL & OCSP	RFC 5280 CRL + RFC 6960 OCSP responder for relying parties
Async CA polling	Bounded polling for async-CA issuer connectors

Operator

You're running certctl in production and need operational guidance.

Doc	What it covers
Security posture	Auth, rate limits, encryption at rest, key rotation, RBAC primitive (Bundle 1), bootstrap
RBAC operator reference	Roles, permissions, scopes, scope-down + bootstrap flow (Bundle 1)
Auth threat model	API-key compromise, role-grant abuse, bootstrap-token leak, audit-mutation, compliance mapping (Bundle 1)
OIDC / SSO runbooks	Per-IdP setup guides — Keycloak, Authentik, Okta, Auth0, Entra ID, Google Workspace (Bundle 2)
Control plane TLS	Self-signed bootstrap, operator-supplied Secret, cert-manager Certificate CR
Database TLS	PostgreSQL transport encryption
Approval workflow	Two-person integrity gate for high-stakes issuance + Phase 9 profile-edit closure
Helm deployment	Kubernetes installation via the bundled chart
Performance baselines	Operator-runnable benchmarks for regression spot checks
Auth benchmarks	Session + OIDC validation p99 targets and measured baselines (Bundle 2 Phase 14)
Legacy clients (TLS 1.2)	Reverse-proxy runbook for embedded EST/SCEP clients on TLS 1.2

Runbooks

Runbook	When
Cloud targets	AWS ACM + Azure Key Vault deployment, debugging, rollback
Expiry alerts	Per-policy multi-channel routing matrix, severity tiers
Disaster recovery	CRL cache, OCSP responder cert, CA private-key rotation, Postgres restore

Migration

You're moving from another cert-management tool to certctl, or running both in parallel.

From	Doc
Certbot	migration/from-certbot.md
acme.sh	migration/from-acmesh.md
cert-manager (coexistence, not replacement)	migration/cert-manager-coexistence.md
Caddy ACME (point Caddy at certctl)	migration/acme-from-caddy.md
cert-manager ACME (point cert-manager at certctl)	migration/acme-from-cert-manager.md
Traefik ACME (point Traefik at certctl)	migration/acme-from-traefik.md
API keys → RBAC (v2.0.x → v2.1.0)	migration/api-keys-to-rbac.md — AUDIT YOUR API KEYS post-upgrade

Contributor

You're contributing to certctl, running tests locally, or trying to understand the CI pipeline.

Doc	What it covers
Testing strategy	What we test and why; per-PR fast gates vs daily deep-scan
Test environment	Local environment with real CAs (Pebble, step-ca, etc.)
QA prerequisites	Before running QA: stack boot, demo data baseline, env vars
QA test suite	qa_test.go reference for release QA
GUI QA checklist	Manual GUI verification pass for release
Release sign-off	Release-day checklist — code state, automated gates, manual QA, artefact verification
CI pipeline	CI shape, regression guards, adding new checks

Doc	Why archived
Upgrade to TLS (v2.2)	Pre-v2.2 HTTPS-everywhere upgrade procedure
Upgrade past v2 JWT removal	G-1 milestone JWT auth removal procedure

Reading order by role

First-time operator: Concepts → Quickstart → Examples. About 90 minutes end to end.

Production operator: Architecture → Security posture → Control plane TLS → Disaster recovery runbook. About 4 hours end to end.

PKI engineer: ACME server → SCEP server → EST server → Intermediate CA hierarchy. About 6 hours end to end.

Contributor: Architecture → Testing strategy → Test environment → CI pipeline. About 3 hours end to end.

10 KiB Raw Blame History