LUKSbox v0.6.1
/ Documentation / Desktop GUI / Unlocking a vault

Unlocking a vault

Passphrase, FIDO2, TPM 2.0, Secure Enclave, hybrid-PQ and deniable unlock from the GUI.

The Unlock view appears when you open an existing vault, click a recent-vault entry, use Type path manually..., or launch luksbox-gui /path/to/my.lbx. It has three parts:

Unlock view: vault path at the top, Unlock button top right, Sidecars and Method sections on the left, and on the right the KEYSLOTS IN THIS VAULT panel listing slot 0: passphrase
The Unlock view for a passphrase-only vault. The keyslot panel on the right is read from the vault header; the method on the left must match one of its slots.

Choosing the unlock method

Whenever the vault path in the form changes (a recent entry, Browse... or a typed path), LUKSbox reads the vault's keyslot table from its unencrypted header and (0.6.0+):

Method Opens these slots
Passphrase passphrase
FIDO2 security key FIDO2 (wrap), FIDO2-direct
Hybrid passphrase + ML-KEM (post-quantum) passphrase + ML-KEM-768 / ML-KEM-1024
Hybrid FIDO2 + ML-KEM (post-quantum, authenticator + .kyber) FIDO2 + ML-KEM-768 / ML-KEM-1024
TPM 2.0 (this machine) TPM 2.0
TPM 2.0 + PIN (this machine + memorised PIN) TPM 2.0 + PIN
TPM 2.0 + FIDO2 (this machine AND this authenticator) TPM 2.0 + FIDO2
Hybrid TPM 2.0 + ML-KEM (PQ + machine-bound) TPM 2.0 + ML-KEM-768 / ML-KEM-1024
Hybrid TPM 2.0 + FIDO2 + ML-KEM (3 factors) TPM 2.0 + FIDO2 + ML-KEM-768 / ML-KEM-1024
Secure Enclave (this Mac; also its Touch ID, + FIDO2 and + passphrase slots) Secure Enclave, Secure Enclave + biometry, and the Secure Enclave + FIDO2 / + passphrase slots
Hybrid Secure Enclave + ML-KEM (also its + FIDO2 and + passphrase slots) the same slots with ML-KEM-768 / ML-KEM-1024

Methods this build cannot use are not listed: the TPM 2.0 methods need a Linux or Windows build with the TPM backend, the Secure Enclave methods a macOS build with it, the FIDO2 methods a build with FIDO2 support. The ML-KEM parameter set (768 or 1024) is read from the .hybrid sidecar; you never choose it.

Passphrase unlock

  1. Check the vault path at the top.
  2. Type your passphrase in the Passphrase field.
  3. Click Unlock, or press Enter in the field. Argon2id runs (0.5 to 4 seconds depending on the vault's KDF preset) while a "Working..." overlay is shown.
  4. On success, you land in the Browser view.

A wrong passphrase gives "no keyslot accepted the provided unlock material". The GUI deliberately doesn't say which slot failed, matching the crypto layer, which tries every keyslot the same way.

FIDO2 unlock

For FIDO2 (wrap) and FIDO2-direct slots: method FIDO2 security key.

Unlock view for a FIDO2 vault: the keyslot panel lists slot 0: FIDO2 (wrap) and the FIDO2 method is selected
FIDO2 unlock. The authenticator used is the one selected in the sidebar's FIDO2 AUTHENTICATOR picker.
  1. Check the authenticator selected in the sidebar's FIDO2 AUTHENTICATOR picker. Click (refresh) Re-detect if you plugged a key in after starting LUKSbox.
  2. Type the FIDO2 PIN. On Windows there is no PIN field (0.6.1+): the view shows FIDO2 PIN: Windows asks for it in its own security-key prompt., and you type the PIN there. (Older versions showed a PIN field whose value Windows ignored, so you were asked twice.)
  3. Click Unlock, then touch the authenticator when asked. Every FIDO2 slot's credential goes into one request, so one touch (on Windows, one prompt) covers whichever enrolled key you present.
  4. On success, you land in the Browser.

LUKSbox never guesses which authenticator to talk to: the PIN goes only to the one selected in the sidebar (0.6.0+). With more than one plugged in, the picker preselects the first one detected, so check that it is the key you mean before typing the PIN. With none selected the unlock is refused ("... FIDO2 authenticators are present; select one explicitly ..."), and a key unplugged since you picked it gives "selected FIDO2 device (...) is no longer plugged in; re-detect or pick another".

A wrong PIN stops the unlock at once (0.6.0+) instead of moving on to the next FIDO2 slot, which would spend another of the authenticator's 8 PIN retries.

If the vault also has a passphrase keyslot (a backup), pick Passphrase in the method list to use it instead, for example when you lost the key.

Hybrid-PQ unlock

For slots that add an ML-KEM .kyber seed file to a passphrase, a FIDO2 key, a TPM or a Secure Enclave. Every hybrid method asks for Path to the .kyber seed file (with Browse...); the classical factor and the seed file are both required, either alone won't unlock.

Unlock view with the Hybrid FIDO2 + ML-KEM method selected: FIDO2 PIN, Seed-file passphrase and Path to the .kyber seed file fields
Hybrid FIDO2 + ML-KEM: the FIDO2 PIN, the seed-file passphrase and the .kyber path.

Click Unlock; ML-KEM decapsulation, Argon2id and the AEAD unwrap run in sequence.

TPM 2.0 and Secure Enclave unlock

When a TPM or Secure Enclave unseal fails, the error ends with the reason in parentheses (0.6.0+), for example that the TPM is in dictionary-attack lockout, that the TPM's storage root key does not match the one a pinned slot was sealed under, that Touch ID was cancelled, or that the TPM PIN was wrong.

Deniable open

If the vault was created with deniable mode, tick This vault uses a deniable header (advanced) in the Sidecars section. A deniable vault has no readable header, so the GUI cannot detect it; you tick the box yourself. The form then asks for the Cipher suite (must match create time) and the Argon2id strength (must match create time): in deniable mode these values are part of the secret. The detached-header option is hidden (deniable vaults do not support one); the anchor option stays.

Every method then asks for the envelope passphrase (the Envelope passphrase (deniable - required) field, or the Passphrase field of the Passphrase method). The FIDO2 credential, the hmac salt and the TPM sealed blob are stored inside the slot envelope, so there is nothing else to paste in; you only bring the device (FIDO2 key, TPM, Secure Enclave) the credential uses. Two extra methods, Secure Enclave + FIDO2 (deniable) and Hybrid Secure Enclave + FIDO2 + ML-KEM (deniable), appear only in deniable mode.

Which method? Identify keyslot

The keyslot panel explains that the slot table of a deniable vault is encrypted, so nothing about it can be read without the envelope passphrase (0.6.0+). Type the envelope passphrase and choose the cipher and Argon2id strength, then click Identify keyslot: LUKSbox derives the envelope key (a few seconds), lists the envelopes that passphrase opens with their credential type (for example slot 1: passphrase + FIDO2) and the method to use, and switches to it. With several envelopes, Use this one picks another. For a TPM envelope it adds (or TPM 2.0 + PIN if a PIN was set at creation). Nothing is unlocked or written.

If nothing opens: no envelope opens with this passphrase, cipher and KDF strength (or the file is not a deniable vault).

Errors on the deniable path

For hybrid-PQ deniable variants the seed-file passphrase field defaults to blank, meaning "reuse the envelope passphrase". Leave it blank if you took the default at create time; fill it if you set a distinct seed-file passphrase for defence in depth.

Recovery mode (read-only, skips broken files)

If a vault that used to open suddenly refuses with metadata blob deserialization failed or per-inode AEAD errors (the v0.2.1 durability bug fixed in v0.2.2), tick the "Recovery mode (read-only, skips broken files)" checkbox on the Open form before clicking Unlock.

The toleration flag installs broken inodes as 0-byte placeholders during open instead of refusing the whole vault. On success a modal lists every broken file's path + original size + AEAD- failure reason so you know what to re-source. The mount is read-only; the GUI refuses every flush while the recovery report is active, so the broken inodes are never persisted back to disk over the original on-disk metadata. Future brute-force recovery against the original chunks_external pointers stays possible.

Treat recovery mode as a one-shot escape hatch: open, copy out everything that reads, close, run the broken-vault forensics workflow on the original .lbx (see the recovery operations page for the full flow). The CLI equivalent is LUKSBOX_TOLERATE_BAD_CHUNK_LISTS=1 luksbox mount ...; the wizard prompts "Try opening in recovery mode?" on the same failure.

Errors you might see

Error Meaning
"no keyslot accepted the provided unlock material" Wrong passphrase, PIN or key, or a method that matches none of the slots
"... (TPM in lockout ...)" and other reasons in parentheses A TPM or Secure Enclave unseal failed; the reason says why (see above)
"unlock failed" Deniable path: wrong passphrase, cipher, Argon2id strength or file
"hybrid mode requires the .kyber seed file path" A hybrid method with an empty seed-file path
"selected FIDO2 device (...) is no longer plugged in" The authenticator picked in the sidebar was unplugged; re-detect or pick another
"Rollback detected: anchor at gen ... > vault at gen ..." With an anchor: the vault file is an older copy than the one the anchor last saw
"header rollback detected: ..." With an anchor and header format v3: the keyslot table was replaced by an older copy (for example a header backup taken before a revoke)
"vault locked by another process" Another luksbox (CLI or GUI) instance has the vault open and holds its lock

Performance notes

Unlock time is dominated by Argon2id (the KDF). Typical figures:

FIDO2 touch + assert adds 200 ms on top of the KDF. Hybrid-PQ adds another 100 ms for the ML-KEM decapsulation.

If unlock takes much longer than expected (e.g. 10+ seconds for an interactive preset), suspect either disk I/O contention or that the vault was created with a custom high-m_cost target on a faster machine than the one you're unlocking from.

Next

<- PreviousBrowsing files