gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 20:21:29 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
5313cd8492c16b491d93c763dde3bf8e5b805b34
certctl/api/openapi-handler-exceptions.yaml
T
shankar0123 4dc8d3fa5b acme-server: key rollover + revocation + ARI (Phase 4/7) 
Closes the RFC 8555 + RFC 9773 surface beyond the issuance happy-path:
  - POST /acme/profile/<id>/key-change   (RFC 8555 §7.3.5)
  - POST /acme/profile/<id>/revoke-cert  (RFC 8555 §7.6)
  - GET  /acme/profile/<id>/renewal-info/<cert-id>  (RFC 9773 ARI)

After this commit, ACME clients can rotate account keys, revoke certs
through the ACME surface (rather than only via the certctl GUI/API),
and fetch ARI for proactive renewal scheduling.

Architecture:
  - Key rollover: outer JWS verified against the registered account key
    (existing kid path); the inner JWS — embedded as the outer's payload
    — verified against the embedded NEW jwk in a new dedicated routine
    (ParseAndVerifyKeyChangeInner) that enforces RFC 8555 §7.3.5
    inner-only invariants: MUST use jwk + MUST NOT use kid, payload
    .account == outer.kid, payload.oldKey thumbprint-equals registered.
    A single WithinTx swaps the stored thumbprint+pem and writes the
    audit row. Concurrent-rollover safety via SELECT…FOR UPDATE on the
    conflicting account row in UpdateAccountJWKWithTx; the loser
    observes the winner's new thumbprint and is told to retry (409).
  - Revocation: two auth paths. kid → AccountOwnsCertificate single-
    indexed COUNT lookup over acme_orders. jwk → constant-time RFC 7638
    thumbprint compare against the cert's pubkey. Both paths route
    through service.RevocationSvc.RevokeCertificateWithActor so the
    existing CRL/OCSP refresh + audit + metrics pipeline applies. RFC
    5280 §5.3.1 numeric reason codes clamp to certctl's
    domain.ValidRevocationReasons; codes 8 (removeFromCRL) + 10
    (aACompromise) clamp to 'unspecified' since they aren't in the set.
  - ARI is GET-only and unauth per RFC 9773 §4. Cert-id wire shape is
    base64url(AKI).base64url(serial); ParseARICertID strict-decodes,
    SerialHex emits the canonical certctl-shape lowercase-no-leading-
    zeros hex used in certificate_versions.serial_number.
    ComputeRenewalWindow has 3 branches: bound RenewalPolicy →
    [notAfter - days, notAfter - days/2]; no policy → last 33% of
    validity; past expiry → [now, now + 1d] (renew immediately).
    Retry-After honors CERTCTL_ACME_SERVER_ARI_POLL_INTERVAL.

What ships:
  - internal/api/acme/{keychange,ari}.go (+ phase4_test.go: 15 tests).
  - internal/api/acme/order.go: RevokeCertRequest wire shape.
  - internal/api/handler/acme.go: KeyChange, RevokeCert, RenewalInfo
    + 11 new writeServiceError mappings.
  - internal/repository/postgres/acme.go: UpdateAccountJWKWithTx (FOR
    UPDATE + expectedOldThumbprint precondition; ErrACMEAccountKey-
    ConcurrentUpdate sentinel) + AccountOwnsCertificate.
  - internal/service/acme.go: RotateAccountKey + RevokeCert +
    RenewalInfo; CertificateRevoker + RenewalPolicyLookup interfaces;
    SetRevocationDelegate + SetRenewalPolicyLookup wiring; 11 new
    sentinels; 6 new metrics.
  - internal/service/acme_phase4_test.go: service-layer tests for
    RotateAccountKey (happy + duplicate-key) + RevokeCert (kid mismatch
    + jwk mismatch + jwk happy + already-revoked + reason-clamping) +
    RenewalInfo (disabled + bad cert-id).
  - internal/api/router/router.go: 6 new register calls (3 per-profile
    + 3 shorthand). Router parity exceptions extended in lockstep
    (in-tree SpecParityExceptions + CI-only openapi-handler-exceptions
    .yaml).
  - cmd/server/main.go: SetRevocationDelegate(revocationSvc) +
    SetRenewalPolicyLookup(renewalPolicyRepo) at startup.
  - internal/config/config.go: CERTCTL_ACME_SERVER_ARI_ENABLED (default
    true) + CERTCTL_ACME_SERVER_ARI_POLL_INTERVAL (default 6h);
    BuildDirectory's ariEnabled flag now flips on under
    cfg.ARIEnabled.
  - docs/acme-server.md: phase status flipped to Phase 4; endpoints
    table grows 6 rows (3 per-profile + 3 shorthand); FAQ section
    appended explaining how to rotate keys, revoke certs, and consume
    ARI.

Tests:
  - 'go vet ./...' clean across the repo.
  - 'go test -short -count=1 ./...' green across every package.
  - phase4_test.go covers: keychange happy-path + 5 negatives +
    MapKeyChangeErrorToProblem coverage; ARI cert-id round-trip + 6
    malformed cases + BuildARICertID from a generated cert; window-
    math 3 branches.
  - service-layer tests confirm: RotateAccountKey atomically swaps the
    thumbprint (verifies persisted state) and rejects duplicate keys;
    RevokeCert routes through the stub RevocationSvc with the right
    actor string + reason on the jwk path, rejects mismatched keys,
    rejects already-revoked certs, clamps reason codes correctly;
    RenewalInfo respects ARIEnabled + cert-id format.

Engineering history: cowork/WORKSPACE-CHANGELOG.md 'ACME-Server-4'.
2026-05-03 16:51:06 +00:00

95 lines
5.6 KiB
YAML
Raw Blame History

# 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."
- route: "POST /acme/profile/{id}/key-change"
why: "ACME server RFC 8555 §7.3.5 doubly-signed key rollover; documented in docs/acme-server.md."
- route: "POST /acme/profile/{id}/revoke-cert"
why: "ACME server RFC 8555 §7.6 revoke-cert (kid OR cert-key auth); documented in docs/acme-server.md."
- route: "GET /acme/profile/{id}/renewal-info/{cert_id}"
why: "ACME server RFC 9773 ACME Renewal Information (unauthenticated GET); documented in docs/acme-server.md."
- route: "POST /acme/key-change"
why: "Phase 4 default-profile shorthand for key rollover."
- route: "POST /acme/revoke-cert"
why: "Phase 4 default-profile shorthand for revoke-cert."
- route: "GET /acme/renewal-info/{cert_id}"
why: "Phase 4 default-profile shorthand for ARI."
Reference in New Issue View Git Blame Copy Permalink