Wizard walkthrough

Screen-by-screen walkthrough of luksbox wizard - menus, prompts, confirmation dialogs.

This page walks the wizard end-to-end. Each section corresponds to one wizard screen. The top-level menu screenshot below shows the overall shape; the rest is captured in prose because the wizard's text UI is faithful enough on its own that pixel-by-pixel screenshots add little beyond what the descriptions already convey.

1. Top-level menu

Run luksbox wizard (no args). The first screen, What would you like to do?, lists nine actions; arrow keys to navigate, Enter to select:

1. Create a new vault
2. Open an existing vault
3. Show info about a vault (no unlock)
4. Generate a strong random passphrase
5. Create a deniable vault (advanced)
6. Mount a deniable vault (advanced)
7. Verify a deniable header (advanced)
8. PANIC: irreversibly destroy a vault by header path
9. Quit

2. Startup notes

Before the menu, the wizard prints what it found:

• With more than one FIDO2 authenticator plugged in, it asks Multiple FIDO2 authenticators detected, pick one for this session; every FIDO2 operation of the session then uses that key (unless --fido2-device already named one). With one, it is selected silently.
• A build without FIDO2, TPM 2.0 and Secure Enclave support (the passphrase-only static Linux CLI) says This build has no FIDO2, TPM 2.0 or Secure Enclave support (e.g. the passphrase-only static Linux build), so only passphrase and passphrase + ML-KEM keyslots are offered. (0.6.1+). Every menu then hides the keyslot kinds the build cannot use, instead of failing after the prompts.
• A Linux build with TPM support on a machine without a TPM device says No TPM 2.0 device found (/dev/tpmrm0): TPM keyslots will not work on this machine. (0.6.1+).

3. Create a new vault

The Create flow asks, in order:

1. Path for the new vault (default vault.lbx; an existing file is refused).
2. Whether to use a detached-header sidecar.
3. Cipher suite (default: AES-256-GCM-SIV).
4. On-disk metadata format: v3 (default) or v2 (compat, for LUKSbox before v0.2.0).
5. Initial keyslot kind: passphrase, FIDO2 wrap-style, FIDO2-direct and the four hybrid ML-KEM kinds, then the TPM 2.0 kinds on Linux and Windows or the Secure Enclave kinds on macOS. Each entry has a one-line explanation. Kinds the build cannot use are not listed.
6. For passphrase and FIDO2 wrap-style vaults: whether to pad files to power-of-2 chunks and whether to hide exact file sizes.
7. Use header format v3? (default yes, 0.6.0+): every keyslot change bumps a header generation that the anchor records, so restoring an older header (for example one from before a revoke) is detected. A v3 vault needs LUKSbox 0.6.0+ to open; answer no only if LUKSbox 0.2.1-0.5.x must still open it. Not asked when you picked the v2 metadata format, which keeps the v2 header.
8. Whether to initialize a rollback-detection anchor, and where.
9. The maximum vault size (see Vault size; not asked with the v2 metadata format).

Then come the prompts of the chosen kind (passphrase, FIDO2 touches, .kyber seed path, TPM PIN). A new standard vault's passphrase slots use the Interactive Argon2id preset.

4. New passphrases

Every time the wizard needs a new passphrase it first asks Generate a strong random passphrase instead of typing one? (default no). A generated passphrase is 20 random characters (about 99 bits of OsRng entropy), shown once with WRITE THIS DOWN, it is shown only once.; the wizard goes on only after you confirm I have stored the passphrase safely. Continue?.

A typed passphrase is asked twice. An empty one needs a confirmation. A weak one (zxcvbn score below 3 of 4) prints a warning with hints and asks Use this passphrase anyway? (default no, which asks for another one); this check covers deniable vaults too (0.6.0+). LUKSBOX_ACCEPT_WEAK=1 skips the question.

5. Argon2id strength

When you add a passphrase or FIDO2 keyslot from Manage keyslots, and for every deniable envelope you create, the wizard asks for the Argon2id strength:

• Interactive (256 MiB, t=3, p=4) ~500 ms per attempt
• Moderate (512 MiB, t=4, p=4) ~1.5 s per attempt
• Sensitive (1 GiB, t=5, p=4) ~3-4 s per attempt
• Custom (advanced - lower memory for constrained VMs / AppVMs)

Custom asks for the memory cost (KiB), iterations and parallelism. Below 64 MiB, or below 64 MiB x 3 passes (the RFC 9106 floor), the wizard warns and asks Use these Argon2id parameters anyway? (a stolen vault is then cheap to brute-force; only do this on a host that cannot allocate more) (default no, which asks again) (0.6.0+). Every preset passes the floor.

6. FIDO2 enrollment, touch prompt

If you chose a FIDO2 or hybrid-FIDO2 slot, the wizard asks for the FIDO2 PIN, then for two touches: one to register a new credential, one to derive the keyslot secret. The CLI underneath uses libfido2 on Linux/macOS or webauthn.dll on Windows. On Windows the wizard does not ask for the PIN (0.6.1+): Windows asks for it in its own security-key prompt.

7. TPM enrollment

For any TPM kind, the wizard warns that TPM-bound keyslots only open on the chip that sealed them and asks Continue with TPM-backed creation?. Then:

• TPM 2.0 and TPM 2.0 + PIN: Skip bootstrap passphrase? (default no). By default the vault also gets a backup passphrase keyslot, the recovery when the chip dies; skipping it leaves a single TPM slot.
• The fused and hybrid TPM kinds: Add a recovery passphrase? (default no), since a passphrase slot next to them is a way in without any of the hardware factors.

Before the first new TPM keyslot of the session, the wizard asks (0.6.0+): Pin the TPM's storage root key into the new TPM keyslot? (unlock then refuses a substituted key, defeating an active TPM-bus interposer; the slot needs LUKSbox 0.6.0+ to unlock) (default no). The answer applies to every TPM keyslot sealed in that session. The question is skipped when --tpm-pin-srk (or LUKSBOX_TPM_PIN_SRK=1) already turned pinning on.

8. After create

The wizard prints OK created <path> (with the header format, anchor and maximum size it set) and asks Open and mount this vault now?. More keyslots (a backup passphrase, a second key) are added later through Open an existing vault > Manage keyslots.

9. Open an existing vault

Open asks for Path to vault, whether it uses a detached header, and whether to verify it against a rollback-detection anchor (and the anchor's path). It then reads the header and asks How would you like to unlock?, listing only the methods for the keyslot kinds in this vault that this build can use (no question when only one applies). With an authenticator plugged in, a FIDO2 method is preselected when the vault has one. A vault whose keyslots all need hardware support the build lacks gets an explicit error (this build cannot open any of this vault's keyslots ...) rather than "vault has no usable keyslots" (0.6.1+).

When a TPM or Secure Enclave unseal fails, the error ends with the reason in parentheses (TPM lockout, storage root key mismatch, cancelled Touch ID, wrong TPM PIN, PIN slot skipped) (0.6.0+).

With an anchor, the wizard prints OK anchor matches vault (generation N), or refuses with ROLLBACK DETECTED when the vault is older than the anchor. If the metadata cannot be read, it offers Try opening in recovery mode? (read-only, skips broken files). FIDO2 keyslots from before v0.3.0, which open only on Linux and macOS, get a notice with the luksbox migrate-fido2-slot command.

10. Vault menu

Once unlocked, Vault action offers:

1. List a directory
2. Cat a file (print to stdout)
3. Copy a local file in
4. Copy a file out to disk
5. Make a directory
6. Remove a file
7. Remove a directory
8. Rename a file or directory (same parent dir)
9. Manage keyslots
10. Rotate master volume key
11. Upgrade header to format v3 (rollback-detectable keyslot table)
12. Vault size (usage, maximum size, give back free space)
13. Mount as a filesystem
14. PANIC: irreversibly destroy this vault
15. Close vault

Rotate master volume key first offers to verify an anchor, then explains the cost (every chunk is re-encrypted) and asks Proceed with MVK rotation? before collecting each keyslot's credential.

11. Manage keyslots

Keyslot action prints the current slot table, then offers:

• Add a passphrase keyslot
• Add a FIDO2 keyslot (wrap-style)
• Add a passphrase + ML-KEM-768 / ML-KEM-1024 keyslot
• Add a FIDO2 + ML-KEM-768 / ML-KEM-1024 keyslot
• Linux and Windows: Add a TPM 2.0 keyslot (this machine, no PIN), a TPM 2.0 + PIN keyslot, a fused TPM 2.0 + FIDO2 keyslot (both required), a hybrid TPM 2.0 + ML-KEM-768 / -1024 keyslot, a 3-factor TPM 2.0 + FIDO2 + ML-KEM-768 / -1024 keyslot
• macOS: Add a Secure Enclave keyslot (this Mac), a Secure Enclave + Touch ID keyslot, the hybrid Secure Enclave + ML-KEM keyslots, a fused Secure Enclave + FIDO2 or + passphrase keyslot and their ML-KEM hybrids
• Update an existing keyslot's secret in place
• Revoke a keyslot (pick the slot, then confirm Revoke slot N? If this is your last keyslot you will be locked out.)
• Back to vault menu

Entries for kinds the build cannot use are hidden (0.6.1+).

12. Upgrade the header to format v3

Upgrade header to format v3 (0.6.0+) explains that every keyslot change then bumps a header generation that the anchor records, and that the upgrade is one-way: LUKSbox versions before 0.6.0 can no longer open the vault. Without an anchor attached to the session it adds that the counter only protects you once an anchor records it. Upgrade the header now? (default no) applies it and prints the header generation. A vault already on v3 just says so.

13. Vault size

Creating a vault asks for a maximum size, showing the free space on the disk (0.6.1+):

Maximum vault size (e.g. 6G, 500M; 0 = unlimited; 412.3 GB free on this disk) [0]:

Enter keeps it unlimited. A value it cannot use (6X, or one smaller than the vault itself) is explained and asked again, and a valid one is echoed back (-> 6.0 GB (6,442,450,944 bytes)).

Once a vault is open, Vault size (usage, maximum size, give back free space) shows the same report as luksbox size, and offers Change the maximum size and, when the end of the vault file is unused, Give back ... at the end of the vault. Close vault asks 1.8 GB at the end of the vault is unused. Give it back to the disk? (default yes) when at least 1 MB can be freed, the same threshold as the GUI's Ask setting. Mounts started from the wizard never ask. Deniable vaults and vaults opened in recovery mode are never offered a give-back.

14. Mount flow, eager-flush prompt

Both the open-and-mount path and the post-create mount path ask for the mountpoint and, except on Windows, Mount in background (recommended)?. Then one durability question comes right before mounting:

Eager flush? (every metadata op crash-durable on return; SLOW on
vaults with thousands of files -- default is no) [y/N]

• No (default, Enter): mounted with deferred flush. Tree mutations return as soon as the in-memory state is updated; a background timer persists changes every 30 seconds. Fast on large vaults.
• Yes: mounted with --sync. Every metadata mutation is flushed to disk before the syscall returns, restoring pre-v0.2.2 per-op durability. Cost scales with total file count; expect basic operations (rm, cp -r) to slow down dramatically on vaults with thousands of files.

The CLI equivalent is luksbox mount --sync (see the mount page for the full trade-off). The GUI equivalent is the Eager flush (--sync) checkbox in the Browser view. Default is "no" in all three surfaces; the prompt does not persist (you'll be asked again on the next mount).

A host crash without explicit fsync can lose up to 30 seconds of metadata changes in the default deferred mode. The on-disk encrypted bytes that ARE flushed remain crash-consistent thanks to the v0.2.2 durability fence, so partial-crash damage is bounded to "the last batch of unfinished mutations" rather than "a vault that no longer opens".

15. Deniable vaults

Create a deniable vault (advanced) warns that you must remember the cipher, the Argon2id parameters and the credential type, and asks Continue with deniable vault creation?. It then asks for the path, the cipher, the Argon2id strength (with the check of section 5), the Credential type for the initial slot (only the types the build supports), the metadata format, Use header format v3? (0.6.0+), and an optional anchor, followed by the passphrase (with the checks of section 4) and the device steps. At the end it prints the parameters to save.

Mount a deniable vault (advanced) and Verify a deniable header (advanced) ask for the path (and the mountpoint), then the cipher, Argon2id strength and credential type used at create time, then (for Mount) whether to verify an anchor, then the passphrase. When the passphrase opens an envelope of another credential type than the one you picked, the error names it (0.6.0+), for example this passphrase opens the envelope in slot 1, whose credential type is "FIDO2 authenticator only": pick that type. Deniable TPM vaults created with the optional TPM PIN ask for it (0.6.0+).

16. TPM permission diagnostic (Linux)

When a TPM operation cannot open the TPM, the error explains what to do: a missing /dev/tpmrm0 (driver not loaded, or TPM disabled in the firmware), a permission problem (add yourself to the tss group, with the exact commands), or a TPM that refuses the operation (for example dictionary-attack lockout). See the TPM 2.0 keyslot page for the Linux permission setup.