Create a Passphrase-Protected Vault Key with vault genkey

vault genkey writes the key file that everything else depends on, with an optional decoy passphrase alongside. This guide creates one, explains the decoy slot and shows how to do it without prompts.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Pick where the key lives
2. Run genkey and answer the prompts
3. Know what it refuses to do
4. Script it without prompts
5. Back it up and move on

Allow about five minutes. You need a terminal and somewhere private for the key file. No elevated privileges are required. The key file is the one artefact you must back up, since without it and its passphrase the vault is unreadable for good.

1. Pick where the key lives

The key goes to ~/.vault/key unless you say otherwise with --key PATH or VAULT_KEY. Make sure the parent directory exists and is yours alone:

$ mkdir -p ~/.vault
$ chmod 700 ~/.vault

2. Run genkey and answer the prompts

It prompts twice for the passphrase, then for an optional decoy passphrase. Leave the decoy empty if you do not want one:

$ vault genkey
$ vault genkey --key /mnt/usb/vault.key

Both passphrase slots are sealed with Argon2id and XChaCha20-Poly1305. They are the same size and stored in random order. The second slot holds either a decoy identity or random bytes, so nobody can tell from the file which you chose. No seed or private key is ever written unencrypted.

3. Know what it refuses to do

Warning

genkey refuses to overwrite an existing file. That is deliberate. Overwriting a key you still need makes every file encrypted under it permanently unreadable.

If you really do want a fresh key, give it a new path with --key and delete the old one only after you have confirmed nothing depends on it.

4. Script it without prompts

With VAULT_PASSPHRASE set, no prompts appear. The decoy then comes from VAULT_DECOY_PASSPHRASE, or is left out if that is unset. The decoy must differ from the main passphrase:

$ VAULT_PASSPHRASE='real one' VAULT_DECOY_PASSPHRASE='other one' vault genkey

Keep these variables out of shell history and shared profiles. Prefix them to one command as above, or read them from a file you control.

5. Back it up and move on

Copy the key file to a second location, such as an encrypted USB stick. The passphrase protects it, but a lost key file is as bad as a lost passphrase. Then create the store with vault-init(1). The wider picture is in vault(1).

Checkpoint

Check that the file exists with ls -l ~/.vault/key. A working key is proved later, when vault list accepts your passphrase.

Done means

A key file exists at a path you chose on purpose.
The passphrase is remembered or stored safely, since it cannot be reset.
A decoy passphrase was set only if you wanted one, and it differs from the main one.
genkey was not used to replace a key that is still in use.
A backup copy of the key file lives somewhere else.