Skip to content

Backup and recovery

What to back up

Your keys are not what you back up: several keys enrolled on each vault are the backup for any one of them. What has no spare is the small amount of data each vault keeps beside its contents, and one way in that needs no key at all.

Vault Back up The way in without a key
shared (gocryptfs) the encrypted folder, and above all its vault.keys directory: it holds every key's wrap the paper master key (housekey vault masterkey NAME)
keepass the .kdbx file: its header holds every key's wrap the key file (housekey vault masterkey NAME, --format xml for a .keyx)
disk (LUKS) a header backup (cryptsetup luksHeaderBackup), re-taken after any revocation the passphrase keyslot housekey leaves in place
disk (ZFS) the dataset: its properties hold the wraps, and zfs send -p or -w carries them the 64 hex characters housekey vault masterkey NAME shows
bootdisk as for LUKS, kept off the machine the passphrase keyslot - remove it only after booting with each key you rely on; a ZFS root keyed by housekey has its recovery key (vault masterkey) instead

Keep the paper copies away from the computer, and never photograph them or save them in a file. A header backup opens the disk with any one key it lists, so guard it like the disk. See LUKS specifics and ZFS specifics.

Recovery

A key is stolen and the PIN is known to the thief. housekey vault revokekey NAME --label LABEL, with a key that is staying to authorise it. On a shared vault that also rotates the passphrase, so a copy of the stolen key's wrap no longer opens the vault as it is now. What rotation cannot change is the gocryptfs master key: a snapshot or archive from before the revocation holds an old gocryptfs.conf and the old wrap, which together still give the master key to the stolen key. Expire those if that matters; only a new vault and a copy of the files change the master key. With the key in hand, housekey key erase removes the credential and reclaims its resident slot - which needs the key's PIN, because credential management is PIN-gated by CTAP even on biometric keys.

A TPM PIN is forgotten, or the TPM is reset or replaced. The TPM key is gone for good: there is no reset that keeps it. Open with a FIDO2 key, housekey key erase --type tpm2 if the old key is still there, housekey key init --type tpm2, and enrol this machine on each vault again; revoke the old label with revokekey. A TPM in lockout recovers on its own, one failure forgotten per interval; a FIDO2 key opens meanwhile.

A mobile is lost. Revoke it on each vault it is enrolled on, as for a token. Someone holding it still needs your fingerprint or its screen lock, and to be on your network, for it to answer. If the mobile and the machine's TPM are your only keys and both are lost at once, what is left is the paper master key (shared), a LUKS passphrase keyslot (disk), or vault masterkey's key file (keepass): keep one of those, or a token, as well.

The wrap directory is lost. This is the real single point of failure for a shared vault - not the keys, there are several of those. Losing vault.keys bricks every key at once while the hardware is intact. It is tiny. Put it in the offsite backup.

Everything is lost. The paper master key bypasses the whole chain and needs only the ciphertext directory:

gocryptfs -masterkey=stdin /path/vault.enc /mnt/vault

gocryptfs asks for the key. Never put it on the command line (-masterkey=KEY): ps shows it to every user while gocryptfs runs, and the shell's history keeps it.

The paper master key is lost. housekey vault masterkey NAME shows it again, on the terminal, after a verification with any enrolled key: housekey unwraps the passphrase as vault open does and hands it to gocryptfs-xray -dumpmasterkey on a pipe, and gocryptfs-xray writes the key straight to the terminal - it never passes through housekey. This is the only way to see it for a vault taken over with add --type shared, whose password nobody knows. For a keepass vault it shows the key file instead (see KeePass vaults). A LUKS vault has none: its way back without a key is its passphrase keyslot and a header backup.

Test your recovery. The key you never test is the one that fails when you need it. housekey vault testkey NAME with each key in turn costs a minute.