diff --git a/docs/migration/acme-from-caddy.md b/docs/migration/acme-from-caddy.md index de2b589..b115d05 100644 --- a/docs/migration/acme-from-caddy.md +++ b/docs/migration/acme-from-caddy.md @@ -158,7 +158,7 @@ psql -c "SELECT actor, action, resource_id FROM audit_events legitimately high throughput. - **Caddy logs `urn:ietf:params:acme:error:rejectedIdentifier`** → the SAN list includes an identifier the certctl profile policy - rejects. Cross-reference [`docs/acme-server.md` § Troubleshooting](./acme-server.md#certificate-readyfalse-with-rejectedidentifier). + rejects. Cross-reference [`docs/acme-server.md` § Troubleshooting](../reference/protocols/acme-server.md#certificate-readyfalse-with-rejectedidentifier). - **`badNonce` in Caddy logs** → clock skew or multi-replica certctl without sticky sessions; same fix as the cert-manager walkthrough. diff --git a/docs/migration/acme-from-cert-manager.md b/docs/migration/acme-from-cert-manager.md index ac64a5e..9ab0023 100644 --- a/docs/migration/acme-from-cert-manager.md +++ b/docs/migration/acme-from-cert-manager.md @@ -75,7 +75,7 @@ curl -X POST https://certctl-test.default.svc.cluster.local:8443/api/profiles \ ``` Auth-mode tradeoffs are covered in -[`docs/acme-server.md` § Auth-mode decision tree](./acme-server.md#auth-mode-decision-tree). +[`docs/acme-server.md` § Auth-mode decision tree](../reference/protocols/acme-server.md#auth-mode-decision-tree). For first-time deployments, `trust_authenticated` is the right default. ## Step 3 — Capture the certctl bootstrap CA @@ -94,7 +94,7 @@ cat deploy/test/certs/ca.crt | base64 -w0 Capture the output for Step 4. This is **the** single biggest first- time-deploy footgun on the cert-manager integration path. The reference recipe lives in -[`docs/acme-server.md` § TLS trust bootstrap](./acme-server.md#tls-trust-bootstrap-read-this-before-configuring-cert-manager). +[`docs/acme-server.md` § TLS trust bootstrap](../reference/protocols/acme-server.md#tls-trust-bootstrap-read-this-before-configuring-cert-manager). ## Step 4 — Apply the ClusterIssuer @@ -229,7 +229,7 @@ psql -c "SELECT created_at, action, resource_type, resource_id ## Common failure modes These are operator-side; full troubleshooting reference is in -[`docs/acme-server.md` § Troubleshooting](./acme-server.md#troubleshooting). +[`docs/acme-server.md` § Troubleshooting](../reference/protocols/acme-server.md#troubleshooting). - `400 Bad Request: badNonce` → clock skew between certctl-server and cert-manager, or a multi-replica certctl fleet without sticky diff --git a/docs/reference/connectors/index.md b/docs/reference/connectors/index.md index 1701ae4..ceba2d1 100644 --- a/docs/reference/connectors/index.md +++ b/docs/reference/connectors/index.md @@ -813,16 +813,16 @@ issued, SCEP-issued certs). See: -- [ACME Server Reference](./acme-server.md) — env-var reference, +- [ACME Server Reference](../protocols/acme-server.md) — env-var reference, endpoints, auth-mode decision tree, RFC 8555 conformance statement, troubleshooting, FAQ. -- [cert-manager Walkthrough](./acme-cert-manager-walkthrough.md) — kind +- [cert-manager Walkthrough](../../migration/acme-from-cert-manager.md) — kind → cert-manager → certctl-server → Certificate flow. -- [Caddy Walkthrough](./acme-caddy-walkthrough.md) — Caddyfile `acme_ca` +- [Caddy Walkthrough](../../migration/acme-from-caddy.md) — Caddyfile `acme_ca` + trust configuration. -- [Traefik Walkthrough](./acme-traefik-walkthrough.md) — `certificatesResolvers` +- [Traefik Walkthrough](../../migration/acme-from-traefik.md) — `certificatesResolvers` + `serversTransport.rootCAs`. -- [Threat Model](./acme-server-threat-model.md) — JWS forgery +- [Threat Model](../protocols/acme-server-threat-model.md) — JWS forgery resistance, nonce store integrity, HTTP-01 SSRF, DNS-01 cache posture, TLS-ALPN-01 chain-not-validated rationale, rate-limit tuning, audit trail. diff --git a/docs/reference/protocols/acme-server-threat-model.md b/docs/reference/protocols/acme-server-threat-model.md index c09960a..f0d5b50 100644 --- a/docs/reference/protocols/acme-server-threat-model.md +++ b/docs/reference/protocols/acme-server-threat-model.md @@ -270,7 +270,7 @@ Documented to set scope expectations for security reviewers: ## See also - [`docs/acme-server.md`](./acme-server.md) — operator-facing reference. -- [`docs/tls.md`](./tls.md) — TLS posture, including the L-001 +- [`docs/tls.md`](../../operator/tls.md) — TLS posture, including the L-001 table of `InsecureSkipVerify` justifications (TLS-ALPN-01 row). - [`internal/api/acme/jws.go`](../internal/api/acme/jws.go) — verifier source. diff --git a/docs/reference/protocols/acme-server.md b/docs/reference/protocols/acme-server.md index 4c7857d..dd02041 100644 --- a/docs/reference/protocols/acme-server.md +++ b/docs/reference/protocols/acme-server.md @@ -12,9 +12,9 @@ external PKI vendors today. > **Phase status (2026-05-03):** Phase 6 — full operator-facing > reference. The functional surface is complete (Phases 1a-5); this > doc is the canonical procurement-readability reference. New: client- -> walkthrough docs for [cert-manager](./acme-cert-manager-walkthrough.md), -> [Caddy](./acme-caddy-walkthrough.md), and -> [Traefik](./acme-traefik-walkthrough.md); a dedicated +> walkthrough docs for [cert-manager](../../migration/acme-from-cert-manager.md), +> [Caddy](../../migration/acme-from-caddy.md), and +> [Traefik](../../migration/acme-from-traefik.md); a dedicated > [threat model](./acme-server-threat-model.md); a section-by-section > RFC 8555 + RFC 9773 conformance statement; a 5-failure-mode > troubleshooting playbook; a tested-clients version pinning table. @@ -600,7 +600,7 @@ Yes. The endpoints are HTTPS over the certctl-server's listener (port Posh-ACME on a Mac all integrate against `https://:8443/acme/profile//directory`. The TLS-trust-bootstrap requirement applies the same way — see the -[Caddy walkthrough](./acme-caddy-walkthrough.md) for the OS-trust-store +[Caddy walkthrough](../../migration/acme-from-caddy.md) for the OS-trust-store recipe. ### How do I migrate manually-issued certs to ACME-issued ones? @@ -640,9 +640,9 @@ Read before writing a security review. ## See also -- [cert-manager integration walkthrough](./acme-cert-manager-walkthrough.md) -- [Caddy integration walkthrough](./acme-caddy-walkthrough.md) -- [Traefik integration walkthrough](./acme-traefik-walkthrough.md) +- [cert-manager integration walkthrough](../../migration/acme-from-cert-manager.md) +- [Caddy integration walkthrough](../../migration/acme-from-caddy.md) +- [Traefik integration walkthrough](../../migration/acme-from-traefik.md) - [Threat model](./acme-server-threat-model.md) - [TLS trust bootstrap reference](./tls.md) - [Architecture (control-plane)](./architecture.md)