Examples¶
A new shared vault¶
Install housekey and a shared vault's tools, make a folder for the vault on the share, and create it there:
sudo apt install ./housekey_*_amd64.deb # from a release, or build it: see Installation
sudo apt install gocryptfs fuse3 # a shared vault's tools: the package suggests them, it does not install them
mkdir -p /mnt/nas/Documents/myvault
cd /mnt/nas/Documents/myvault
housekey vault create --type shared # five prompts, all with sensible defaults
create lets gocryptfs print the master key to your terminal, once. Write it on paper for a permanent offline recovery.
housekey vault enrolkey myvault --label my_yubikey5 # each further key, one at a time
housekey vault open myvault
housekey vault close myvault
Adding what already exists¶
Anything that already exists is added with one verb, vault add PATH. housekey reads PATH before it asks anything, and what it finds decides what adding means: a housekey vault - made on another machine - is only written into this machine's configuration, with nothing changed on it and no key needed; a volume that is not housekey's is taken over, which changes it, so it is taken over only when --type says what it is to become. Without --type, housekey stops and says what taking it over would do.
A LUKS disk¶
For a local encrypted disk that already exists:
sudo apt install cryptsetup
sudo housekey vault candidates # find the container, copy its path
sudo housekey vault add /dev/disk/by-uuid/a39a54ca-... --type disk
sudo housekey vault open secure
A disk vault is root's work throughout, so those run under sudo; a shared vault is yours, and never does. See As yourself, or as root.
Taking over a LUKS container adds one keyslot and one header token. It changes nothing already in the header - your existing passphrase keyslot stays exactly where it is, and you should keep it.
A gocryptfs volume¶
For a gocryptfs volume that already exists:
A plain gocryptfs directory - what gocryptfs -init DIR makes - is moved into housekey's layout in place: DIR keeps its name and becomes the vault root, and the volume moves to DIR/vault.enc, by three renames on one filesystem, nothing copied. Anything that used the old path, such as another machine's mount or a backup job, needs the new one. A volume already laid out as DIR/vault.enc is not moved.
Taking a gocryptfs volume over replaces its password. A gocryptfs volume has exactly one password, and housekey's wraps hold the passphrase that opens it, so the old password cannot simply be kept beside housekey's keys. After a warning and a y/N confirmation, add --type shared checks the current password against vault.enc/gocryptfs.conf, verifies the first key, changes the password to a random one nobody sees (gocryptfs -passwd, both passwords down a pipe), and wraps that for the key. From then on the vault opens only through housekey, with an enrolled key, or with the volume's gocryptfs master key; anything that opened it with the old password - another machine, a script, an fstab line - stops working. Secure the master key before taking it over: if the paper copy is lost, gocryptfs-xray -dumpmasterkey ROOT/vault.enc/gocryptfs.conf shows it, given the current password, and afterwards nobody knows the password to give it.
A volume whose password nobody knows - one taken over by another housekey realm, being moved - is taken over with --with-master-key: give its gocryptfs master key (from that tool's vault masterkey) instead of the password, typed hidden or from --passphrase-file. housekey checks the key against the volume's own files - the first block of a file must decrypt with it - before anything changes, then writes gocryptfs.conf itself with the key wrapped under the new random password. That is what gocryptfs -passwd -masterkey does, without the key on a command line, where ps and the shell's history keep it, and without the hard link gocryptfs backs the config up with, which a share that squashes identities refuses (fs.protected_hardlinks: every file there is someone else's). The old config is kept as gocryptfs.conf.bak until the key is enrolled, and put back if anything fails. A volume with no file content yet has nothing to check the key against, and is refused: use its password.
If anything fails before the key is enrolled, the original password is put back and the volume moved back where it was. Once the key is enrolled the original is scrubbed from memory. The record and the first wrap go into ROOT/vault.keys, and nothing in the ciphertext changes. Volumes made with gocryptfs -fido2, reverse-mode volumes and volumes whose config is kept elsewhere (-config) are refused.