Keys¶
Realms¶
A realm is a fleet of keys, machines and vaults that open each other: realm=muskernet in the config, in the examples here. Its relying-party id - what every token's credential is made for, and what every vault's record names - is heft:muskernet. The heft: prefix makes it something no website can ask a key for, as OpenSSH's ssh: does for its credentials; nothing resolves it and CTAP does not validate it. The only requirement is that every machine spells the realm identically, which is why it is recorded once in the config rather than derived from anything local.
- A realm name is lower-case letters, digits and hyphens, 1 to 63 of them, not starting or ending with a hyphen. Lower case only, because relying-party ids compare byte for byte:
Muskernetandmuskernetwould be two realms whose keys cannot open each other's vaults. There is no default;config init,vault createand a takeover byvault addask, or take--realm. - A machine belongs to one realm.
vault addrefuses another realm's vault. A TPM key belongs to no realm - its secret depends only on each vault's salt - so the same TPM could serve several, should machines ever belong to more than one. housekey key info --credentialslists every realm a token holds a credential for, with the label it was enrolled under (it asks the token's PIN).- The same realm names every other use of the tokens, one scheme per use:
heft:muskernetfor vaults,ssh:muskernetfor ssh keys,pam://muskernetfor login,tag:muskernetfor the credential that names each token. housekey reads the last - see Labels from the token.
FIDO2 keys¶
A FIDO2 token holds one resident credential for the realm, and derives each vault's key secret from it with hmac-secret, verifying you by fingerprint or PIN every time. One credential, in one resident slot, covers every vault (see One credential covers everything). The token must speak FIDO 2.1: see Requirements.
Before enrolling anything¶
housekey key test # one FIDO2 key at a time
housekey key test --type tpm2 # this machine's TPM
housekey key test --type mobile # a mobile, Android or iOS, and the network path to it
housekey key test --type ios # an iOS mobile alone (--type android: an Android one)
key test creates a scratch resident credential under its own relying-party id (heft:_selftest, so it also shows the key accepts a heft: id), derives from it twice, checks the two results are identical, and deletes the credential again. One credential plus one salt giving the same bytes every time is the premise of the whole scheme; confirm it per model before you enrol six keys, not after.
It costs three verifications, and biometric keys allow around five before refusing - unplug and reinsert between runs. --two-salt adds a fourth, probing whether the key will return 64 bytes for two salts in one assertion.
housekey key changepin --type fido2 changes the PIN of the one token plugged in, or sets the first PIN on a token that has none. A token's credentials do not depend on its PIN, so every vault it opens still opens, and a fingerprint on a biometric key is unaffected. The token may refuse a PIN its own rules forbid.
housekey key info reports what a token supports, how it verifies, how many PIN attempts remain and its tag, with no PIN. --credentials adds resident slot headroom and the credentials it holds by realm; CTAP gives those only for the PIN, even on biometric keys, so only then is it asked for.
Labels from the token¶
A token can name itself: a discoverable credential under tag:REALM whose user id is plain text such as yubikey-bio. housekey reads it with a silent assertion - no touch, no PIN, no verification, nothing derived - the same as fido2-assert -G -r -t up=false, and uses it in three places:
- The default label.
vault enrolkeyasks for the label once the new token is plugged in, offering its tag;vault createand a takeover byvault addoffer the tag of the one token plugged in.--labeloverrides it. Using the tag every time is what keeps a token's label the same on every vault. - Which token to ask first. With several tokens plugged in, the one whose tag names a key enrolled on the vault is asked first. With one, or none matching, nothing changes.
housekey key infoprints the tag.
A tag is a hint and nothing more: anyone can make a credential with any user id, so it never decides access. A wrong one costs what trying tokens in turn always did.
housekey key rename --label NAME sets the tag on the one token plugged in, or replaces it. The name is the credential's user id, so a new name is a new credential: made first, then the old one deleted, which takes the PIN (credential management is PIN-gated even on a biometric token) and a touch. Nothing the token opens changes, and the labels it is enrolled under on the vaults stay as they are; vault labelkey changes those.
Changing a label¶
housekey vault labelkey NAME --label OLD --new-label NEW renames one key's enrolment on one vault; what the key opens does not change, and neither does its label on any other vault. On a shared or keepass vault the label is bound into the key's wrap, so the wrap is made again under the new label, to the public key the vault's signed list holds: an enrolled key opens the vault to authorise it (the key being relabelled will do), and the key itself need not be there. On a disk or bootdisk vault the label is in the LUKS2 header token, which no key protects, so it changes under sudo with no key asked.
TPM2 keys¶
A machine's TPM can be a key: tpm2 beside fido2. It suits a machine that should open its vaults without a token plugged in - at the desk, or at boot - while still asking for something the thief of the machine does not have.
housekey key init --type tpm2 # once per machine: create the key, set the PIN
housekey vault enrolkey docs --type tpm2 # authorised by an enrolled FIDO2 key
housekey vault open docs # no token plugged in: asks for the TPM PIN
It mirrors hmac-secret. One HMAC-SHA256 key per machine is generated inside the TPM, can never leave it, and is persisted at a fixed handle (0x81484654). The key secret for a vault is TPM2_HMAC(that key, the vault's salt): 32 bytes, exactly the shape a FIDO2 key returns, so wraps, keyslots and the header token treat the two alike, and one TPM key covers every vault as one credential does.
Beside it, an ECDH key (3.2.3). A shared vault's wraps are public-key, and a TPM - unlike a FIDO2 token - can do the private half of that itself: an ECC P-256 key, generated in the TPM at 0x81484655, with TPM2_ECDH_ZGen. A TPM's wraps are written to it, so its private key never leaves the TPM. It has no PIN of its own: its policy is "whoever can use the HMAC key", so the one PIN guards both, wrong PINs count against the one lockout, and key changepin covers both. key init makes it; on a TPM initialised before 3.2.3, key init --type tpm2 adds it, and each vault's wrap for the TPM moves to it the next time this machine opens that vault. A TPM with no ECC has none, and its wraps use a key pair derived from the HMAC key, as a token's do. LUKS keyslots and the boot plugin use the HMAC key only.
The PIN is required on every use, as user verification is on every assertion, and the TPM counts wrong PINs against its dictionary-attack lockout: after its limit (often 32) it refuses every PIN, right or wrong, forgetting one failure per interval. housekey key ls shows how many attempts remain. The PIN becomes the key's authorisation as a hash, and every command carrying it - or the secret - runs in a session salted against a storage key with parameter encryption, so neither crosses the TPM's bus in the clear.
Order. vault open, vault testkey and the boot plugin try a connected FIDO2 key first, and this machine's TPM when no key is connected, or none holds a credential; housekey then asks an enrolled mobile when neither will do (the boot plugin has no mobiles). --type chooses outright. Every TPM2 enrolment records the key's TPM name beside its wrap or keyslot, so housekey knows whether this machine's TPM is enrolled on a vault before asking for any PIN, and vault info says which TPM key is this machine's:
Enrolling. The label defaults to the host name (before 3.3.6 it had -plus-PIN on the end; labels already enrolled keep it). A TPM is enrolled by an already-enrolled FIDO2 key or mobile - another machine's TPM cannot vouch for this one - and a token can be enrolled with this machine's TPM as the authorising key, with no swap. vault create and a takeover by vault add take --key-type tpm2 to make the TPM the first key; enrol a token as well.
Autolock leaves a vault that was opened with the TPM alone: no key was plugged in to open it, so one being unplugged says nothing about it. vault open records how each vault was opened in the runtime directory.
At boot, a bootdisk with a TPM2 keyslot asks for the TPM PIN when no FIDO2 key is plugged in. That needs housekey-boot 3.1.0 or later in the initramfs; an older plugin ignores the TPM slot and asks for a key or the passphrase.
No PCR binding. The key is sealed to the TPM and its PIN, not to what the machine booted, so kernel and firmware updates never break it. It does not resist an evil maid any better than a FIDO2 key does; binding to PCR 7 (Secure Boot state) is on the list for when there is a signed boot chain to bind to.
Things to know:
/dev/tpmrm0has to be usable by you: installtpm-udev(Debian) and join thetssgroup,sudo usermod -aG tss $USER, then log in again.housekey key changepin --type tpm2changes the PIN. The TPM re-wraps the same key under the new one, so every vault it is enrolled on opens with the new PIN, nothing is re-enrolled and a bootdisk's initramfs needs no rebuilding. It asks for the current PIN, which counts towards the lockout if wrong.- A forgotten PIN cannot be reset or recovered, since changing it needs the current one.
housekey key erase --type tpm2thenhousekey key init --type tpm2makes a new key, which is a different key: enrol this machine on each vault again. The same goes for a firmware TPM reset, or a new motherboard. - housekey needs the TPM owner hierarchy's authorisation to be empty, as
systemd-cryptenrolldoes. - A TPM with no ECC - early TPM 2.0 firmware, such as the Infineon SLB9665 in a Surface Pro 2 - is used with an RSA-2048 storage key instead;
housekey key test --type tpm2says which. housekey key test --type tpm2checks the TPM against the scheme with a scratch key - including that a wrong PIN is refused, without spending a lockout attempt - and then, if the TPM key exists, its PIN.
Mobile keys¶
A mobile running the housekey app can be a key: android (below) or ios (iPad and iPhone) beside fido2 and tpm2. It suits someone with one token, or none: a key not bound to one machine that is always to hand.
housekey key test --type android # check the mobile and the network path; enrols nothing
housekey vault enrolkey docs --type android # authorised by a key already enrolled
housekey vault open docs # no token, TPM not enrolled: asks the mobile
How it is asked. housekey shows a QR code on the terminal and listens on one TCP port (8455) for as long as the request lasts. The app reads the code - with its own scanner, or from the mobile's camera app, which sees an hkey: link and offers to open it in the app - connects to this machine, and says which key it holds; housekey asks it for one ECDH, which the mobile does only after a fingerprint or its screen lock, and shows on its screen which machine, vault and purpose it is for. Everything after the QR is encrypted to a key only the QR carried. The mobile never listens, and nothing is pushed to it.
On the USB cable (Android, app 0.9.0 or later). While housekey waits for a mobile to open a vault or for key test, it also watches the USB ports: an Android mobile plugged in is made an Android Open Accessory naming housekey, Android opens the app (asking the first time; tick "always"), and housekey sends the request down the cable instead of through the QR code - the same session, the same code on both screens, one fingerprint. Whichever answers first, the QR or the cable, is used. It works with USB debugging off, in any USB mode, with the mobile locked (the request shows over the lock screen), and with no network at all: with no network address housekey waits on the cable alone. Enrolling stays on the QR code and the code typed in. housekey reaches the mobile only if you may open it: the package installs a udev rule (70-housekey-mobile.rules) that lets the person at the machine open a device with an ADB or MTP/PTP interface, and the accessory it becomes; --trace says what was skipped and why. A machine with android-udev-rules (51-android.rules, which covers every Google device, the accessory included) or libmtp's media-player rule may reach the mobile already. housekey sends the accessory requests only to such devices, so a mobile plugged in only to charge is switched too, while housekey is waiting for a mobile; one that does not answer is given back in its ordinary mode when the wait ends. A mobile on the cable is a key as a security key plugged in is: with no security key there, housekey asks it before this machine's TPM (it moves on to the TPM if the mobile is not enrolled on the vault, and stops if you decline).
Its key. One P-256 key per mobile, generated in its secure hardware (StrongBox on a Pixel) and never leaving it, usable only for key agreement and only with the user, once per authentication. A shared or keepass vault wraps to it as to a TPM's ECDH key, so a rotation includes the mobile without the mobile. A disk keyslot gets a P-256 pair of its own at enrolment: the header keeps its public half, and the keyslot's key comes from the mobile's ECDH with it. On a bootdisk, an Android mobile is asked at boot over the USB cable, after a FIDO2 key and before this machine's TPM when it is plugged in, or waited for after the TPM: plug it in when the disk is to be unlocked, compare the code on the splash and approve (see Bootdisk vaults). An iPhone or iPad cannot be enrolled on one.
Enrolling checks the mobile's attestation - the certificate chain its secure hardware signs, ending at Google's root - that the key is hardware-backed, for key agreement only, needs the user every time, and belongs to the housekey app on a mobile with a locked bootloader and verified boot. Then it asks you to type the six-digit code the mobile shows: whoever answers the QR becomes a key, and the code proves it was your mobile. A mobile can authorise enrolments, including this machine's TPM, as a FIDO2 key can.
The network. The mobile has to reach this machine: open the port in its firewall (mobile_port changes it), and keep Wi-Fi client isolation off. housekey takes only connections sent with TTL 255 that arrive having crossed at most mobile_hops routers (default 1, so a mobile on Wi-Fi in an adjacent subnet works; GTSM, RFC 5082). That keeps the rest of the internet out, not the rest of your network: a guest network or VPN clients the router routes directly are as near as your Wi-Fi.
Order. A FIDO2 key first, this machine's TPM when it is enrolled, and a mobile when neither will do - or --type mobile, which takes whichever mobile answers, or --type android or --type ios for that kind alone. Wherever a command asks for a key that is already enrolled, press Enter with no token plugged in to use a mobile. Over SSH housekey warns that anyone who can see the terminal can scan its code; only an enrolled mobile can answer, and enrolling needs the code typed in. No mobile within 90 s is exit 3, no terminal is exit 4. Autolock leaves a vault opened with a mobile alone, as with the TPM.
Losing it. housekey vault revokekey NAME --label LABEL on each vault; on a shared or keepass vault that rotates, as for any key. A mobile replaced is a new key: enrol the new one, then revoke the old.
Android¶
An Android mobile needs Android 16 with its QPR2 update or later. Its key is attested: enrolling checks the certificate chain its secure hardware signs, as described above, so housekey knows the key is hardware-backed rather than taking the app's word for it. An Android mobile is the only mobile that can unlock a bootdisk, over the USB cable.
iPad and iPhone¶
An iPad or iPhone needs iOS 26 or later, with a passcode set. Its key lives in the Secure Enclave and belongs to the team that signs the app: a build signed by another team cannot reach it, so moving from a free Apple ID to a paid developer account makes a new key, to be enrolled again.
housekey key test --type ios # check the device and the network path
housekey vault enrolkey docs --type ios # needs ios_unattested=yes
Unattested. iOS attests nothing about a Secure Enclave key. housekey cannot check that the app's key is in the enclave, is for key agreement only, or needs the user at every use, as it checks an Android mobile's: it takes the app's word. So an iPad or iPhone is enrolled only where the configuration says ios_unattested=yes in its [housekey] section, and it is shown as unattested (vault info: "(iOS, unattested)"). The enrolment otherwise is a mobile's: the code it shows typed in, and one ECDH against a pair made here. The app asks App Attest for an object over its key where it can and sends it; housekey does not check it yet.
Opening is a mobile's: --type mobile asks whichever mobile answers, --type ios an iOS one alone. Enrolling is the one place mobile is refused: the platform decides what housekey checks - an Android mobile's attestation, or ios_unattested - so enrolkey wants --type android or --type ios, named by you rather than claimed by the mobile.