Command line¶
Vocabulary¶
Three nouns, and the command line is built from them: housekey vault ..., housekey key ..., housekey config ....
| vault | what a key opens: an encrypted volume, or a password database. One of four types. |
| key | a thing that can unlock a vault, and verifies you every time it does: a FIDO2 token, this machine's TPM2 with a PIN, or a mobile running the housekey app (Android, or iOS). One of four types. |
| config | the configuration: the machine's file and yours, which name the realm and the vaults (see Configuration). |
A realm names the fleet of keys, machines and vaults that open each other (see Realms). A token is a FIDO2 security key - a YubiKey, say; in a LUKS2 header a header token is something else, the JSON object where housekey keeps a disk vault's record.
| Vault type | Is | Unlocked by |
|---|---|---|
| shared | gocryptfs, file-level, stacks over an NFS mount, safe from several machines at once | housekey vault open |
| disk | LUKS2, block-level, one host at a time; or an encrypted ZFS dataset (see ZFS specifics) | sudo housekey vault open |
| bootdisk | the LUKS2 container this machine boots from (dracut only, see Bootdisk vaults) | the initrd, through the plugin |
| keepass | a KeePassXC database (KDBX 4) with a key file and no password; one file | housekey vault open, which hands it to KeePassXC |
"Key" and "keyslot" are doing different jobs and always will: a key is the thing in your pocket or in the machine, a keyslot is a LUKS2 structure. Where this document needs the 32 bytes a key derives, it calls them the key secret.
| Key type | Is | Verifies by |
|---|---|---|
| fido2 | a token's resident credential with hmac-secret |
fingerprint, or the token's PIN |
| tpm2 | one HMAC key per machine, generated inside its TPM | a PIN, with the TPM's dictionary-attack lockout |
| android | one ECDH key per Android mobile, generated in its TEE or StrongBox, reached over the LAN | fingerprint, or the mobile's screen lock |
| ios | one ECDH key per iPad or iPhone, in its Secure Enclave, reached over the LAN as a mobile is; unattested | Touch ID or Face ID, or the device's passcode |
Commands¶
hkey is installed beside housekey as a short alias for it.
housekey TARGET ACTION [ARGUMENT] [options]
status what this machine has and can do, in brief
vault
create create a shared, keepass or ZFS vault and enrol the first key
[--type TYPE] [--name NAME] [--vault-root PATH]
[--mount-point PATH] [--database PATH]
[--dataset POOL/NAME] [--key-type TYPE] [--label LABEL] [--realm NAME]
[--scope SCOPE] [--no-master-key]
add PATH add an existing vault, or take over a gocryptfs volume, LUKS container or ZFS dataset
[--type TYPE] [--name NAME] [--mount-point PATH]
[--mapper-name NAME] [--key-type TYPE] [--label LABEL]
[--realm NAME] [--scope SCOPE] [--passphrase-file PATH]
[--with-master-key]
open [NAME|PATH] unlock and mount
[--type TYPE] [--cli] [--foreign] [--read-write]
close [NAME] unmount and re-lock
[--all] [--force] [--foreign]
autolock close every vault if no FIDO2 key is present
[--force]
enrolkey [NAME] add a key to a vault
[--type TYPE] [--label LABEL] [--force]
[--foreign] [--read-write]
revokekey [NAME] remove a key's access to a vault
[--label LABEL] [--force] [--foreign] [--read-write]
labelkey [NAME] change the label a key is enrolled under
[--label LABEL] [--new-label LABEL] [--force]
[--foreign] [--read-write]
rotate [NAME] replace a shared or keepass vault's secret, wrapped again to every key
[--type TYPE] [--force]
wipe-tpm [NAME] remove systemd's PIN-less TPM keyslot, once a key boot has worked
ls (or list) every configured vault, one line each
[--keys]
info [NAME] paths, keys and state for one vault
[--all]
testkey [NAME] check a key still opens this vault
[--type TYPE] [--foreign]
masterkey [NAME] show a shared or keepass vault's master key, for paper recovery
[--type TYPE] [--format FORMAT]
repair [NAME] put back a keepass vault whose credentials were changed in KeePassXC
[--type TYPE] [--force]
candidates [DIR] LUKS containers here, or vaults under DIR, and which are housekey's
[--type TYPE]
rename OLD NEW rename a vault in the configuration
forget NAME remove a vault from the configuration
key
ls (or list) connected FIDO2 keys, and this machine's TPM
[--all]
info one key in detail
[--type TYPE] [--credentials]
init create this machine's key in its TPM, with a PIN
[--type TYPE] [--pin-file PATH]
changepin change a key's PIN, keeping its credential
[--type TYPE] [--pin-file PATH]
rename change the name a FIDO2 key gives itself in the realm
[--label NAME]
test self-test a key against the scheme, enrolling nothing
[--type TYPE] [--keep] [--two-salt]
erase delete this realm's credentials from a connected key
[--type TYPE]
config
info which files are in use, and what they say
init write a configuration file with a realm and no vaults
[--realm NAME] [--scope SCOPE]
test parse the files and report what they define
global options
-c, --config FILE configuration file (default $HOUSEKEY_CONFIG, ~/.config/housekey/housekey.conf)
-y, --yes answer every confirmation with yes
--non-interactive never prompt; a missing answer is an error naming its flag
--json one JSON object on stdout, what was done or found; narration on stderr
--print-answers after an interactive run, print the equivalent one-line command
--wait poll for a key to be plugged in (the default)
--no-wait ask for a keypress once a key is plugged in, rather than polling
--wait-timeout SECONDS how long the poll for a key waits (default 120); implies --wait
--trace report every key and LUKS operation, with timings
-h, --help help for housekey, a target, or an action
-V, --version print the version
housekey TARGET -h actions for one target, with their options
housekey TARGET ACTION -h what one action does, and its options
housekey completion SHELL a completion script for bash, zsh or fish
Shell completion is set up by the packages; see Shell completion.
--type names a vault type on create, add and candidates, and a key type everywhere else; on create and add the key type is --key-type.
housekey vault -h (or housekey vault help) lists one target's actions with their options; housekey vault close -h explains one action and each of its options. Global options go anywhere on the line.
-y only answers confirmation questions. It is not --force: vault close asks nothing, so -y changes nothing there, and a vault that is in use is still refused. See How do I lock every vault overnight? for what --force does.
The vault name may be left out while only one vault is configured.
housekey status is one screen of what this machine has and can do: the configuration files read, the vaults by type and whether each is open, the volume / is on and whether housekey unlocks it (with housekey-boot installed), the FIDO2 keys plugged in and how many more the vaults list, the mobiles, this machine's TPM and the vaults it is enrolled on, programs housekey runs that are not installed (marked when a configured vault needs one), and whether this session can open a disk vault itself or needs sudo. It asks for no key and no PIN; a disk vault's keys and the boot volume's header are root's to read, so as yourself they are n/a and sudo housekey status reads them.
Answering on the command line¶
Every question a command asks can be answered with a flag, so a vault can be created or added from a script without a single prompt:
housekey vault create --type shared \
--name docs --vault-root /mnt/nas/Documents/vault \
--mount-point ~/Vault --label yubikey5 --yes
Answers resolve in one order: flag → HOUSEKEY_* environment variable → prompt → default. --mount-point is HOUSEKEY_MOUNT_POINT, and so on. --non-interactive takes the default where there is one, saying which it took, and errors naming the flag where there is not.
--print-answers prints the one-line equivalent after an interactive run, which is how the second machine gets configured identically to the first rather than approximately.
Four things cannot be made unattended, and say so rather than pretending:
vault createneeds a terminal. gocryptfs suppresses the master key unless its own stdout is a terminal, so a run without one produces a vault whose paper recovery key was never displayed and can never be displayed again.--no-master-keyaccepts that deliberately.- Taking a volume over with
vault add --typeneeds the existing passphrase.--passphrase-file PATH, or-for stdin. There is no flag carrying the passphrase itself:pswould show it. enrolkeyneeds hands. Two keys: the enrolled one verifies, then the new one is plugged in - beside it, in its place, or from the start. housekey tells them apart by the credential each holds for the realm, read without a touch or PIN, never by port or by how many are plugged in. housekey polls for the new key (--wait-timeoutsets how long, 120 s by default), which is as close to unattended as it gets;--no-waitasks for a keypress once it is in instead. With nothing plugged in to authorise and a mobile enrolled, a terminal is still asked for Enter, which is how the mobile is chosen.- Enrolling a mobile needs the code it shows typed in. That is what proves the mobile that answered the QR is yours, so neither
--yesnor--non-interactivecan stand in for it. It also needs its platform named,--type androidor--type ios:--type mobileis refused there.
Scripting¶
Every command takes --json: one object on stdout with a v field, and everything else - narration, prompts, gocryptfs' own output - on stderr, so a pipeline gets stdout to itself. The master key never appears in either: it goes to the terminal or nowhere.
Read commands (vault ls, vault info, vault candidates, key ls, key info, config info) describe what they found. key ls reports the TPM under tpm; key info gives resident_used, resident_free, fleet_credentials, realms and error only with --credentials (with_credentials says which); vault info gives each key's type under key_details. key ls --all and vault ls --keys give the same object: vaults, and keys, each with its type, id, labels, here, and on (a vault and label each, by_label where the vault records no id for it), with not_available and unread naming the vaults not read.
Every other command reports what it did: command, ok, and what applies of vault, type, mount_point, key (the label), key_type, key_id, keyslot, config, changed (false when there was nothing to do, such as opening an open vault), and lists such as closed, failed, left_open or erased. rotate, and revokekey on a shared vault, add rotated, wrapped_to and dropped; vault rename adds old_name, vault labelkey old_label, and key rename realm, old_name and name. declined is true if a confirmation was answered no. A failure, from any command, writes "ok": false with exit (the exit status) and error, plus whatever the command had done by then:
housekey vault open docs --json
{ "command": "vault open", "ok": true, "vault": "docs", "mount_point": "/home/alice/docs",
"key": "yubikeybio", "key_type": "fido2", "changed": true, "v": 1 }
Nothing secret is ever in the object: labels, paths, keyslots and key ids only.
Exit codes:
0 |
it worked |
1 |
it did not |
2 |
a mistake in the command line, including an answer a flag would have given |
3 |
no suitable key: none connected, this machine's TPM is not enrolled, no mobile answered in time, or the key that verified is not enrolled on the vault |
4 |
needs a person at a terminal, and there is none - including to show a mobile its QR code |
5 |
needs elevation: a disk vault or the machine's configuration, as an ordinary user. The message gives the line to run under sudo |
3 is the one a wrapper usefully branches on: unplugged is not the same as broken.
2 and 4 split what a script could not do. 2 means a flag would have supplied it - an answer (--label, --mount-point...), --passphrase-file, --pin-file for a new PIN, --yes, or dropping --no-wait so housekey polls for a key to be plugged in - and says which. 4 means only a person can: a key's PIN, a mobile's QR code, or the master key on screen (vault masterkey). A biometric token needs no PIN, so a script can open a vault with one; a token with a PIN, or this machine's TPM, needs someone to type it.