Vaults¶
Configuration¶
Configuration files¶
Two files, read together as one list of vaults:
- The machine's,
/etc/housekey/housekey.conf: disk and bootdisk vaults. Root's jobs - the nightly sweep - and every user see these, and root reads nothing else. It is root's to write and everyone's to read (0644); housekey writes it when run under sudo, and only ever adds, renames or removes whole, checked sections, putting the file back if the result would not parse. - Yours,
~/.config/housekey/housekey.conf: shared vaults, whose FUSE mounts are yours alone - root cannot unmount them - and keepass vaults, which open in your KeePassXC.
Either may be missing. The machine's file, when there is one, names the realm, and yours may then leave it out (if it names one, they must agree). A vault name may be in only one of them. vault ls says which each vault is in (machine or user), vault info names the file, and config info lists each file's vaults.
vault create and vault add put a disk or bootdisk vault in the machine's file and a shared or keepass vault in yours; --scope machine|user overrides - for someone who can do LUKS work without sudo (see As yourself, or as root), a disk vault can be their own. Root reads only the machine's file, so a disk vault in yours is not seen under sudo unless -c names the file. forget and rename edit whichever file holds the vault. -c FILE or HOUSEKEY_CONFIG reads, and writes, exactly that one file instead.
# /etc/housekey/housekey.conf
[housekey]
realm=muskernet
[secure]
vault_type=disk
device=/dev/disk/by-uuid/a39a54ca-063e-4a36-add7-e07a95c4ba4d
mount_point=/secure
[root]
vault_type=bootdisk
device=/dev/disk/by-uuid/0f6d1b2c-...
mapper_name=cryptroot
# ~/.config/housekey/housekey.conf - no [housekey] needed: the machine's names the realm
[docs]
vault_type=shared
vault_root=/mnt/nas/Documents/vault
mount_point=/home/alice/Vault
[passwords]
vault_type=keepass
database=/home/alice/.local/share/housekey/passwords.kdbx
A disk vault takes device and an optional mapper_name, which defaults to the vault name. It has no vault_root, because its record is in the header. A bootdisk additionally has no mount_point. A keepass vault takes database alone: its record and wraps are in the database's header, and it is opened in KeePassXC, not mounted.
For a shared vault, everything else is convention:
<vault_root>/vault.enc |
ciphertext |
<vault_root>/vault.keys |
wraps, the vault record, and pubkeys.json |
<vault_root>/vault.keys/volume.json |
relying-party id (heft:REALM), salt, vault type |
The [housekey] section can also hold the mobile settings (see Mobile keys): mobile_port (default 8455), mobile_hops (default 1), mobile_roots, a PEM file of attestation roots to trust beside Google's - for a mobile OS with its own, or heft-phone-sim - and ios_unattested (yes or no, the default), whether an iPad or iPhone may be enrolled with no attestation. Yours overrides the machine's.
A # starts a comment, on a line of its own or after a setting, where it must follow a space or tab: mobile_hops=0 # same subnet only. A # inside a word is part of the value, so /srv/a#b is a path; a value cannot contain a space followed by #. housekey config init (and the first vault written to a new file) writes the optional [housekey] settings commented out, each with a line on what it does and its default.
housekey reads the file as plain settings and never runs anything in it. Only the settings it knows are accepted: a misspelt or unknown one is an error that names it, rather than being quietly ignored. And housekey refuses a file that anyone other than its owner can write to, since whoever could change it could change which disk or folder a vault is.
housekey config test parses both and reports what they define, reading nothing else: no keys and no headers, so it needs no elevation. A machine file that is not readable by everyone is an error saying so (sudo chmod 644 /etc/housekey/housekey.conf).
Rotation¶
housekey vault rotate NAME replaces a shared vault's passphrase: a new one is generated, wrapped to the public key of every enrolled key, and made the volume's password (gocryptfs -passwd). One key does it, whichever; the others need not be present. revokekey on a shared vault rotates as part of revoking. A keepass vault rotates too, more completely - see KeePass vaults.
- A key with no verified public key cannot be wrapped to - one whose wrap is missing from
pubkeys.json. Open the vault once with it first; otherwise rotate names it and asks before leaving it without access. - A list that does not verify is refused, untouched: it cannot be trusted to say who to wrap to. Opening with each key that should stay rebuilds it.
- It is crash-safe. The new wraps are staged in
vault.keys/rotatingbefore the password changes, and moved into place after. Interrupted after the password change, the next open with any key finishes the move; interrupted before, the old wraps still open, androtateasks before discarding the staging - it may be another machine's rotation in progress. The staging directory is also the lock that stops two rotations at once. - The gocryptfs master key does not change - gocryptfs cannot change it. Rotation makes old copies of wraps useless against the volume as it is now, but anyone with the master key (the paper copy), or with an old
gocryptfs.confand a wrap that opens it (a snapshot from before), still opens the vault. Only a new vault, and a copy of the files into it, changes the master key.
One credential covers everything¶
The same holds for a TPM2 key, one per machine, and a mobile, one key per mobile, whatever the number of vaults.
The salt is a per-assertion input, not a property of the credential, so one credential yields unlimited independent secrets. One resident slot per key covers every vault, present and future, of every type. Separation between vaults comes from the random per-vault salt; HMAC is a pseudo-random function, so holding one vault's key says nothing about another's.
This is also why housekey key erase takes no vault name. The credential is fleet-wide, so erasing it orphans that key from every vault at once rather than from one of them. Before it asks, it lists the vaults configured here that the key is enrolled on, found by key id as vault ls --keys finds them, with no PIN (4.0.17); a disk vault's header is read only under sudo, so as yourself such a vault is named as not read, and may be one more.
The relying-party id is therefore realm-wide and fixed: see Realms.
KeePass vaults¶
A password database opened only by a key: a KeePassXC database, KDBX 4, whose key is a key file and no password. The key file's 32 bytes are the vault's master secret, wrapped to each key exactly as a shared vault's passphrase is - and the wraps live in the database itself, in its header's public custom data, which any reader can see without the key and which KeePassXC keeps when it saves. So the vault is one file, with nothing beside it, and it cannot drift apart from its wraps.
housekey vault create --type keepass --name passwords # ~/.local/share/housekey/passwords.kdbx
housekey vault enrolkey passwords # a second key, now
housekey vault open passwords # into KeePassXC
housekey vault close passwords # lock it
housekey vault open passwords --cli # in keepassxc-cli, on this terminal
housekey vault open passwords --cli show -s Bank/login # one keepassxc-cli command, then return
- Open unwraps the key file, writes it to the runtime directory (tmpfs, yours alone), and asks KeePassXC - started if it is not running - to open the database with it, over its D-Bus interface. KeePassXC reads the key file during the call, and housekey removes it the moment the call returns. housekey asks for a key every time: whether KeePassXC has locked the database since is not something it says.
- In keepassxc-cli:
housekey vault open NAME --cliruns keepassxc-cli's shell (keepassxc-cli open) on the terminal instead, for where there is no KeePassXC to hand the database to - over SSH, or on a machine with no desktop. The key file is in the runtime directory only until keepassxc-cli has read it, which it does once, as it starts; the shell keeps the database until youquit, and housekey waits for it. A key file cannot go down a pipe: keepassxc-cli seeks in it. While the shell runs, enrol, revoke, rotate and repair refuse, before any key is asked and--forceor not - keepassxc-cli cannot be locked from outside, and would save the old header back over the change - andvault closedoes not end it. Two programs editing the database at once (the shell and KeePassXC) is yours to avoid. - One keepassxc-cli command:
--cliis the last option housekey reads, and words after it are keepassxc-cli's, global options included.housekey vault open NAME --cli show -s Bank/loginruns that one command on the database instead of the shell - housekey gives it the database and the key file, askeepassxc-cli show --no-password --key-file KEYFILE DATABASE -s Bank/login- and returns when it ends, so a script can read an entry:pass=$(housekey vault open passwords --cli show -a password Bank/login). Its output alone is on stdout (housekey's messages go to stderr), and a command that fails exits 1. The key file goes as soon as keepassxc-cli has read it, and while the command runs the vault is held as under the shell. A command that opens no database (generate,diceware,estimate,db-create,import) is refused, as is a key option: run keepassxc-cli itself for those. - Never "open". KeePassXC decrypts the database in its own memory, and does not say whether it still has it unlocked; the file stays encrypted throughout. So
vault lsandinfosayready(the database is there) orno database, andinfoadds when housekey last opened it in KeePassXC this session, and with which key. - Close and
autolockask KeePassXC to lock, when it is running. KeePassXC 2.7 can only lock every database it has open, so that is what happens. A database with unsaved changes makes KeePassXC ask Save, Discard or Cancel first, and Cancel leaves it unlocked; KeePassXC does not tell housekey the answer, so housekey then says it cannot tell whether it locked. - Enrol, revoke and rotate change the database's file, so KeePassXC is locked first - and if it stopped to ask about unsaved changes, the change fails and nothing is written, unless
--force: it writes back the housekey data it read whenever it saves, and would otherwise undo an enrolment - or a revocation - at its next save. A rotation is complete, unlike gocryptfs's: a new key file, the database re-encrypted under it, the new wraps in its header, in one write. housekey re-encrypts the contents as they are and never parses them, so nothing in the database is lost to a field housekey does not know. - New databases only. Entries from an existing database move in with KeePassXC's import or merge.
vault add FILE.kdbxadds a housekey keepass vault made elsewhere - a synced copy - to this machine's configuration. - The key derivation is light (Argon2id, 16 MiB, one pass): it exists to slow down guessing a password, and this database has none - its key is 32 random bytes. A heavy one would only make every open slower.
- Paper:
housekey vault masterkey passwordsshows the key file's 32 bytes as 64 hex digits; a file holding exactly those digits, with no spaces and no line break, is a key file KeePassXC accepts, though it calls the format legacy.--format xmlshows the same bytes as a whole KeePass XML key file instead, with the hash that catches a mistyped digit: copy the block into a.keyxfile. Either way it goes to the terminal only, and it changes at every rotation. - Never give it a password in KeePassXC, or another key file: housekey hands KeePassXC the key file alone, and a database that needs more than that no longer opens with housekey. Nothing is lost if it happens - housekey's data stays in the header and its keys still unwrap the key file - and
housekey vault repair NAMEputs it back: a key as foropen, then the password that was added, checked against the database's header, and the database re-encrypted under the key file alone. Its wraps do not change, so nothing is enrolled again. Meanwhilevault masterkeystill shows the key file, with a warning. - Merging another database in, or this one into another: KeePassXC's Merge From Database asks for the other database's credentials even when it is open. A housekey vault's are its key file:
housekey vault masterkey NAME --format xml, the block copied into a.keyxfile in$XDG_RUNTIME_DIR, no password, andshred -uon it afterwards. - Back the database up. Its header holds every key's wrap: losing the file loses the vault, whatever keys you hold.
Needs KeePassXC and dbus-send (the package suggests both; install them yourself), and a desktop session; --cli needs only keepassxc-cli, which comes with KeePassXC, and a terminal. Verified against KeePassXC 2.7.6: it keeps housekey's data across saves, including one that rebuilds the header, and keepassxc-cli opens, edits and lists a database housekey made, before and after a rotation, in its shell and one command at a time.
Bootdisk vaults¶
Status: supported with dracut. Boot unlock has been dependable on a test machine through two installs. On Ubuntu 26.04 (LVM on LUKS on NVMe) it has unlocked the root in the initrd, consistently since 3.7.8: by a fingerprint on two biometric tokens, a PIN token's PIN, the TPM's PIN once the TPM was enrolled, an Android mobile on the USB cable (4.11), and the passphrase after the wait with no token; with the splash and on the console alone; a wrong PIN or an unmatched fingerprint asked again; and, on a volume with housekey's keyslots only, the wait for a token without end - that volume runs with no passphrase keyslot. On Ubuntu 26.10 with the installer's encrypted ZFS root, its LUKS keystore taken over (4.14.0) has unlocked with a FIDO2 token, the mobile on the cable and the TPM's PIN, with the splash and without it. On Fedora 45 (5.0.1, from the rpm packages), the installer's LUKS root with btrfs on a Surface Pro 2 was taken over, a key enrolled, and the root unlocked in the initrd by a FIDO2 token and by an Android mobile on the USB cable; the TPM is untried there. A ZFS root keyed by housekey itself (housekey-boot-unlock, 4.14.0) has not been booted yet: it is tested against a TPM simulator, the mobile simulator and a pretend zfs. Before you remove the passphrase keyslot on a machine, boot it with each key it will rely on, and keep a cryptsetup luksHeaderBackup off the machine. Shared and disk vaults are unaffected.
A LUKS container the machine boots from is taken over with vault add --type bootdisk and unlocked by the initrd, through libcryptsetup-token-heft.so, which the housekey-boot package installs. housekey itself never opens or closes it.
sudo apt install ./housekey_*_amd64.deb ./housekey-boot_*_amd64.deb
# or on Fedora:
# sudo dnf install ./housekey-[0-9]*.x86_64.rpm ./housekey-boot-*.x86_64.rpm
sudo housekey vault add /dev/disk/by-uuid/a39a... --type bootdisk
housekey-boot carries the plugin and the dracut module, and regenerates the initramfs on install. It depends on housekey at exactly the same version: the two share the record format, and a skew between them is the one failure the shared vectors exist to catch. Only machines with a bootdisk vault need it.
Building it needs libcryptsetup-dev, libfido2-dev, libtss2-dev, libssl-dev and a Rust toolchain on the build machine only; make deb-boot-arm64 cross-builds the plugin in a container, as the Go side already does. To install from a source tree without packaging:
housekey-initramfs is what the package runs too, and what to run after changing /etc/crypttab. It rebuilds each initramfs that exists, in place and by name - /boot/initrd.img-<kernel> (Debian, Ubuntu) or /boot/initramfs-<kernel>.img (Fedora, 5.0.1), and the boot loader spec copy on the EFI partition where there is one - and checks the plugin is in each. Not dracut --force --regenerate-all: that stops at the first stale directory under /lib/modules, and dracut's default output is not always the image the boot loader reads, so a rebuild can succeed and the machine still boot without the plugin - and ask for the passphrase. sudo lsinitrd /boot/initrd.img-$(uname -r) | grep token-heft (on Fedora /boot/initramfs-$(uname -r).img) says whether the image you boot has it.
bootdisk is a separate type rather than a flag on disk because the consequences differ in kind: the vault is unlocked before housekey exists, housekey must refuse to touch it, and a mistake costs a rescue disk rather than an error message. --type is required to take a container over for the same reason: the difference between the two should not be a default you did not choose. Taking a bootdisk over refuses to start unless dracut and the plugin are both installed, prints the /etc/crypttab line to apply, and leaves systemd's TPM keyslot alone.
A ZFS root (4.13.0, not yet tried on a machine). Ubuntu's installer encrypts a ZFS root by keeping the pool's key in a small LUKS volume inside the pool - the zvol rpool/keystore, opened as keystore-rpool and mounted at /run/keystore/rpool, the pool's keylocation a file there. That LUKS volume is what housekey takes over, as a bootdisk:
sudo housekey vault add /dev/zvol/rpool/keystore --type bootdisk
sudo /usr/lib/housekey/housekey-initramfs
At boot OpenZFS's dracut module imports the pool and opens the keystore through systemd-cryptsetup, which hands it to the plugin, so it unlocks with a key exactly as a LUKS root does; ZFS then loads its key from the file. The ZFS key itself never changes, and /etc/crypttab plays no part. Ubuntu's zfs module opens the keystore under dracut from 25.10; on a release whose module does not (24.04, and Linux Mint 22 on it), housekey-boot's dracut module adds a hook that does it first, the same way. housekey knows the keystore by what / is on - the root's encryption root keeps its key under /run/keystore/ - so it is a boot volume, never closed, and taken over only as a bootdisk, under the name the zfs module gives it. Taking it over also needs OpenZFS's dracut module (zfs-dracut). A ZFS root encrypted under a key of its own, with no keystore, is taken over itself (next).
A ZFS root keyed by housekey (4.14.0, not yet tried on a machine). A ZFS root encrypted under a passphrase of its own - a manual install, or ZFSBootMenu's - is taken over as a disk vault on ZFS is: its key replaced with housekey's, wrapped to each key in its own properties, the old one put back on any failure.
sudo housekey vault add rpool --type bootdisk # its encryption root; asks the passphrase, then a key
sudo housekey vault masterkey ROOT # the recovery key: write it down now
sudo /usr/lib/housekey/housekey-initramfs
At boot housekey-boot-unlock, put in the initramfs by housekey-boot's dracut module, reads the root's housekey properties once the pool is imported, asks a key in housekey's order - a token, a mobile already on the USB cable, this machine's TPM with its PIN, a mobile plugged in later - opens the wrap that key is enrolled with and gives the key to zfs load-key on its standard input. The recovery key always opens the root, so the wait for a token is bounded (housekey.token_wait=), as on a LUKS volume with a passphrase; then it asks for the recovery key - the 64 hex characters vault masterkey shows - and Enter with nothing typed asks the keys again. OpenZFS's own prompt, after it, takes the same 64 characters. Enrolling or revoking a key, and rotating, change the dataset's properties, not the initramfs: nothing to rebuild.
A bootdisk vault has no mount_point: the initrd mounts it as / long before housekey runs.
Then reboot, unlock with a key, and only then:
At boot, the plugin waits for the splash to come up (up to 5 s, when the kernel command line asks for one), then for a FIDO2 token to appear: 8 s from when it says so on screen, or housekey.token_wait=SECONDS on the kernel command line. Then this machine's TPM, if it is enrolled on the volume, then the passphrase. When every active keyslot is housekey's and the TPM is not enrolled, nothing else could open the volume, so it waits for a token for as long as it takes. A token that is plugged in is asked until it is verified, never passed over for the TPM or the passphrase; to get past it, pull it out. What it wants is said on the console and on the splash (plymouth display-message), and with the splash up a PIN is asked for there by the plugin, naming whose it is: "PIN for your security key" or "PIN for this machine's TPM" (4.2.2).
dracut only. initramfs-tools has no notion of LUKS2 header tokens, so nothing there would ever call the plugin. Fedora uses dracut, and Ubuntu 25.10 and later do by default; on a machine still using initramfs-tools, switch it before taking a bootdisk over, and test that in a VM first.
systemd's TPM keyslot is the thing to think about. It is the one systemd-cryptenroll --tpm2-device made, and it opens the disk with no key and no PIN, which is the whole point of wipe-tpm. Removed, every boot needs a verification at the console - a FIDO2 key, or this machine's TPM PIN if the TPM is enrolled with housekey: no unattended reboot after a kernel update, no remote reboot that comes back on its own, and a headless machine that will not return until somebody visits it. That is a reasonable trade on a desktop and a bad one on a Pi in a cupboard. housekey vault info prints every remaining way in, so it is a question with a printed answer. housekey's own TPM2 key is a different thing: it always needs its PIN, and is removed like any other key, with revokekey.
Keep a passphrase keyslot. add refuses to take a container over without one, and wipe-tpm refuses to remove the last non-key slot. It is what stands between a wrong guess about the initramfs and a rescue disk.
Leftover systemd-cryptenroll tokens. Taking a container over with vault add removes any tokens systemd-cryptenroll left in its header, along with their keyslots, authorised by the passphrase it already asks for. This is not tidiness: at boot, systemd-cryptsetup tries every token in the header, so a leftover systemd-fido2 token reintroduces exactly the one-prompt-per-keyslot behaviour housekey exists to avoid. Taking it over is refused if every keyslot belongs to some token, because there would be no passphrase to fall back on, and prints what it found before removing anything. housekey vault info lists every way into a vault - housekey keyslots, TPM, foreign tokens, and slots claimed by nothing.
Evil maid is out of scope. The initramfs is unencrypted, so a modified one can take the secret your key hands it, or the TPM PIN you type. Sealing to PCRs would resist that; neither a FIDO2 key nor housekey's PIN-only TPM key does. Fixing it needs a signed boot chain - Secure Boot with a signed UKI - which is a separate piece of work.
A vault from another machine¶
A vault made or taken over elsewhere already carries everything housekey needs - a shared vault's record in ROOT/vault.keys, a LUKS container's header token, a keepass vault's own database header - so another machine only has to be told where it is:
housekey vault add ~/nas/docs # a shared vault's root
sudo housekey vault add /dev/sdb1 # a removable LUKS container
housekey vault testkey docs # prove a key opens it
housekey vault open PATH does the same on the way: a path that is not configured but is a housekey vault is offered to be added (y/N, or --yes), and then opened. A path that is configured opens that vault, whichever spelling of it is given. open never takes a volume over.
Adding a housekey vault asks for a name and a mount point and writes one section to the configuration. Nothing on the vault changes and no key is needed, so --key-type, --label, --realm, --passphrase-file and --with-master-key are refused, and --type, if given, has to agree with the vault's record. A LUKS container is recorded by its /dev/disk/by-uuid path whatever it was named by; reading its header takes root, so add one under sudo. With no configuration yet, one is created with the vault's realm; a vault from another realm is refused, as is one already configured, and a boot volume anywhere but the machine it boots.
housekey vault candidates finds them: it marks each LUKS container as configured, a housekey vault to add, or not housekey's (to take over, with --type). Configured containers are marked from the configuration alone; telling the others apart means reading their headers, which takes root: run it under sudo, or they are listed with n/a against them. housekey vault candidates --type shared DIR does the same for DIR and the directories directly under it.
After a shared vault is taken over on one machine, this is how every other machine that used it picks it up: the takeover changed its password and, for a plain gocryptfs directory, moved it into ROOT/vault.enc.
Another machine's boot disk¶
4.15: a LUKS root, tried on hardware from live systems; 4.16: a ZFS root keyed by housekey, tried on a disk, read-only and read-write; the keystore layout and a pool named as one here against a pretend ZFS. A boot disk is never opened or closed from a session - except one that does not boot this machine: plugged in here because its own machine will not boot, or this machine's own seen from a rescue system. --foreign names it by its device, and nothing goes in the configuration:
sudo housekey vault open /dev/sdb3 --foreign # read-only
sudo housekey vault open /dev/sdb3 --foreign --read-write
sudo housekey vault close /dev/sdb3
sudo housekey vault revokekey /dev/sdb3 --foreign --read-write --label lost-token
From a rescue system with no housekey configuration, the realm is the one the disk's record names, for that command alone: nothing is written to /etc/housekey. close and testkey write nothing to the disk, so they take a device that is no configured vault's without --foreign; open and the key changes need it.
It opens with the keys enrolled on it, in the usual order (this machine's TPM only if it is enrolled there: the rescue-system case). housekey assumes nothing about what is inside, since that may be what went wrong:
- The container is unlocked as
housekey-foreign-ID, ID the first eight hex digits of its LUKS UUID. - LVM in it is read with lvm's report commands alone -
--readonly,--devicesthat one mapping - and each plain, linear logical volume is mapped by housekey with dmsetup ashousekey-foreign-ID-LV. LVM never activates the volume group, so a group with the same name as one here (twoubuntu-vg) needs no rename, and nothing is written to the disk's metadata. If LVM activates it by itself when the disk is unlocked, housekey takes that down again and says so. Thin, RAID, snapshot and cache volumes, and one partly on another disk, are listed with why, and not mapped. - Every volume blkid finds a filesystem on is mounted at
/run/housekey/foreign/ID/LV(/run/housekey/foreign/ID/fswith no LVM; a btrfs at its top level, every subvolume under it). Nothing is picked as the root and the disk's fstab is not read: a chroot, and its bind mounts, are yours.
Without --read-write every mapping is read-only, so nothing reaches the disk, not even a journal replay: ext3/ext4 mount with noload, XFS with norecovery, btrfs with rescue=nologreplay, showing a filesystem that was not unmounted cleanly as it was. Key changes always write the header, so enrolkey, revokekey and labelkey need --read-write too; this machine's TPM is never enrolled on another machine's disk. Every command says the disk is another machine's, and what it does to it.
close unmounts only what open mounted, and refuses - naming it - anything mounted inside those mounts (unmount a chroot's bind mounts yourself, with care: under shared propagation, unmounting a bind of /dev carelessly can take the host's /dev/pts with it) or one of the disk's volumes mounted elsewhere. close --all and autolock never touch a foreign disk. A ZFS root from another machine cannot be opened this way yet.
A ZFS root (4.16.0). Name a device of its pool: sudo housekey vault open /dev/sdb4 --foreign. Its pool's name is likely one this machine has too (rpool), so housekey imports it by its id under a name of its own, housekey-foreign-ID (ID the first eight hex digits of the id), with zpool import -t: the name lasts until the export and is never written to the pool. Without --read-write it is imported readonly=on, so nothing at all is written to it; with no cache file, so this machine does not import it at its next boot. Its key comes from its keystore - Ubuntu's installer keeps the pool's key as a file in a LUKS volume inside the pool, rpool/keystore, which housekey takes over as a boot disk: housekey opens it read-only with your key, reads the file and closes it again - or, for a root keyed by housekey, from housekey's wrap; either way the key goes to zfs on stdin, never from the path the pool names, which is its own machine's. Every filesystem the key opens is mounted at /run/housekey/foreign/ID/POOL/DATASET - /run/housekey/foreign/112210f4/rpool/ROOT/ubuntu_ab12cd, its var inside it - whatever its mountpoint or canmount say, so Ubuntu's root (canmount=noauto) is mounted with the rest and none is picked as the root; datasets with canmount=off (containers such as rpool/ROOT) are listed and not mounted, and so are any under a key that is not loaded. Only the named pool is imported: bpool, where Ubuntu keeps /boot, is yours to import if you need it. close unmounts what open mounted and exports the pool. A ZFS root's keys are not changed from another machine yet.
As yourself, or as root¶
housekey does what it is asked as whoever runs it, and never elevates itself.
- A shared vault is yours. Its gocryptfs mount belongs to the user who makes it, so
housekey vault open docs, with no sudo. Under sudo housekey would not even find it: root reads the machine's configuration alone. - A disk or bootdisk vault is root's. Reading a LUKS header, changing keyslots, unlocking, mounting and writing
/etc/housekey/housekey.confall take privileges an ordinary user does not have, sosudo housekey vault open secure, and the same forclose,enrolkey,revokekey,labelkey,testkey,add,rename,forgetandwipe-tpm;sudo housekey statusreads whathousekey statusshows as n/a.
Without the privileges, a command says so and stops with exit status 5, before any key is asked to verify, and gives the line to run:
$ housekey vault open secure
housekey: opening secure needs elevation: alice cannot read /dev/disk/by-uuid/a39a54ca-...
Run it with elevation:
sudo housekey vault open secure
The reports still work as you. vault ls and vault info print what can be seen unprivileged - the configuration, whether the vault is open - in the same layout, with n/a against what could not be read (the keys and keyslots in the header, whether an unlocked vault is pending close) and a note on stderr saying why; --json lists the same under not_available. vault candidates lists unconfigured containers with n/a. close --all and autolock close what you can close and leave the disk vaults to root's own sweep.
What is checked is what the process can do, not who it is. Someone in the disk group can read and write a header, so info, enrolkey and revokekey work for them without sudo; unlocking and mounting take CAP_SYS_ADMIN, which in practice means root. That is what --scope user is for: a disk vault in your own file, for a user who does not need sudo to use it.
Two things to know about sudo:
- With PAM set up for FIDO2, sudo's own prompt is a touch of the token, and then housekey's verification is another: two, as it always was for a disk vault, now with sudo's first.
- sudo does not pass
HOUSEKEY_*variables on. Give answers as flags, or inside the sudo:sudo HOUSEKEY_LABEL=spare housekey vault enrolkey secure.