0013 — Automation keyslot (slot 2) for unattended/Ansible unlock

Status: accepted (2026-06-22) — ratified by maintainer; proposed 2026-06-05

Context

The keyfile container has slot 0 (daily passphrase), slot 1 (recovery), and slots 2-7 reserved (SPEC §7). Reboots are rare and usually attended, so fully hands-off TPM unlock isn’t urgent — but upgrade/deploy cycles want a scriptable unlock that does not require putting the human daily passphrase into an Ansible vault. That secret must be independently revocable: a leaked automation credential should be rotatable without touching slot 0 or slot 1.

Decision

Slot 2 is the automation keyslot, fleet-wide. A dedicated automation passphrase is enrolled there and used only by automation.

• Enroll: keyboot-install keyfile enroll-automation <file> — sugar that adds a passphrase to slot 2 (same mechanism as add-recovery, authorized by an existing daily/recovery passphrase). The convention lives in the tool, not just the docs.
• Rotate / revoke (GL#14): rotate in place with keyfile passwd --slot 2; move/retire with keyfile rekey --retire-slot 2 --new-slot 3. The 32-byte payload is untouched, so data-disk enrollment survives — only the automation passphrase changes. Slot 0 (daily) and slot 1 (recovery) are unaffected by any automation-slot rotation.
• Unlock flow (no new mechanism): Ansible (vaulted passphrase) connects to keyboot’s pre-unlock dropbear and feeds the slot-2 passphrase to the authorized-keys forced command /sbin/keyboot-askpass, which reads it from stdin and submits it to stage-4’s FIFO — exactly the existing SSH-unlock path (stage-3-ssh.sh / stage-4-passphrase.sh). A sample role lives at ansible/keyboot_unlock/.
• Single canonical slot, not a range. LUKS1 has no per-slot labels, so a range (2-7) would need external inventory to track “which slot is what”. One canonical slot keeps the vault entry and rotation trivial; slots 3-7 stay reserved (e.g. as the target of a rekey rotation, or future use).

TPM-sealing (truly hands-off, measured boot) remains the deferred path.

Alternatives considered

• Reserved range 2-7 for multiple automation identities — rejected as the default: needs out-of-band tracking (no LUKS1 labels) for little gain on a fleet where one automation secret per host is the norm. rekey already lets you stage a rotation into slot 3 and kill slot 2 when needed.
• Reuse the daily passphrase for automation — rejected: puts the human secret in a vault and couples revocation (rotating automation would force a daily-passphrase change).
• TPM/measured-boot unlock — the right hands-off answer eventually; deferred (needs sealing policy + PCR design; out of scope here).

Consequences

• A leaked automation credential → passwd --slot 2 (or rekey) and you’re done; daily/recovery untouched.
• No change to the unlock runtime — automation reuses the proven SSH askpass path; the only new code is the enroll-automation sugar + the sample role.
• Pairs with the future keyboot_deploy role (GL#24): the deploy loop unlocks via this slot, then clones/boots-next/health-gates.