diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md index 839453ca..2a770671 100644 --- a/docs/swarm/ca.md +++ b/docs/swarm/ca.md @@ -45,7 +45,7 @@ siblings of the hive domain — `forge.`, not `forge.`. The hive CA's leaf is a **single-label** wildcard over the hive's own domain, so it can't cover them. -That leaf is issued by the secret store's `pki` mount instead, from a +The secret store's `pki` mount issues that leaf instead, from a root generated inside it. `swarm-services-cert.service` logs in with this host's services-issuer certificate, calls `pki/issue/swarm-services`, and writes the result to @@ -54,20 +54,20 @@ copies from. Every hive does this with its own identity, so holding the swarm root's private key stopped being what decides whether a hive can serve its swarm's names. -The role's `allowed_domains` is read from the same -`services.hyperhive.swarm.serviceDomains` the SANs are built from, so -asking for a name nobody configured is a refusal from the store naming -that name — not a certificate quietly issued for it. +The same `services.hyperhive.swarm.serviceDomains` that builds the SANs +also populates the role's `allowed_domains`, so asking for a name nobody +configured is a refusal from the store naming that name — not a +certificate quietly issued for it. **The root's public certificate is a file, on every hive:** `/var/lib/hive-tls/swarm-services-root.pem` (0644), written beside the leaf it signed and folded into `trust-bundle.pem`. On the host running -the store it is also at -`/var/lib/swarm-bao-services-pki/services-root.pem`. That is the file to -hand a browser, and no store login is needed to read it — which matters, +the store it's also at +`/var/lib/swarm-bao-services-pki/services-root.pem`. That's the file to +hand a browser, and reading it needs no store login — which matters, because every store listener demands a client certificate. -**The root is generated once and never again.** The granting unit asks +**The granting unit generates the root once, and never again.** It asks the mount whether it already has an issuer (`bao list pki/issuers`) before calling `pki/root/generate/internal`, so a rebuild or a reboot re-asserts the role and the grant without touching the anchor. A root diff --git a/docs/swarm/secrets.md b/docs/swarm/secrets.md index 65facb85..743242d2 100644 --- a/docs/swarm/secrets.md +++ b/docs/swarm/secrets.md @@ -45,7 +45,7 @@ neither is a renaming of the other. | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | swarm root CA cert | `swarm-ca.nix` first-boot unit, when the operator sets `autoConfigure` | `/var/lib/swarm-ca/root.pem` | operator copies the **cert** in; it's public | | swarm root CA key | same unit | `/var/lib/swarm-ca/root-key.pem`, `0600` | stays on whichever host holds it — see the constraint below | -| swarm-services root CA (cert + key) | `swarm-bao.nix`'s granting unit, inside the store's `pki` mount | the **key** never leaves the mount; the **cert** is published at `/var/lib/swarm-bao-services-pki/services-root.pem` (0644) and at `/var/lib/hive-tls/swarm-services-root.pem` on every hive | nothing to copy — every hive receives the cert with the leaf it asks the store for | +| swarm-services root CA (cert + key) | `swarm-bao.nix`'s granting unit, inside the store's `pki` mount | the **key** never leaves the mount; the **cert** lands at `/var/lib/swarm-bao-services-pki/services-root.pem` (0644) and at `/var/lib/hive-tls/swarm-services-root.pem` on every hive | nothing to copy — every hive receives the cert with the leaf it asks the store for | | authelia session, JWT and storage-encryption keys | authelia's first-boot unit, in-container | `/var/lib/authelia-swarm/{session,jwt,storage-encryption}.key` | generated in place; nothing outside that container reads them | | authelia OIDC HMAC key | same unit | `/var/lib/authelia-swarm/oidc-hmac.key` | same | | authelia OIDC issuer key (RSA) | same unit | `/var/lib/authelia-swarm/oidc-issuer.key` | same — relying parties verify against the **public** half at `/jwks.json` |