Skip to content

Cryptography

Key hierarchy

key + rp id + salt    →  key secret  →  key pair  →  opens NAME.wrap  →  master passphrase
master passphrase     →  opens gocryptfs.conf  →  master key  →  your files
What it is Where it lives
realm the fleet's name, muskernet say; its FIDO2 relying-party id is heft:muskernet the config file; the id in each vault's record and on each key
salt 32 random bytes, one per vault the vault record
key secret HMAC-SHA256(CredRandomWithUV, salt), or TPM2_HMAC(this machine's key, salt); a mobile has none on a shared or keepass vault nowhere - recomputed each unlock
key pair a P-256 private scalar derived from the key secret, and its public key - or, for a TPM with an ECDH key and for a mobile, that key itself the public key in the key's wrap and in pubkeys.json; the private half nowhere, or inside the TPM or the mobile
master passphrase base64 of 48 random bytes nowhere - only as per-key wraps
master key the key actually encrypting your files in gocryptfs.conf, under the master passphrase

For a disk or bootdisk vault the middle two rows collapse. LUKS is already a wrapping layer - the volume key is stored once, encrypted separately per keyslot - so the key secret is the key, one keyslot per key, and cryptsetup finds the matching slot itself. There is no wrap directory on disk at all:

key + rp id + salt    →  key secret  →  opens a LUKS keyslot  →  volume key

The wrapping layer exists because every key produces different bytes - CredRandom is per credential, per key - while gocryptfs has a single keyslot. One master passphrase is generated once and stored once per key. Adding a key writes a wrap; revoking one deletes a wrap; the vault is never re-encrypted.

Wraps are public-key. A token has a P-256 key pair for each vault, derived from its key secret: FIDO2 has no public-key encryption of its own, so the private half is computed on the host, as the key secret already is, and forgotten. A TPM's ECDH key and a mobile's key do ECDH themselves, and their private halves never leave them. A wrap is ECIES - a one-use key pair, ECDH to the key's public key, HKDF, AES-256-GCM - so it can be made with the key's public key alone, the key nowhere near. Rotation uses that: one key present re-wraps the passphrase for all of them.

vault.keys/pubkeys.json lists every key's public key, authenticated by one HMAC keyed by the passphrase, so nobody who can merely write to the share can add a key of their own to it - or remove one - unnoticed. housekey only ever adds a key to it that has just proven itself present; if the list does not verify, the next open rebuilds it from the keys present and says what it left out.

The format is pinned in the housekey-cli source by testdata/wrap-vectors.json, which testdata/check-wrap-vectors.py recomputes with nothing but Python's standard library. LUKS vaults are unchanged: a keyslot needs its key present to enrol, whatever the scheme.

Scheme Specifics

Keepass specifics

The master secret is the key file. A keepass vault's secret is 32 random bytes, used as the KDBX key file's data: KeePassXC is given it as a KeePass XML (v2) key file, and the database's composite key is the SHA-256 of those bytes, with no password. It is wrapped to each key exactly as a shared vault's passphrase is - the same ECIES wrap, the same additional data, the same authenticated list of public keys - so everything above about wraps and rotation holds for it.

Everything lives in the database's own header. The vault record (its type spelled kdbx), the wraps and pubkeys.json are one entry, heft, in the KDBX 4 outer header's public custom data: readable by anyone without the key, kept by KeePassXC when it saves, and covered by the header's HMAC, so it cannot be changed without the key file either. There is nothing beside the .kdbx file to lose or to fall out of step with it.

housekey writes the header, not the contents. An enrolment or revocation rewrites the header and its hash and HMAC, which needs the key file and the key derivation. Every write is a single atomic replacement of the file, refused if the file changed since housekey read it. New databases are KDBX 4 with AES-256, gzip, and Argon2id at 16 MiB and one pass: the key derivation exists to slow down guessing a password, and this database's key is 32 random bytes. KDBX 3.1 and Twofish are refused.

Rotation is complete. Unlike gocryptfs, whose master key can never change, a keepass rotation makes a new key file and re-encrypts the database under it, with the new wraps in its header, in one write. housekey re-encrypts the cipher stream as it is and never parses the XML inside, so nothing housekey does not understand is lost. A copy of the database from before the rotation still opens with a key enrolled then - the same caveat as a snapshot of a shared vault.

The key file touches disk only in the runtime directory. To open a vault in KeePassXC, housekey writes the key file to $XDG_RUNTIME_DIR/housekey/keyfiles (tmpfs, mode 0600) for the length of the D-Bus call that opens the database, which reads it synchronously; for --cli, until keepassxc-cli has read it, ten seconds at most. It is never written anywhere else.

Credentials changed in KeePassXC are detected, not overwritten. A header that does not verify with the key file housekey unwrapped means a password or another key file was added in KeePassXC: housekey writes nothing to it, and housekey vault repair re-encrypts it under the key file alone, with the wraps unchanged. See KeePass vaults.

GoCryptFS specifics

The layout. A shared vault is a directory, the vault root, holding two others:

vault.enc/ the gocryptfs volume: the ciphertext, and gocryptfs.conf with gocryptfs's master key encrypted under the volume's password
vault.keys/volume.json the vault record: the realm's relying-party id, the salt, and the type, spelled gocryptfs
vault.keys/LABEL.wrap one wrap per key, holding the master passphrase
vault.keys/pubkeys.json every key's public key, under one HMAC

The master passphrase is the volume's gocryptfs password: base64 of 48 random bytes, which nobody ever types or sees. housekey gives it to gocryptfs down a pipe, and gocryptfs derives the key that opens gocryptfs.conf from it as it would from any password. The files themselves are encrypted under gocryptfs's own master key, which housekey never handles except to show it (vault masterkey, through gocryptfs-xray, straight to the terminal).

A token's key pair is derived per vault. Its private scalar is HKDF of the key secret, with the vault's salt and the label heft/p256/v1, reduced to a P-256 scalar; it is computed on the host for the length of one operation and never stored. A wrap is an ephemeral ECDH to the key's public key, HKDF with the salt, and AES-256-GCM, whose additional data binds the relying-party id, the salt, the label (the file's name) and both public points. So a wrap cannot be renamed, or copied to another vault or realm, and still open: a relabel seals it afresh, to the public key the list holds.

The list is keyed by the passphrase. pubkeys.json's HMAC key is derived from the salt, the passphrase and the relying-party id, so only someone who can open the vault can change the list. Writing to the share is not enough to slip a key in, or to drop one from the next rotation unnoticed.

gocryptfs has one password, so rotation changes it. The new passphrase is wrapped to every key on the verified list, staged in vault.keys/rotating/ (the directory is also the lock), then made the volume's password with gocryptfs -passwd, then moved into place; an open finishes a rotation interrupted after the password changed. gocryptfs's master key never changes, so the paper master key, or an old gocryptfs.conf with an old wrap, still opens the files: only a new vault and a copy of the files change it. See Rotation.

File-level, so a share is fine. Each file is encrypted on its own, so the vault root can sit on NFS and be opened from several machines at once, each mounting it with FUSE as its own user. Volumes made with gocryptfs -fido2, reverse-mode volumes and volumes whose config is kept outside the volume are refused.

LUKS specifics

The salt lives in a LUKS2 custom header token, the same inner object a shared vault keeps in volume.json, plus a map from keyslot number to key label; a key_types map giving the kind of key, for keyslots that are not FIDO2; a key_ids map giving each key's id (a TPM key's name, a hash of a mobile's key, and since 4.0.8 a hash of a token's credential id - a token enrolled earlier gets its id when it next authorises a change to the vault's keys); and for a mobile's keyslot the public half of the key pair made for it (points). The boot plugin reads an id only for a TPM2 keyslot. Not derived from the LUKS UUID: cryptsetup luksUUID --uuid= would silently orphan every credential at once.

The record on disk still spells its type gocryptfs or luks, not shared or disk, and carries boot-ness in its role field as before. That vocabulary is shared with the Rust plugin and with testdata/luks-vectors.json, so housekey maps to it at the boundary rather than renaming a field two implementations have to agree on.

The token's own keyslots array lists every housekey keyslot. That is what makes libcryptsetup offer them to the boot plugin, which is called once and whose key is then tried against each of them.

Keyslots use PBKDF2 at minimum iterations, not the default argon2id. The key being installed is already 256 bits of uniform entropy from the hardware, so stretching it protects against nothing and would cost a second of CPU and up to a gigabyte of RAM on every unlock. This is what systemd-cryptenroll does for its own token-derived slots. A keyslot holding a human passphrase must keep the default - add never touches yours.

Keyslots are marked preferred. cryptsetup walks keyslots in numerical order, so a passphrase slot at 0 with default argon2id parameters is ground through on every unlock before a housekey slot further up is reached - a second of CPU and up to a gigabyte of RAM, every time, to fail. add and enrolkey set --priority prefer on the slots they create. For slots enrolled before this, or by hand:

for n in 4 5 6 7 8 9; do
  sudo cryptsetup config --key-slot $n --priority prefer /dev/sdX1
done

Root. cryptsetup and mount need it, so a disk vault is used under sudo: sudo housekey vault open secure. housekey does not call sudo itself - see As yourself, or as root. The key reaches cryptsetup down a pipe, never as an argument, where ps would show it.

Locking a LUKS vault unattended is root's crontab, or the root line of the udev rule: no sudoers entry is involved.

Recovery has no paper master key. gocryptfs prints one; LUKS has no equivalent. For an emergency recovery use the passphrase keyslot (add leaves it alone) plus a header backup:

sudo cryptsetup luksHeaderBackup /dev/sdX1 --header-backup-file luks-header.img

Guard that file like the disk: it holds every keyslot, so it plus any one key opens the vault. And a backup taken before a revocation puts the revoked keyslot back - re-take it after any real revocation, and destroy the old one.

ZFS specifics

Not yet tried on real ZFS: so far it is tested only against a simulated zfs. A disk vault can be an encrypted ZFS dataset instead of a LUKS container: its section names dataset=tank/secure where a LUKS one names device=, and has no mount point, since ZFS mounts the dataset where its own mountpoint property says. The dataset must be its own encryption root - encrypted under a key of its own, not its parent's. A pool's top dataset is one too, which is how a whole pool becomes a vault.

sudo housekey vault create --type disk --dataset tank/secure   # a new encrypted dataset
sudo housekey vault add tank/vault --type disk                 # take an encrypted one over
sudo housekey vault add usbpool                                # add a housekey dataset from another machine

ZFS has one key per dataset and no keyslots, so a ZFS vault works like a shared or keepass one: a random 32-byte key is the dataset's key (keyformat=hex), wrapped to each enrolled key. The record, the wraps and the list of public keys are the dataset's own user properties - heft:record, heft:f.LABEL.wrap, heft:f.pubkeys.json, a capital letter in a label written as a colon and the letter - so a zfs send -p or -w of the pool carries them. revokekey rotates the key without the revoked one, and vault rotate rotates it outright; as with gocryptfs, ZFS's own data key never changes, so a copy of the pool from before still opens with a wrap from before.

The key reaches zfs on its standard input, never its command line. housekey vault masterkey shows it, for paper: 64 hex characters, which zfs load-key takes at its own prompt with no housekey at all.

The pool. vault open imports the pool when it is not imported (a USB pool, say), and vault close exports it again - only a pool housekey imported; one imported at boot or by hand stays. housekey never creates a pool: zpool create destroys what is on its disks. To make a whole pool a vault, create it encrypted with a passphrase (zpool create -O encryption=on -O keyformat=passphrase ...) and take it over.

Taking a dataset over replaces its key. After a warning and a yes, its passphrase (or key, from --passphrase-file) is checked, the first key verified, and the key changed to housekey's; datasets below it that share its key follow. Any failure before the first key is enrolled puts the old key back.

Closing unmounts every filesystem under the dataset's key, deepest first, and unloads the key; nothing is unmounted while something uses it, unless --force, which detaches what is in use and leaves the key loaded until a later close finds it let go. housekey never closes the dataset / is on, or one under whose key it is. A ZFS root unlocked at boot by housekey-boot is not there yet: --type bootdisk with a dataset is refused for now.