Skip to content

Frequently asked questions

How do I lock every vault overnight?

close --all and info --all act on every configured vault, so a sweep is one line rather than one line per vault. A vault that is already closed is passed over silently; nothing is printed unless something happens.

--all is a flag rather than the default for a bare close: the difference between closing one vault and closing all of them should not be an argument that is not there.

For shared vaults, from your crontab (crontab -e, not /etc/crontab): a FUSE mount made by you can only be unmounted by you, and a user crontab has HOME set so your file is found.

0 3 * * * housekey vault close --all --force

For disk vaults, from root's crontab. Root reads only the machine's file, so nothing more is needed.

0 3 * * * housekey vault close --all --force

Your sweep sees the machine's disk vaults too, but closing them takes root, and housekey does not elevate itself: close --all passes over them - listed as left_to_root under --json, and said on stderr when there is a terminal to say it on - and leaves them to root's. vault autolock does the same.

Without --force, a vault something still holds open is refused, and the processes holding it are listed. --force skips that check, unmounts lazily and, for LUKS, closes with cryptsetup close --deferred, so the vault is torn down when the last user lets go rather than being left unmounted but unlocked. (--deferred-remove is dmsetup's spelling; cryptsetup rejects it.) vault autolock always behaves as if --force were given.

Pending close. A lazy unmount only takes the mount out of this mount namespace. A container, a snap or a systemd service with PrivateTmp= started while the vault was mounted has its own copy of the mount, and a process with a file open on it holds it too; either keeps the LUKS mapping alive - unlocked - until it lets go. housekey reports that state as pending close: vault close says so instead of failing with cryptsetup's "still in use" (exit 0 under --force, which asked for exactly this, and 1 without); vault info and vault ls say pending close (under sudo: only device-mapper knows, and it tells only root; without, they say unlocked and that the rest is not available); and vault open asks for a key before mounting it again. housekey does not go looking for the holder or unmount other namespaces: stop the container or service, and the vault locks. sudo grep -l ' /secure ' /proc/[0-9]*/mountinfo finds which processes still see the mount.

Can my vaults lock when I unplug my key?

Yes, with a udev rule. housekey's source has it as packaging/99-housekey-autolock.rules; the packages do not install it, because it has to name you. It has two lines, because a vault is closed by whoever can close it: one drops privileges with systemd-run --uid= and closes your shared and keepass vaults - udev fires as root, which cannot unmount your FUSE mount and does not read the configuration under your home directory - and one runs as root and closes the machine's disk vaults. Leave out the line you have no use for.

ACTION=="remove", SUBSYSTEM=="hidraw", ENV{ID_FIDO_TOKEN}=="1", \
  RUN+="/usr/bin/systemd-run --no-block --uid=1000 --setenv=HOME=/home/alice --setenv=XDG_RUNTIME_DIR=/run/user/1000 /usr/bin/housekey vault autolock"

ACTION=="remove", SUBSYSTEM=="hidraw", ENV{ID_FIDO_TOKEN}=="1", \
  RUN+="/usr/bin/systemd-run --no-block /usr/bin/housekey vault autolock"

Save it as 99-housekey-autolock.rules, putting your user name and uid in place of alice and 1000. udev gives commands almost no PATH, so housekey is named by its full path: /usr/bin/housekey from the packages, or /usr/local/bin/housekey after make install. Then:

sudo install -m644 99-housekey-autolock.rules /etc/udev/rules.d/
sudo udevadm control --reload

Pull the last token and journalctl -b | grep housekey shows what each line did.

The policy is "no FIDO2 key present at all", not "no enrolled key": resident credentials cannot be enumerated without the key's PIN, so a precise check would prompt on every USB event. An unrelated key left plugged in suppresses autolock. A vault opened with this machine's TPM or a mobile is left open: no token was plugged in to open it. This is ergonomics, not a security control - once mounted, the key is in memory and the hardware is irrelevant until the next unlock.

Which key opens which vault?

housekey key ls            # the keys here: label, type, id, and state
housekey key ls --all      # every key of the realm, plugged in or not, the same way
housekey vault ls --keys   # which key opens which vault: a row per key, a column per vault

key ls prints a line per key here: its label, type, id, whether it is here, and its state - how a token verifies, or why it cannot be used; the TPM's PIN attempts left. key ls --all prints the same for every key of the realm, other machines' TPMs and mobiles among them. Neither lists vaults; vault ls --keys does, with yes, -, n/a for a vault whose keys could not be read, and label for a key enrolled there under the same label but with no id recorded.

Each vault records its keys' ids beside them, so a key is the same key on every vault whatever its label there; a token tells its own id, from its credential, with no PIN and no touch. A token enrolled before 4.0.8 has no id recorded until it is next proven present - when it opens a shared vault, or authorises a change to a disk or keepass vault's keys - and is matched by its label until then. A disk vault's keys are in its header, so as yourself its column is n/a; under sudo only the machine's vaults are read. Nothing here costs a verification.

Can key material end up in swap?

housekey keeps key material out of core files - core dumps are disabled for the whole process - and tries to lock its memory into RAM so none of it can be swapped out. The lock works only as root: the kernel wants ulimit -l to cover the whole address space, and a Go program reserves more than a gigabyte of that up front. So housekey run under sudo, for a disk vault, is locked, and an ordinary user's housekey, for a shared one, is not.

That matters only if swap is unencrypted. housekey checks /proc/swaps and says nothing when there is no swap, when it is zram (compressed RAM), or when it is on dm-crypt - an encrypted swap partition, or a swap file on an encrypted root, LVM inside LUKS included. Otherwise a command that handles key material warns once, naming the swap area. A hibernation image is written to swap, so the same answer covers it. To fix it, in order of preference:

  • Encrypt swap: a swap file on the encrypted root filesystem, or a swap partition in /etc/crypttab with a random key (no hibernation), or inside the LUKS volume.
  • Use zram instead of disk swap (zram-tools or systemd-zram-generator).
  • Turn swap off (sudo swapoff -a, and remove it from /etc/fstab).

Raising ulimit -l far enough (to unlimited, in /etc/security/limits.d/) also works, but affects every program that user runs.

How do I see what housekey is doing with a key?

--trace, or HOUSEKEY_TRACE=1, reports every operation that talks to a key or to cryptsetup, with timings:

sudo housekey --trace vault open secure

A long gap between an operation's begin and end line is the key waiting for a person. That is how to tell one assertion collecting two gestures - user verification and user presence are separate checks, and on a biometric key both are the same motion - from two assertions, which look identical from the outside but mean something has gone wrong.

What does housekey not protect against?

Sharing with another realm. Someone you trust can have their key enrolled on your vaults, in your realm. What is not designed is sharing a vault with a different realm: every key is enrolled into one realm - a token's public key is even derived per vault, from its credential under the realm's relying-party id - and someone outside the realm has no key in it.

Sealing to the platform. A key proves possession, not that the machine booted the software you installed. That includes housekey's TPM2 key, which is bound to the TPM and its PIN but not to PCRs. Bootdisk vaults are supported, but the initramfs is unencrypted and a modified one can take the secret your key hands it. PCR sealing covers that and none of housekey's keys does; it answers a different question, and needs a signed boot chain to be worth having.

Destroying a vault. There is no command for it. vault forget removes the configuration section and nothing else - the ciphertext, the wraps, the keyslots and the header token all stay exactly as they are, and it prints the section back so it can be pasted in again. Destroying data is cryptsetup erase, or rm, and should not be reachable by a typo in a vault name.

Defence against live compromise. Once mounted, the key is in memory and the data is open to anything running as you. This protects data at rest and gates opening it behind possessed hardware.