Documentation
Everything you need to install, use, and understand LUKSbox.
LUKSbox is a Rust-based encrypted-container manager with four keyslot
families: passphrase, FIDO2 / Windows Hello, TPM 2.0
(Linux), and hybrid post-quantum (passphrase / FIDO2 / TPM
combined with ML-KEM). The container mounts as a real drive on Linux
(FUSE), macOS (macFUSE), and Windows (WinFsp), and ships in three
flavours that share the same on-disk format and the same Container
core: the luksbox CLI, the luksbox wizard interactive TUI, and
the luksbox-gui desktop application.
Use LUKSbox for shared or backup copies, not as your only copy
LUKSbox is built to make a secondary copy of your data safe to put in places you don't control: a cloud sync folder, a USB stick you carry around, a vault you send to a colleague or client. It is not designed to be the sole place a file lives.
Like every encrypted container, a LUKSbox vault is a single point
of failure. If the .lbx file is corrupted, lost, or every keyslot
becomes inaccessible, the data is gone. The
forensic toolkit helps with many damage
scenarios but cannot recover bytes that are no longer on disk or no
longer AEAD-tagged.
Best fits:
- Sharing an encrypted folder with a colleague or client over a generic transport (Slack attachment, email, S3 link).
- A cloud backup on Dropbox, iCloud, OneDrive, Nextcloud, S3, Backblaze, etc. without trusting the provider.
- Moving sensitive files on an insecure USB stick or a shared computer.
- A portable encrypted scratch space that travels across your machines.
Always keep an unencrypted copy somewhere you trust (your local disk, a personal cloud, a NAS) for any file you cannot afford to lose. Treat the LUKSbox vault as the travelling copy, not the master copy.
The full no-warranty / no-liability / export-controls / data-loss
notice lives on the Disclaimer page and in
DISCLAIMER.md
in the source repository. The Apache 2.0 license covers the legal
floor; the disclaimer restates it in plain English.
Pick a path
- New here? Start with Quickstart - create your first vault and mount it as a drive in under a minute.
- Setting up a hardware key? See FIDO2 keyslots for the full enrollment + unlock flow with YubiKey, Google Titan, Nitrokey, or Windows Hello.
- Want a machine-bound vault? TPM 2.0 keyslots covers all seven TPM variants (with / without PIN, fused with FIDO2, hybrid PQ permutations).
- Worried about post-quantum? Post-quantum keyslots explains the hybrid ML-KEM design and when you should turn it on.
- Want plausible deniability? Deniable mode creates vaults whose on-disk bytes are indistinguishable from random.
- Want guided prompts? Use the TUI wizard, same operations as the CLI, with confirmation dialogs.
- Looking up a flag? Jump to the CLI reference.
- Lost your key? Recovery covers the passphrase-backup, multi-key, and TPM-loss paths.
- Vault file damaged? Forensics and partial recovery
walks through
header-backup/header-restore/header-dump/check/extract --tolerate-errors. - Want to help find bugs? Security tests lists the fuzz harnesses and contribution paths.
- Building from source? Build covers the toolchain, cross-compile, and signature-verification workflow.
Documentation map
| Section | Contents |
|---|---|
| Getting started | Install, quickstart, platform notes |
| Keyslots | Passphrase, FIDO2, TPM 2.0, post-quantum |
| CLI | Every subcommand with examples |
| TUI | Interactive wizard walkthrough |
| GUI | Desktop application screen-by-screen |
| Operations | Recovery, backup, mount lifecycle |
| Security | Architecture, threat model, cryptography, tests, audit, disclosure |
| Build | From source, reproducible builds, verification |
The full spec for what happens cryptographically per operation lives
in the source repository at
docs/CRYPTO_SPEC.md.
- Getting started Install LUKSbox, create your first vault, mount it as a drive.
- Keyslots Passphrase, FIDO2, TPM 2.0, and hybrid post-quantum keyslots.
- Desktop GUI egui-based desktop client for LUKSbox - same Container core as the CLI, plus a click-driven UI.
- TUI wizard luksbox wizard - the interactive walkthrough. Same operations as the CLI, with confirmation prompts and inline explanations.
- CLI reference Every subcommand of `luksbox`, with examples.
- Operations Recovery, backup, and day-to-day vault lifecycle.
- Security Threat model, audit reports, and the cryptographic foundations.
- Build from source Compile LUKSbox yourself, run the test vectors, verify reproducible-build hashes.
- FAQ Common questions about LUKSbox - licensing, hardware, post-quantum, recovery.