03 §12a: trust in Proxmox by the root CA copy is built, not released (R-1380); R-1396 filed; red-proofs

This commit is contained in:
admin committed 2026-11-14 16:38:44 +01:00
1 parent fe8247665d
commit d809a1d444
5 files changed
+194 -14

No files matched your search

+59 -12
View File
@@ -956,21 +956,68 @@ argument for §3's root-minimization and a small, auditable agent.
the same name**; a node certificate is not made from a CA that ends in less than 14 days. Read from the code, not
forced.
`[DESIGN — proposed, not built]` Two ways. The operator's ruling of 2026-11-11 13:17 (`09` §3 decision 297) names the
first; the spike points to the second, so the choice is back with the operator (`STATUS.md` D80).
**The ruling (D80, `09` §3 decision 303, operator 2026-11-14):** way B — the agent trusts Proxmox through a copy of the
box's own root CA.
| | A — the agent follows the fingerprint | B — the agent trusts the box's own root CA (**CC's pick**) |
`[FACT — built, not released]` (felhom-agent `main` after v0.174.0, the installer on `main` after `installer-v1.36.1`;
2026-11-14 night; **no box has run it** — the proof on a box is a forced new certificate on demo-hp, twice.)
**1. The root step that keeps the copy** — `felhom-os-apply`, host-layer mode `pve-ca-copy`. It copies exactly
`/etc/pve/pve-root-ca.pem` to exactly `/etc/felhom-agent/pve-root-ca.pem` (0644 root — a CA certificate is public),
only if the source is ONE certificate with `CA:TRUE` that has not ended; written whole or not at all; „same" when
nothing changed. The plan names nothing (T1); no source (T2); not one CA certificate (T3). **On a BYO host it runs
too:** the bundle's policy keeps the OWNER'S settings out of our hands (the sshd drop-in is appliance-only), and this
copy is the agent's own trust file in the agent's own folder — it changes nothing of the owner's.
**2. The move of a box that exists** — `internal/pvetrust`, at the agent's start, after a config bundle install, on a
timer (hourly until moved, daily after), and on every call to Proxmox that fails on trust:
| Step | What | If it fails |
|---|---|---|
| How | A root helper reads the node certificate after a mismatch and gives the agent the new fingerprint | The installer puts a copy of `/etc/pve/pve-root-ca.pem` where the agent can read it, sets `ca_file`, leaves the fingerprint empty |
| New agent code | yes: the helper, a sudo rule, the re-pin logic, its tests | none for the trust itself (the key exists and is proven) |
| Trust | one exact certificate | every certificate this box's own CA signs; the CA's key is root-only on the same box |
| Next hand step | none, if the helper is right | none until the copy's own end date (10 years from install); the copy must be refreshed after Proxmox renews the CA |
| Boxes that exist | one root step each (the signed config bundle) | the same |
| 1 | the root step makes or refreshes the copy | nothing changes; cause `ca_copy_unavailable` |
| 2 | **the proof:** one real call to Proxmox with the copy ALONE, while the pinned fingerprint is still the configured trust | nothing is written, the fingerprint stays; cause `ca_copy_does_not_verify` (no cause when Proxmox did not answer at all — asked again within the hour) |
| 3 | ONE write of `agent.json`: `proxmox.tls.ca_file` set, `fingerprint` cleared, every other key kept; read back and checked | the old bytes are put back, the fingerprint stays; cause `config_not_written` |
| 4 | the RUNNING client takes the new trust (`proxmox.Client.SetTLS`) — no restart | it keeps the old trust until the next start |
Why B: it is the standard way to trust a private CA, it is proven on a box, and it removes the failure with no new
privileged code. What B still needs before it is built: the root step that refreshes the copy (and a test that an
old copy raises an alarm that names the cause), and a rule for what the agent does if both keys are set.
Whichever way is built, the mismatch must raise an alarm that names the cause.
**A box is never left with neither way working:** the fingerprint is cleared only after a call worked with the copy.
**Who writes the config:** the agent itself. `agent.json` is the agent's own file (0600) in a root-owned folder, so it
is rewritten in place after a recovery copy (`agent.json.pre-pve-trust`) was parked in the agent's state folder — the
same way the backup-target move and the PBS seed write it. No root step touches it. Never moved: an operator's own
`ca_file`, a box with `insecure_skip_verify`, a config that is not a file.
**3. The installer** (`resolve_pve_trust`): a new box gets the copy, `ca_file`, and NO fingerprint — after a TLS
handshake to `127.0.0.1:8006` verified with the copy alone (no system roots, the IP checked). If the source is not one
CA certificate, the copy cannot be written, or the handshake does not verify, the box gets the pinned certificate as
before, and the agent moves by itself later.
**4. The cause is named** (`proxmox.TrustProblem`): `pinned_cert_changed`, `ca_mismatch`, `cert_expired`,
`ca_file_unreadable`, `name_mismatch`, and from the move: `ca_copy_unavailable`, `ca_copy_does_not_verify`,
`ca_copy_ends_soon` (30 days), `config_not_written`. Each is an ERROR line in the agent's journal and rides the host
report as the `proxmox_trust` stanza (`mode`, `problem`, `detail`, `ca_not_after`, `ca_days_left`, `moved_at`).
**Two gaps, both in R-1396:** the hub does not read the stanza yet (no operator alarm from it), and a box that is
fully blind sends no host report at all, so that case still reaches the operator only as „host stale".
**5. Both keys set.** The order in `proxmox.TLSConfig.build` is unchanged: skip-verify, then the fingerprint, then
`ca_file`, then the system's roots. **A set fingerprint wins over a CA file.** So: the move clears the fingerprint
LAST, in the same write that sets `ca_file`; the installer writes a fingerprint only when the copy was not proven; and
a config that holds both is a pinned box — the agent treats it as „not moved" and runs the move.
**What changes for a pinned box when Proxmox makes a new certificate:** the first failed call names
`pinned_cert_changed`, runs the order above, and the next call works — the box is blind for one report cycle at most,
not until a person repairs it. `runbooks/RUNBOOK-agent-proxmox-pin-repair.md` stays the hand repair for an agent older
than this.
**The root CA's own renewal** (same key, same name, when under two years are left): the daily run refreshes the copy,
proves it and reloads it in the running client. The old copy keeps verifying until its own end date, so nothing is
urgent. Read from Proxmox's code and proven against a test CA, **not forced on a box**.
`[NOT PROVEN]` Everything on a box. Named for the attended session: a new box by the installer (CA only); an old box
moves at the agent's start; a forced new certificate on a moved box (no failed call) and on a pinned box (one failed
cycle, then healed); the wrapper mode on a BYO host; the torn-write case of step 3 (a power cut inside one small
write — the parked copy is the hand recovery, as for every other writer of this file).
`[DESIGN — the other way, not chosen]` A — the agent follows the fingerprint through a root helper after a mismatch:
new privileged code, a sudo rule and re-pin logic; trust stays on one exact certificate.
## 13. Open items / what this unblocks