Managing keyslots

Add, revoke and rotate keyslots, upgrade the header format, deniable keyslots, TPM storage root key pinning.

The Keyslots view is where you add backup keys, revoke compromised ones, rotate the master volume key and upgrade the header format. Reach it with the Keyslots button in the Browser view; < Back returns to the Browser.

The slot list

A LUKSbox vault holds up to 8 keyslots. Each slot is independent: any active slot can unlock the vault, revoking one doesn't affect the others.

At the top, the view shows the vault cipher (set at create time, the same for every slot) and the header format. Then each slot has a card:

Slot N and a tag with its kind: passphrase, fido2 (wrap), fido2-direct, hybrid-pq (768), tpm2 + PIN, secure enclave + FIDO2, ... or empty;
a Revoke button for every slot in use;
for passphrase slots, the Argon2id parameters (Argon2id m=262144 KiB t=3 p=4);
for FIDO2 slots, the start of the credential id and its length;
for every slot that uses FIDO2, whether it opens everywhere (V4: cross-platform (Linux/macOS/Windows)) or only on Linux and macOS, with the luksbox migrate-fido2-slot command to fix it when there is one.

Keyslots view: Slot 0 tagged hybrid-pq-fido2 (768), Slot 1 passphrase with its Argon2id parameters, Slot 2 fido2 (wrap) with its credential id, each with a Revoke button, and empty slots 3 to 7 — The Keyslots view of a vault with three slots in use.

Header format v3

Under the cipher line, the view shows the vault's header format (0.6.0+):

Header format v3 (header generation N): with an anchor, a restored older keyslot table is detected at open.
Header format v2: restoring an older copy of the keyslot table (e.g. from before a revoke) is not detectable., followed by an Upgrade header to v3 button.

With header format v3, every keyslot change (add, revoke, update, rotate) bumps a header generation that the rollback-detection anchor records. Opening the vault with its anchor then refuses an older header, for example a backup taken before a revoke, which would otherwise bring the revoked credential back. Keep the anchor on separate trusted storage.

Upgrade header to v3 is one-way: LUKSbox versions before 0.6.0 can no longer open the vault afterwards. New vaults get header format v3 by default (see Creating a vault). The CLI equivalents are luksbox upgrade-header and luksbox deniable-upgrade-header.

Add a keyslot

Under ADD KEYSLOT there is one button per kind:

+ Add passphrase keyslot and + Add FIDO2 keyslot (wrap mode)
+ Add passphrase + ML-KEM-768 keyslot / -1024, and + Add FIDO2 + ML-KEM-768 keyslot / -1024
Linux and Windows: + Add TPM 2.0 keyslot (this machine), + Add TPM 2.0 + PIN keyslot, + Add fused TPM 2.0 + FIDO2 keyslot (both required), the hybrid TPM 2.0 + ML-KEM-768 / -1024 buttons and the 3-factor TPM 2.0 + FIDO2 + ML-KEM-768 / -1024 buttons
macOS: + Add Secure Enclave keyslot (this Mac), + Add Secure Enclave + Touch ID keyslot, the hybrid Secure Enclave + ML-KEM-768 / -1024 buttons and + Add fused Secure Enclave keyslot (+ FIDO2 / passphrase)...

Each button opens a dialog for what that kind needs: the new passphrase and its Argon2id strength, the FIDO2 PIN and touches, the .kyber seed file path and its passphrase, the TPM PIN. The vault is already unlocked, so no existing credential is asked again. Buttons that need hardware check it first (FIDO2 key plugged in, TPM reachable) so you get the error before typing anything. FIDO2-direct slots can only be made when the vault is created.

This is the standard way to add a backup. Best practice for high-value vaults:

Slot 0: Passphrase (paper-backed)
Slot 1: FIDO2 daily-use device (your YubiKey 5)
Slot 2: FIDO2 backup device (kept in a safe deposit box)
Slot 3: Optional emergency passphrase

TPM storage root key pinning

On Linux and Windows, above the TPM buttons (and in the Create form when a TPM kind is selected), the checkbox Pin the TPM storage root key in new TPM keyslots (0.6.0+, off by default) makes every new TPM keyslot record the TPM's storage root key (SRK). Unlock then refuses to run if the TPM reports a different key, which defeats an active TPM-bus interposer substituting the key to read the unsealed secret.

The choice is remembered and applies to every TPM keyslot you create afterwards, until you untick it. Existing keyslots are not changed.
Pinned keyslots need LUKSbox 0.6.0+ to unlock.
If the TPM is cleared or replaced, a pinned slot can no longer be unsealed ("the TPM's storage root key does not match the one this keyslot was sealed under"), as with any TPM slot. Keep a backup slot.

The CLI equivalent is the global --tpm-pin-srk flag (or LUKSBOX_TPM_PIN_SRK=1); the wizard asks before the first new TPM keyslot of a session.

Revoke a keyslot

Click Revoke on the slot. The dialog Revoke keyslot #N? explains what happens; Revoke this keyslot confirms:

The slot's wrapped master key is overwritten and cannot be recovered, so the passphrase or authenticator that used it no longer opens the vault
The slot becomes empty
The remaining slots are untouched
The MVK is NOT rotated - if an attacker has previously extracted the MVK from this vault, they still have it after revocation

If you suspect a keyslot was actively compromised (someone copied your .lbx AND has your YubiKey AND your PIN, say), follow the revoke with Rotate master key below. That generates a fresh MVK and re-encrypts every chunk under it. With header format v3 and an anchor, a copy of the header taken before the revoke can no longer bring the slot back.

Revoking the last active keyslot locks you out for good. The GUI lets you do it, but the dialog warns in red and its button reads Yes, lock me out permanently. Enroll the new credential first, then revoke the old one.

Rotate the master key

Rotate master key..., under ROTATE, is available when every slot in use is a passphrase slot. The dialog asks for the passphrase of each passphrase slot and the Argon2id strength for the new wraps, then:

Generates a fresh random MVK
Re-encrypts EVERY file chunk under keys derived from the new MVK
Re-wraps every keyslot under the new MVK, with fresh salts
Commits atomically: with an inline header the work goes to a <vault>.rotating temp file that is renamed over the original at the end, so a crash before that leaves the original intact

After rotation, any previously-extracted MVK is useless against the vault. Use this:

After revoking a compromised slot
On a calendar (annual rotation policy)
After a security incident in your org
Before publishing a vault to long-term cold storage

For other vaults the button shows Rotate master key (use CLI), disabled, with the reason: FIDO2 (wrap) slots need luksbox rotate-mvk or the wizard; TPM and Secure Enclave slots must be revoked, the key rotated with luksbox rotate-mvk, then re-enrolled; hybrid-PQ vaults cannot be rotated yet, and FIDO2-direct vaults not at all (their master key comes from the authenticator: recreate the vault).

Deniable vaults

A deniable vault has no slot list: an unused slot is random bytes and each used one is sealed under its own passphrase, which is the point of a deniable vault. The view shows a Deniable keyslots section instead (0.6.0+):

It says which slot this session was unlocked with ("This session was unlocked with slot N").
Find slot: type a credential's envelope passphrase and choose the Argon2id strength it was created with. LUKSbox lists the slot(s) it opens and their credential type, marking yours with (this session). The credential's FIDO2 key, TPM or Secure Enclave is not needed for this. Each slot found, other than your own, has a Revoke... button.
Revoke a slot by number (the one picked when it was added): choose it and click Revoke.... The confirmation explains that the slot is overwritten with random bytes, so the credential stored there, if any, stops opening the vault, and that this cannot be undone; Revoke slot N confirms. The slot this session was unlocked with is not offered: revoking it would lock you out, so unlock with another credential first.
A credential whose slot you do not know cannot be shut out in place: no LUKSbox front end rotates a deniable vault's master key yet. Create a new deniable vault and copy the files into it.

Adding a keyslot to a deniable vault works with the same buttons; the dialog also asks for the new credential's envelope passphrase, its Argon2id strength and a target slot number. Write the number down: you need it to revoke that credential later. Secure Enclave keyslots cannot be added to a deniable vault.

Tips

Always have at least 2 keyslots for any vault you care about. Single-slot vaults are one device-loss away from unrecoverable.
Revoke + rotate after device loss, not just one or the other.
The slot index isn't a security property - slot 5 is no more or less secure than slot 0. Indexes are just labels.
You can mix kinds freely - passphrase + FIDO2 + hybrid-PQ all in the same vault, in any combination.