Passphrase keyslots

Argon2id-stretched passphrase, the universal fallback keyslot.

The passphrase keyslot is what every vault has by default. It's universal (works without hardware), recoverable (memorise it, write it down), and the slowest to brute-force (Argon2id is memory-hard).

How it works

1. You type a passphrase at create or unlock time.
2. LUKSbox runs Argon2id with the slot's stored salt + parameters (default: 256 MiB memory, 3 iterations, 4 lanes).
3. The output is the wrap-KEK, a 256-bit key.
4. The wrap-KEK is used with AES-256-GCM-SIV to either:
   • Wrap the random Master Volume Key (MVK) at create time, or
   • Unwrap the stored ciphertext at unlock time.

The passphrase itself is never stored. Only the salt, the AEAD nonce, and the wrapped MVK ciphertext + tag live on disk.

KDF presets

LUKSbox ships three presets controllable via --kdf:

sensitive multiplies the brute-force cost by about 6.7x at the price of a slower interactive unlock. Use it for vaults you want to protect against state-level adversaries who'd burn CPU-weeks on a single target.

luksbox create my-vault.lbx --kdf sensitive

create --kdf-target-time 5s instead calibrates the memory cost so that one unlock takes about that long on this machine.

Argon2id settings below 64 MiB of memory, or below the work of 64 MiB x 3 passes (the RFC 9106 floor), make a stolen vault cheap to brute-force. Since 0.6.0, create --kdf-target-time, deniable-init and an enroll or update that would write such a slot print a warning, and the wizard's custom KDF setting asks you to confirm.

Choosing a passphrase

Headline:

Practical recommendation: use a 6-word passphrase from the EFF long wordlist. 6 words = 78 bits of entropy, comfortably past any feasible attacker horizon.

Adding a passphrase keyslot to an existing vault

luksbox enroll my-vault.lbx --kind passphrase
# Enter the existing passphrase to unlock (add --fido2 to unlock
# with a FIDO2 key instead).
# Enter the NEW passphrase twice to enroll the second slot.

Now the vault has two passphrase slots. Either works; revoking one doesn't affect the other.

To change the passphrase of an existing slot in place, use update:

luksbox update my-vault.lbx --slot 0
# Unlock, then enter the slot's NEW passphrase twice.

KDF strength of new and changed slots

Since 0.6.0:

• update keeps the Argon2id cost the slot already has.
• enroll, the wizard when it adds a slot, and rotate-mvk use the strongest passphrase cost already in the vault. Before 0.6.0 they always used the interactive preset, so a vault created with --kdf sensitive silently gained slots at a quarter of its cost, and an attacker goes for the weakest slot.
• To choose explicitly, pass --kdf to enroll or update, for example luksbox enroll my-vault.lbx --kind passphrase --kdf sensitive. It applies to slot kinds with a passphrase factor (passphrase and the Secure Enclave + passphrase kinds).

Scripting

enroll, update and the other commands that set a new passphrase on an existing vault read it from LUKSBOX_NEW_PASSPHRASE. Since 0.6.0, LUKSBOX_PASSPHRASE is only the unlock secret there: it is no longer reused as the new passphrase, and without LUKSBOX_NEW_PASSPHRASE LUKSbox prints a note and prompts for the new one. (create still takes the new vault's passphrase from LUKSBOX_PASSPHRASE.) Both variables are visible to other processes of the same user, so prefer typing the passphrase when you can.

When you type a new passphrase that is easy to guess, LUKSbox warns and asks "Use this passphrase anyway?". Since 0.6.0 the wizard and deniable-vault creation check it too.

Revoking a passphrase keyslot

luksbox revoke my-vault.lbx --slot 1

The revoked slot is zeroed and can no longer unlock. The MVK is NOT rotated, so previously-extracted plaintext is still readable by whoever has it. For a true "this passphrase no longer reveals anything new" rotation, see luksbox rotate-mvk.