alexion/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: describe the current secrets design in the install procedure

Browse Source 
The closing section still described key derivation from each machine's SSH
host key, a mechanism that was superseded because it forces new host keys
on every reimage and makes storing those keys as secrets circular.

Record the two-tier identity model that replaced it, and warn that the
hand-set bootstrap password stops working once the password becomes a
secret: hashedPasswordFile outranks every other password option, so a
machine installed after that must have its identity provisioned before
first boot rather than a password set afterwards.
This commit is contained in:
alexion
2026-07-19 16:56:36 -04:00
parent 5b3ebdccf3
commit 13e5a9bb56
1 changed files with 9 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/install.md
View File

@@ -148,6 +148,12 @@ At boot you are prompted for the LUKS passphrase from step 3; after unlocking, l
Setting the login password by hand is a bootstrap shortcut, not the end state. Setting the login password by hand is a bootstrap shortcut, not the end state.
The first thing to do on the running laptop is to move that password to a `hashedPasswordFile` backed by a `sops-nix` secret, so it is declared and reproducible like everything else. The first thing to do on the running laptop is to move that password to a `hashedPasswordFile` backed by a `sops-nix` secret, so it is declared and reproducible like everything else.
This is deliberately out of scope for the install itself. Per ADR 0002, secrets are decrypted by two tiers of age identity: an admin identity held in a password manager, which is a recipient of every secrets file, and a per-`Host` identity generated on that machine's encrypted root.
Per ADR 0001, each `Host`'s secrets are encrypted to an age key derived from that `Host`'s SSH host key — and that host key does not exist until this first install generates it. A `Host` identity is deliberately *not* derived from its SSH host key, which is what allows the SSH host keys to become secrets in their own right and survive a reimage.
So the sops wiring can only happen *after* the machine is up, which is exactly why it is the first follow-up rather than part of this procedure.
That wiring is out of scope here because this procedure is what produces the machine the identity is generated on.
**Once the password is a secret, step 4 of this procedure stops working.**
`hashedPasswordFile` takes precedence over every other password option, so `passwd` under `nixos-enter` no longer yields a login, and no fallback setting can override it.
From that point on, a `Host` must have its identity provisioned and registered as a recipient *before* its first boot, or it boots with no usable password.
Anyone reinstalling after the secrets work lands should follow the secrets provisioning procedure rather than step 4 as written.