Skip to content

feat(sensitive): step-ca as the tier's own CA, issuing to Caddy over ACME (#130) - #432

Merged
Gerrrt merged 7 commits into
mainfrom
gerrrt/step-ca-certificate-authority-893481
Sep 10, 2026
Merged

Gerrrt merged 7 commits into
mainfrom
gerrrt/step-ca-certificate-authority-893481

Conversation

@Gerrrt

@Gerrrt Gerrrt commented Sep 9, 2026

Copy link
Copy Markdown
Owner

Towards #130. Second in the tier's build order, after #129's foundation.

The premise was wrong, and it was measured before deciding

The foundation commit (and its README, and the roadmap) said step-ca would be an intermediate beneath the lab CA so that nothing is re-pointed. gen-certs.sh mints that root with pathlen:0. Trial against a throwaway root shaped by the same openssl line, in the pinned step-ca image:

Step Result
step ca init --root ca.pem --key ca-key.pem … Succeeds, mints an intermediate
openssl verify on the intermediate alone OK
A leaf beneath it, verified through the chain error 25 at 2 depth lookup: path length constraint exceeded

Every client here is Go's crypto/x509 and enforces the same. ADR-0035 records the measurement, counts the cost of re-rooting the estate instead (Grafana ×2, the lab guest via the Mac, every device that imported ca.pem), and decides the tier gets a root of its own — the audiences differ (household devices vs the operator), the precedent is set (.sops.yaml, ADR-0020), and a compromised trinity then forges only what trusts the tier's root.

What the issue asked, answered

  • Replace or beneath? Neither: a CA of its own, minted on the monitoring host. The estate's CA is untouched.
  • Root key handling. Cold on the monitoring host, never on trinity — ca.json never references it (checked by the script), the bundle that ships is built by naming files and --install refuses one carrying the root key. Encrypted at rest with STEPCA_PASSWORD, which lives in the tier's SOPS file that the monitoring host cannot decrypt, so using the root is a two-host operation on purpose. Backed up with the age key's offline copy; loss costs a re-root, not an outage, because the intermediate issues for its whole lifetime without it. Putting it in git under SOPS is rejected — that is the artefact that was purged from history.
  • ACME for Caddy. cert_issuer acme in the Caddyfile, tls-alpn-01 only (80 stays unpublished, ADR-0012), seven-day leaves — the lifetime is the outage budget between step-ca dying and handshakes failing, and 24h gives a weekend nothing. Every served name is also a network alias of Caddy, because step-ca validates by dialling the name from inside the compose network.
  • gen-certs.sh and the runbook. Rescoped, not retired: they are the estate's CA, Grafana does not speak ACME. The runbook opens with the two-CA table; pathlen:0 is commented as deliberate; build-the-tier-ca.md is the tier's procedure; render-config.sh's error no longer names the command that would mint a third CA on trinity.

Proved, not assumed

Booted on the monitoring host under a throwaway compose project (TIER_CA_PROJECT) against a throwaway root: step-ca healthy, Caddy obtained a seven-day leaf for trinity.matrix.elysium over tls-alpn-01, the handshake verified against tier-ca.pem with Verify return code: 0, /healthz and the 404 answered, only 443 listening. Two things that first boot found, which the foundation never had a chance to: step ca init writes absolute paths into ca.json, so the tree must be minted at /home/step; and step-ca's binary carries the NET_BIND_SERVICE file capability, so cap_drop: [ALL] alone makes the exec fail with operation not permitted — it keeps that one capability now, with the measurement in the comment.

make validate passes in full.

Security review

  • Adds no inter-VLAN rule — step-ca is unpublished; Caddy reaches it on the compose network
  • No credential in a tracked path — the tree and bundle land under gitignored certificates/; the script proves the bundle holds no root key; check-tracked-artefacts.sh and the gitleaks PEM rule stand behind it
  • No new device

Left open

🤖 Generated with Claude Code

Gerrrt and others added 7 commits September 9, 2026 23:41
…ACME (#130)

The foundation commit said step-ca would be an intermediate beneath the lab
CA, so nothing would be re-pointed. It was written before anyone read the
root: gen-certs.sh mints it with pathlen:0, and a leaf beneath any
intermediate of it fails "path length constraint exceeded" — measured with
the pinned step-ca image against a throwaway root shaped by the same openssl
line. ADR-0035 records the measurement, counts the cost of re-rooting the
estate instead, and decides the tier gets a root of its own: the audiences
are different (household devices versus the operator), the precedent is
already set (.sops.yaml and ADR-0020 give separate trust separate keys), and
a compromised trinity then forges only what trusts the tier's root.

What this adds:

- scripts/tier-ca.sh and `make tier-ca`: --mint runs `step ca init` in the
  pinned image on the monitoring host, adds the ACME provisioner offline
  (tls-alpn-01 only, seven-day leaves), proves the result (chain verifies,
  root is a CA, ca.json carries the expected claims and only /home/step
  paths, the bundle holds no root key), and writes a bundle for trinity;
  --install populates the step-ca-data volume from it with compose's labels
  so `make up` adopts the volume silently, and writes certificates/tier-ca.pem.
  The root key never leaves the monitoring host; --install refuses a bundle
  that carries it.
- Caddyfile: a global `cert_issuer acme` block against step-ca's directory,
  trusting the tier's root; one site block per name; the catch-all keeps
  /healthz and the 404; fallback_sni for the healthcheck's SNI; the redirect
  listener on 80 disabled since 80 is not published.
- compose.yaml: Caddy mounts only the tier's root and carries a network
  alias for every name it serves — step-ca validates the challenge by
  dialling the name from inside the compose network. step-ca keeps
  NET_BIND_SERVICE: the binary ships with that file capability and the
  kernel refuses to exec it against a bounding set without it (the first
  boot failed on "operation not permitted"; the foundation never booted).
- render-config.sh's missing-certificates error is stack-aware, so on
  trinity it no longer names the command that would mint a third CA.
- gen-certs.sh and generate-certificates.md are rescoped to the estate's CA,
  with the two-CA table up front and pathlen:0 commented as deliberate;
  build-the-tier-ca.md is the tier's procedure; successor-handover.md names
  both keys and the seven-day outage budget.

Proved end to end on the monitoring host under a throwaway compose project:
step-ca healthy, Caddy obtained a seven-day leaf for trinity.matrix.elysium
over tls-alpn-01, the handshake verified against tier-ca.pem, only 443
listening. Every check in `make validate` passes.

Left for the host (#404): the real mint and install. Filed #426 for a
TLS-expiry rule sized for seven-day leaves — the estate's would page
permanently.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…icate-authority-893481

# Conflicts:
#	README.md
#	stacks/sensitive/Caddyfile
#	stacks/sensitive/README.md
#	stacks/sensitive/compose.yaml
… into gerrrt/step-ca-certificate-authority-893481

# Conflicts:
#	README.md
#	scripts/render-config.sh
…AdGuard Home and Immich on the ACME shape

Both landed on the hand-issued-leaf shape this branch retires. Each keeps
its route as a site block of its own and gains a Caddy alias, the SAN
prose goes, and Immich's README paragraph now names the tier's root rather
than the estate's ca.pem. Main's Caddyfile had lost the Immich route in its
own merges while its README still promised https://immich.matrix.elysium;
the block is restored here against immich-server:2283.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…Paperless-ngx on the ACME shape

Its route becomes a site block of its own with a Caddy alias; the SAN prose
goes with the leaf it described.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…Vaultwarden on the ACME shape

Site block of its own, an alias on Caddy, and the SAN prose goes with the
leaf it described.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…icate-authority-893481

# Conflicts:
#	README.md
@Gerrrt
Gerrrt merged commit dabd8da into main Sep 10, 2026
4 checks passed
@Gerrrt
Gerrrt deleted the gerrrt/step-ca-certificate-authority-893481 branch September 10, 2026 06:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant