Creating a vault
The Create form: vault file, keyslot factor and variant, cipher, KDF, vault size, hardening and header format, deniable mode.
The Create view collects everything needed to build a fresh vault in one form. The defaults match what most users want (passphrase keyslot, AES-256-GCM-SIV, interactive KDF, header format v3), so for a basic vault you only need to fill in the path + a passphrase.
The form
Vault file
Type the path of the new vault, or click Browse. The GUI refuses
to create the vault if the vault file, its detached header, its anchor
or its .kyber seed file already exists (a red error names the file).
Since 0.6.0 this is checked before anything is written, so a failed
create never touches another vault's files.
Tick Use a detached header sidecar to write the header to a
separate .hdr file (the .lbx alone then looks like random data);
a second path field appears for it.
Tick Use a deniable header for a deniable vault (see Deniable mode below).
Keyslot factor and variant
Pick the factor under Keyslot factor, then the exact kind under Keyslot variant:
| Factor | Variants |
|---|---|
| Passphrase only | Plain passphrase; hybrid passphrase + ML-KEM-768 or ML-KEM-1024 (post-quantum) |
| FIDO2 authenticator | FIDO2 (wrap); FIDO2-direct; hybrid FIDO2 + ML-KEM-768 or ML-KEM-1024 |
| TPM 2.0 (this machine) (Linux, Windows) | TPM 2.0; TPM 2.0 + PIN; fused TPM 2.0 + FIDO2; hybrid TPM 2.0 + ML-KEM-768 or -1024; 3-factor TPM 2.0 + FIDO2 + ML-KEM-768 or -1024 |
| Secure Enclave (this Mac) (macOS) | Secure Enclave; Secure Enclave + Touch ID; hybrid Secure Enclave + ML-KEM-768 or -1024; fused Secure Enclave + FIDO2 or + passphrase, also as ML-KEM hybrids |
Each variant has a one-line explanation in the form. When to pick what:
| Kind | When to pick |
|---|---|
| Passphrase | Default; most users |
| FIDO2 (wrap) | Hardware-key users; add a passphrase or second key as backup afterwards in Keyslots |
| FIDO2-direct | High-paranoia: the key is the only way in unless you tick Enable backup passphrase |
| Hybrid + ML-KEM-768 | Long-term confidentiality (post-quantum); needs a .kyber seed file |
| Hybrid + ML-KEM-1024 | Same, NIST category 5 (~AES-256 post-quantum strength) |
| TPM 2.0 / Secure Enclave | Vault bound to this machine. A bootstrap passphrase slot is kept as recovery (plain TPM 2.0 and Secure Enclave kinds can skip it); the fused and hybrid TPM kinds get one only if you tick the recovery-passphrase option |
Picking a hybrid kind reveals a .kyber seed file path (where to save the seed: keep it on separate trusted storage) and its passphrase.
FIDO2 kinds use the authenticator selected in the sidebar's FIDO2 AUTHENTICATOR picker (pick one explicitly when several are plugged in) and ask for its FIDO2 PIN. On Windows there is no PIN field (0.6.1+): Windows asks for the PIN in its own security-key prompt.
For TPM kinds on Linux and Windows the form also shows Pin the TPM storage root key in new TPM keyslots (0.6.0+, off by default); see TPM storage root key pinning.
Cipher suite
Three options, AES-256-GCM-SIV is the default:
| Cipher | When to pick |
|---|---|
| AES-256-GCM-SIV (default) | Default; nonce-misuse-resistant; AES-NI on most CPUs |
| AES-256-GCM | Legacy compat with vaults created before SIV was the default |
| ChaCha20-Poly1305 | If your CPU has no AES-NI; constant-time on every platform |
Most users keep the default.
KDF strength (Argon2id)
Three options for Argon2id strength:
| Preset | Memory | Time / unlock | Brute-force resistance |
|---|---|---|---|
| Interactive (default) | 256 MiB | 500 ms | Strong; daily-use vaults |
| Moderate | 512 MiB | 1.5 sec | Annual-archive vaults |
| Sensitive | 1 GiB | 3-4 sec | Long-term cold storage |
The times are typical; luksbox kdf-bench on the command line measures
them on your own CPU.
Passphrase
The passphrase field has:
- A live strength meter (powered by
zxcvbn): very weak / weak / okay / strong / very strong, with the length - A Generate strong passphrase... button that opens a passphrase-generator dialog (length, character sets, preview; the result goes back into the field)
For FIDO2-direct, tick Enable backup passphrase to add a passphrase keyslot wrapping the same master key, so losing the YubiKey doesn't mean losing the vault. FIDO2 (wrap) vaults are created with the FIDO2 slot only: add the backup afterwards in Keyslots.
Vault size
The maximum size of the vault file: Unlimited by default (the vault
grows as you add files). Drag the slider, or type an exact value in the
field next to it (6G, 500M, 1.5G); the line under it shows what
the value was understood as, and warns when it is more than the free
space on the disk. Writes that would grow the vault past the limit
fail as on a full disk. You can change it any time from
Vault size once the vault is open. Needs
the v0.2.1 on-disk format (the default). New in 0.6.1: a vault with a
maximum size needs LUKSbox 0.6.1 or later to open.
Hardening
The Hardening section at the bottom of the form:
- Rollback-detection anchor: writes a small anchor sidecar at the path you give. Keep it on separate trusted storage (a USB stick) for it to actually defend against rollback.
- Advanced size-hiding (paranoid) (collapsed):
- Pad files to power-of-2 chunks: round each file's chunk count up to the next power of 2 (hides the exact size from disk forensics, up to 2x storage)
- Hide exact sizes: move the size into the encrypted first chunk (implies padding)
- On-disk format (advanced) (collapsed), see below.
The two collapsed panels are not shown for FIDO2-direct.
On-disk format
Two checkboxes, both ticked by default:
- Use v0.2.1 format (default; LBM5 + LUKSBOX2 header + crash-safety
mirrors): 64 MiB metadata cap, lower spill threshold, and
crash-safety mirrors next to the vault; requires LUKSbox v0.2.1+ to
open. Unticked, the vault uses v2 (legacy -- inline chunk lists, no
sidecar mirrors, ~10 GiB practical per-vault ceiling, NOT
crash-safe, readable by every LUKSbox release ever shipped). Untick
it only if you need to share the new vault with a colleague on a
pre-v0.3 LUKSbox install AND you can suppress the auto-upgrade
trigger via
LUKSBOX_FORMAT_V2=1in their environment; otherwise the first flush on their side will upgrade the vault and lock them out of older binaries. The choice is permanent for the vault. See the CLI create page for the full comparison. - Header format v3 (default; rollback-detectable keyslot table) (0.6.0+): every keyslot change (enroll, revoke, update, rotate) bumps a header generation that the anchor records, so restoring an older header (for example a backup taken before a revoke, which would bring the revoked credential back) is detected at open. Pair it with an anchor on separate storage. A v3 vault needs LUKSbox 0.6.0+ to open: untick the box only if LUKSbox 0.2.1-0.5.x must still open this vault. It needs the v0.2.1 format, so it is greyed out when that box is unticked. You can upgrade later from Keyslots.
Deniable mode
Tick Use a deniable header in the Vault file section to
build a deniable vault instead of a
standard one. Every byte of the resulting 36 KiB header is
indistinguishable from random output: there is no LUKSbox magic,
no version field, no parseable structure for file(1) / libmagic
/ yara to latch onto.
When deniable mode is on the Create form changes in four ways:
- The detached-header option disappears (deniable vaults do not support one).
- The FIDO2-direct variant disappears from the keyslot picker. Every deniable variant carries a passphrase (the envelope-opening factor) by design, so pure-FIDO2 deniable vaults are not possible. The variants that remain are Passphrase, Passphrase + FIDO2, Passphrase + TPM, Passphrase + TPM + FIDO2, and the four hybrid-PQ counterparts (on macOS, Secure Enclave + passphrase and its FIDO2 / ML-KEM variants).
- The cipher and Argon2id choices stay, but the GUI warns that forgetting the cipher choice or the Argon2id parameters bricks the vault. In deniable mode these values are part of the secret, not stored in the header.
- For hybrid-PQ variants, the optional seed-file passphrase
field shows the hint "Leave BLANK to reuse the envelope
passphrase". One passphrase then opens both the slot envelope
and the
.kyberseed file. Fill it to set a distinct seed-file passphrase (defence in depth; both must be typed at every unlock).
A deniable vault is never added to the recent-vaults list.
See the full deniable mode reference for the supported variants and trade-offs vs the standard format.
Creating
Click Create vault at the top right. Two things happen:
- A "Working..." overlay appears; Argon2id KDF runs (takes 0.5 - 4 sec depending on your preset)
- For FIDO2 keyslots: the GUI prompts for a touch on your hardware key (twice: once to register a new credential, once to derive the keyslot secret)
On success, you're auto-navigated to the Browser view with the new (empty) vault open. You can now import files (via the + Add file... toolbar button, by dropping files from your file manager onto the file list, or by mounting the vault as a drive and using your file manager) or manage keyslots.
Errors you might see
| Error | What it means | Fix |
|---|---|---|
| "... already exists" | The vault path (or its header, anchor or .kyber path) is taken |
Pick a different name, or move the old file aside |
| "No FIDO2 authenticator detected ..." | No device plugged in or libfido2 can't see it | Plug in / check udev rules on Linux (install guide), then Re-detect |
| "hybrid mode requires a path for the .kyber seed file" | Hybrid-PQ kind selected but no seed file path given | Fill the .kyber path |
| "maximum size: ..." | The maximum size field holds a value LUKSbox cannot use | Fix the value (the line under the field says why) |
An empty passphrase is not an error, but the GUI asks for a
confirmation first: anyone with the .lbx file could open such a
vault.