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.

What it does

1. Unlock the vault with an existing keyslot (recovers current MVK).
2. Generate a fresh random MVK.
3. Re-wrap every active keyslot under the new MVK.
4. Re-encrypt every file chunk in the vault under keys derived from the new MVK.
5. Update the header HMAC and write a new generation counter to the anchor sidecar.
6. Commit atomically; on crash mid-rotation, the old vault stays intact and unmodified.

The operation is crash-safe: if the power dies halfway through, your vault is still openable with the old MVK and old keyslots. No half-rotated state is possible.

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
# Authenticates via the default unlock prompt; rotates in place.

# With explicit unlock material
LUKSBOX_PASSPHRASE="$pp" luksbox rotate-mvk my.lbx

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

Recovery after a failed rotation

If the rotation crashed before commit, the vault is still in its pre-rotation state. The temporary work files (.lbx.rotate-tmp) are cleaned up automatically on the next vault open; you can also delete them manually if needed.