luksbox rotate-mvk

Generate a fresh master volume key, re-encrypt the vault.

luksbox rotate-mvk [OPTIONS] <PATH>

The most invasive vault operation. Use after a key compromise to make sure previously-extracted MVKs no longer help an attacker.

rotate-mvk is interactive: it asks for a confirmation and for the credential of every keyslot, so it cannot run unattended.

What it does

1. Unlock the vault with an existing keyslot (recovers current MVK), and check the --anchor if you pass one: a rolled-back vault is refused before anything is re-encrypted.
2. Ask for the credential of every populated keyslot, since each one is rebuilt: the passphrase of each passphrase slot, the PIN and two touches for each FIDO2 slot.
3. Generate a fresh random MVK.
4. Re-encrypt every chunk and the metadata under the new MVK, in a <vault>.rotating copy of the vault.
5. Re-wrap every keyslot under the new MVK with fresh salts. Passphrase slots get the strongest Argon2id cost already used in the vault (0.6.0+; earlier versions used the interactive preset, a silent downgrade for --kdf sensitive vaults).
6. Write the new header (on header format v3, a new header generation) and rewrite the anchor, if given, under the new MVK.
7. Commit by renaming the copy over the original.

With the header inline in the .lbx (the default), the operation is crash-safe: if the power dies before the commit, your vault is still openable with the old MVK and old keyslots. With a detached header (--header) it is not: back up the header file and the vault first.

Which vaults it can rotate

The CLI rotates standard vaults whose keyslots are passphrase or FIDO2 slots. It refuses a vault with a fido2-direct slot (the MVK comes from the authenticator itself), a hybrid post-quantum slot, a TPM slot or a Secure Enclave slot: revoke those first, rotate, then enroll them again. A deniable vault cannot be rotated in this release, from the CLI, the wizard or the GUI: to retire its master key, create a new deniable vault and copy the files into it.

On Windows, rotation failed in 0.6.0-rc.1 with "another process has locked a portion of the file" (os error 33) before changing anything; it works again in 0.6.1.

When to use it

• After revoking a compromised keyslot
• On a calendar (e.g. annual key rotation policy)
• After a major security incident in your org
• Before publishing a vault to long-term cold storage

How long it takes

Proportional to the vault's data size. Each chunk is decrypted under the old MVK and re-encrypted under the new one. Roughly the same throughput as a mount + full read-write pass:

Examples

luksbox rotate-mvk my.lbx
# Unlocks via the default passphrase prompt, asks to confirm, then
# asks for each keyslot's credential; rotates in place.

# With the vault's rollback anchor: checked first, then rewritten
# under the new MVK
luksbox rotate-mvk my.lbx --anchor /media/usb/my.anchor

# After revoking a compromised FIDO2 slot
luksbox revoke my.lbx --slot 1
luksbox rotate-mvk my.lbx

Take a new header-backup afterwards: older header backups no longer open the vault.

Recovery after a failed rotation

If the rotation failed with an error, the temporary copy is removed and the vault is unchanged. If it was interrupted before the commit (crash, power loss), the vault is still in its pre-rotation state, and the <vault>.rotating copy stays next to it. LUKSbox does not delete it on its own, and a new rotation refuses to start while it exists. Check that the vault opens with your usual credentials, then delete the .rotating file. luksbox cleanup-orphans <vault> lists such leftovers but never deletes a .rotating file.