mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 16:41:36 +00:00
shankar0123
9bc845304e
Wires up the actual challenge-validation machinery so profiles in
acme_auth_mode='challenge' resolve end-to-end. After this commit,
cert-manager 1.15+ with `solver: http01: ingress` against a
challenge-mode profile completes a real HTTP-01 flow and gets a cert.
DNS-01 + TLS-ALPN-01 share the same code path with the appropriate
validator selection.
Architecture (the load-bearing parts):
- 3 separate semaphore-bounded worker pools (one per challenge type),
so HTTP-01 and DNS-01 can't starve each other under load. Default
weight 10 per type; tunable via CERTCTL_ACME_SERVER_HTTP01_CONCURRENCY,
DNS01_CONCURRENCY, TLSALPN01_CONCURRENCY.
- 30s per-challenge timeout (configurable via PoolConfig.PerChallengeTimeout).
- HTTP-01 validator runs validation.IsReservedIPForDial (newly
exported wrapper preserving the existing private impl byte-for-byte
for the network scanner + ValidateSafeURL paths) on the resolved
IP — both at the initial dial and every redirect hop. SSRF probes
into private IP space are refused before the connect.
- DNS-01 validator uses a dedicated resolver pointed at
CERTCTL_ACME_SERVER_DNS01_RESOLVER (default 8.8.8.8:53) — does
NOT use the system resolver to keep behavior deterministic across
deployments. Wildcard handling: `*.example.com` queries
_acme-challenge.example.com.
- TLS-ALPN-01 validator (RFC 8737) connects with ALPN `acme-tls/1`,
inspects the id-pe-acmeIdentifier extension (OID 1.3.6.1.5.5.7.1.31),
asserts the ASN.1 OCTET STRING value equals SHA-256 of the key
authorization. Cert chain is intentionally NOT validated
(InsecureSkipVerify=true is correct per RFC 8737 — the proof is
in the extension, not the chain). Documented in docs/tls.md L-001
table + the //nolint:gosec comment carries the justification.
SSRF guard: same posture as HTTP-01.
- Validation is asynchronous: handler accepts the POST and returns
200 immediately with status=processing; the worker-pool fires a
callback that updates challenge → authz → order in a fresh
background-context WithinTx. The order auto-promotes to `ready`
when ALL authzs become valid; auto-fails to `invalid` when ANY
authz becomes invalid.
What ships:
- internal/api/acme/challenge.go: KeyAuthorization (RFC 8555 §8.1) +
DNS01TXTRecordValue (§8.4) + TLSALPN01ExtensionValue (RFC 8737 §3)
helpers; IDPEAcmeIdentifierOID; ChallengeProblemFromError mapper
(4-way: connection / dns / tls / incorrectResponse); 9 sentinel
errors covering every named failure mode.
- internal/api/acme/validators.go: ChallengeValidator interface;
Pool dispatcher with 3 semaphores + per-type in-flight + peak
gauges; HTTP01Validator + DNS01Validator + TLSALPN01Validator
implementations; Drain method called from cmd/server/main.go's
shutdown sequence.
- internal/api/acme/validators_test.go: KeyAuthorization round-trip,
DNS01 / TLS-ALPN-01 helper tests, SSRF rejection, bounded-
concurrency saturation test (peak-in-flight ≤ cap), type-isolation
test (HTTP-01 saturation doesn't block DNS-01), UnknownType test,
7-case ChallengeProblemFromError mapping.
- internal/repository/postgres/acme.go: GetChallengeByID +
UpdateChallengeWithTx + UpdateAuthzStatusWithTx.
- internal/service/acme.go: SetValidatorPool wires the *acme.Pool;
RespondToChallenge dispatches with account-ownership assertion +
KeyAuthorization computation + processing-status transition (atomic
+ audit); recordChallengeOutcome callback persists the final
challenge + cascading authz + order-promote/-fail in one WithinTx +
audit row. 4 new metrics.
- internal/api/handler/acme.go: Challenge handler; round-trips
account.JWKPEM through ParseJWKFromPEM to recover the *jose.JSONWebKey
the validator pool needs.
- internal/api/router/router.go + openapi_parity_test.go +
api/openapi-handler-exceptions.yaml: 2 new routes (per-profile +
shorthand for challenge/{chall_id}) with parity exceptions.
- cmd/server/main.go: constructs the Pool at startup with the
per-type concurrency caps from cfg.ACMEServer; ACMEService.ValidatorPool()
accessor exposed for the shutdown drain sequence.
- internal/validation/ssrf.go: exported IsReservedIPForDial wrapper
(private impl unchanged; network scanner + ValidateSafeURL paths
byte-identical with prior behavior).
- docs/tls.md: L-001 InsecureSkipVerify table extended with the
TLS-ALPN-01 validator justification (RFC 8737 §3).
- docs/acme-server.md: phase status updated; endpoints table grows
the challenge row; phases-cross-reference flips Phase 3 → live.
Tests:
- 80%+ coverage on the new files.
- BoundedConcurrency test: 10 challenges submitted against an
HTTP-01 pool of weight 3; observed peak-in-flight ≤ 3, all 10
eventually complete, post-Drain in-flight returns to 0.
- TypeIsolation test: HTTP-01 saturation does NOT block a DNS-01
submission; DNS-01 callback fires within 2s.
- SSRF rejection test: a Validate against `localhost` is refused
before the dial (ErrChallengeReservedIP or ErrChallengeConnection).
Engineering history: cowork/WORKSPACE-CHANGELOG.md "ACME-Server-3".
83 lines
4.8 KiB
YAML
83 lines
4.8 KiB
YAML
# Routes registered in internal/api/router/router.go that are intentionally
|
|
# NOT in api/openapi.yaml. Each entry needs a one-line `why:` justification.
|
|
# Adding a new entry requires PR-time review.
|
|
#
|
|
# OpenAPI-shaped REST endpoints belong in api/openapi.yaml, NOT here.
|
|
# This list is for protocol-shaped (SCEP wire endpoints) and operational
|
|
# (health, metrics, pprof) routes only.
|
|
#
|
|
# Per ci-pipeline-cleanup bundle Phase 9 / frozen decision 0.11.
|
|
|
|
documented_exceptions:
|
|
- route: "GET /scep"
|
|
why: "SCEP wire-protocol endpoint per RFC 8894 §3.1; serves CA certs via GetCACert/GetCACaps query params, NOT a REST resource."
|
|
- route: "POST /scep"
|
|
why: "SCEP wire-protocol endpoint per RFC 8894 §3.1; receives PKCSReq / RenewalReq PKIMessages, NOT a REST resource."
|
|
- route: "GET /scep/"
|
|
why: "SCEP wire-protocol endpoint with trailing-slash variant; ChromeOS clients send the trailing-slash form."
|
|
- route: "POST /scep/"
|
|
why: "SCEP wire-protocol endpoint with trailing-slash variant; ChromeOS clients send the trailing-slash form."
|
|
- route: "GET /scep-mtls"
|
|
why: "SCEP-mTLS sibling endpoint per ci-pipeline-cleanup-prerequisite EST RFC 7030 hardening Phase 6.5; same wire-protocol semantics, mutually-authenticated TLS variant."
|
|
- route: "POST /scep-mtls"
|
|
why: "SCEP-mTLS sibling endpoint, POST variant."
|
|
- route: "GET /scep-mtls/"
|
|
why: "SCEP-mTLS sibling endpoint, trailing-slash variant."
|
|
- route: "POST /scep-mtls/"
|
|
why: "SCEP-mTLS sibling endpoint, trailing-slash POST variant."
|
|
|
|
# ACME server (RFC 8555 + RFC 9773 ARI) — wire-protocol surface.
|
|
# Like SCEP/EST, ACME is a JWS-signed-JSON wire protocol whose
|
|
# semantics are dictated by the RFC, not by an OpenAPI schema.
|
|
# Documenting every endpoint in openapi.yaml would duplicate
|
|
# RFC 8555 §7.1 + §7.2 + §7.3 with no information gain. The
|
|
# canonical operator-facing reference is docs/acme-server.md.
|
|
# Phases 2-4 will extend this list as new-order, finalize, authz,
|
|
# challenge, cert, key-change, revoke-cert, renewal-info routes land.
|
|
- route: "GET /acme/profile/{id}/directory"
|
|
why: "ACME server RFC 8555 §7.1.1 directory; documented in docs/acme-server.md."
|
|
- route: "HEAD /acme/profile/{id}/new-nonce"
|
|
why: "ACME server RFC 8555 §7.2 new-nonce; documented in docs/acme-server.md."
|
|
- route: "GET /acme/profile/{id}/new-nonce"
|
|
why: "ACME server RFC 8555 §7.2 new-nonce GET form; documented in docs/acme-server.md."
|
|
- route: "POST /acme/profile/{id}/new-account"
|
|
why: "ACME server RFC 8555 §7.3 new-account (JWS jwk); documented in docs/acme-server.md."
|
|
- route: "POST /acme/profile/{id}/account/{acc_id}"
|
|
why: "ACME server RFC 8555 §7.3.2 + §7.3.6 (JWS kid) account update + deactivation; documented in docs/acme-server.md."
|
|
- route: "GET /acme/directory"
|
|
why: "ACME server default-profile shorthand; mirrors per-profile when CERTCTL_ACME_SERVER_DEFAULT_PROFILE_ID is set."
|
|
- route: "HEAD /acme/new-nonce"
|
|
why: "ACME server default-profile shorthand for new-nonce HEAD."
|
|
- route: "GET /acme/new-nonce"
|
|
why: "ACME server default-profile shorthand for new-nonce GET."
|
|
- route: "POST /acme/new-account"
|
|
why: "ACME server default-profile shorthand for new-account."
|
|
- route: "POST /acme/account/{acc_id}"
|
|
why: "ACME server default-profile shorthand for account update + deactivation."
|
|
|
|
# Phase 2 — orders + finalize + authz + cert.
|
|
- route: "POST /acme/profile/{id}/new-order"
|
|
why: "ACME server RFC 8555 §7.4 new-order; documented in docs/acme-server.md."
|
|
- route: "POST /acme/profile/{id}/order/{ord_id}"
|
|
why: "ACME server RFC 8555 §7.4 order POST-as-GET; documented in docs/acme-server.md."
|
|
- route: "POST /acme/profile/{id}/order/{ord_id}/finalize"
|
|
why: "ACME server RFC 8555 §7.4 finalize; documented in docs/acme-server.md."
|
|
- route: "POST /acme/profile/{id}/authz/{authz_id}"
|
|
why: "ACME server RFC 8555 §7.5 authz POST-as-GET; documented in docs/acme-server.md."
|
|
- route: "POST /acme/profile/{id}/challenge/{chall_id}"
|
|
why: "ACME server RFC 8555 §7.5.1 challenge response; dispatches to Phase 3 validator pool."
|
|
- route: "POST /acme/profile/{id}/cert/{cert_id}"
|
|
why: "ACME server RFC 8555 §7.4.2 cert download; documented in docs/acme-server.md."
|
|
- route: "POST /acme/new-order"
|
|
why: "Phase 2 default-profile shorthand for new-order."
|
|
- route: "POST /acme/order/{ord_id}"
|
|
why: "Phase 2 default-profile shorthand for order POST-as-GET."
|
|
- route: "POST /acme/order/{ord_id}/finalize"
|
|
why: "Phase 2 default-profile shorthand for finalize."
|
|
- route: "POST /acme/authz/{authz_id}"
|
|
why: "Phase 2 default-profile shorthand for authz POST-as-GET."
|
|
- route: "POST /acme/challenge/{chall_id}"
|
|
why: "Phase 3 default-profile shorthand for challenge response."
|
|
- route: "POST /acme/cert/{cert_id}"
|
|
why: "Phase 2 default-profile shorthand for cert download."
|