FAQ
Common questions about LUKSbox - licensing, hardware, post-quantum, recovery.
If your question isn't here, file an issue on GitHub or email [email protected].
Maturity + intended use
Is LUKSbox safe to use today?
It is a pre-v1, and we are upfront about that. The on-disk format is locked, the cryptographic primitives are NIST/RFC standards built on RustCrypto, thirteen rounds of internal audit have shipped (every CRITICAL + HIGH + MEDIUM finding fixed in the same revision that surfaced it; 30M+ fuzz iterations across 15+ harnesses), and a workspace-wide audit of secret-memory handling + filesystem TOCTOU
- sidecar DoS landed in 2026-05. External paid audit and broader real-world deployment are the next milestones. The cloud-storage threat model (provider can't read your data even under subpoena) is what it is built for and what it does today. The "compromised-host-after-unlock" threat model is, and will remain, out of scope for any user-space tool. See the security architecture and the threat model.
What is LUKSbox actually for?
Storing sensitive files on places you do not fully trust:
- Cloud storage (iCloud, Google Drive, Dropbox, OneDrive, S3, Backblaze, ...)
- Network shares, NAS units, or sync folders managed by someone else
- USB sticks and external drives that travel
- Backup media that lives outside your physical reach
You encrypt locally with your keys, drop the resulting .lbx
wherever, and mount it back as a real drive when you need it. The
provider sees one opaque, indistinguishable-from-random blob and
cannot decrypt it even under legal compulsion. See the
comparison page for the head-to-head against provider
encryption, LUKS2, VeraCrypt, age, gocryptfs, and BitLocker /
FileVault.
How is this different from cloud-provider encryption?
Provider-side encryption (Drive, Dropbox, S3 SSE, etc.) is encryption by the provider, for the provider. They generate the key, store it, and can be compelled to use it. The data is plaintext to them.
LUKSbox encrypts the file before it reaches the provider. The key never leaves your machine. The provider holds ciphertext only.
How can I help find bugs?
The Security tests page lists every regression
suite, every fuzz harness, and four concrete contribution paths
(corpus seeds, new fuzz harnesses, regression-test suggestions,
AFL++ campaigns). The fastest impact path is dropping a real-world
input file under
fuzz/corpus/<target>/
and opening a PR.
Licensing + commercial use
What does Apache 2.0 actually let me do?
Use LUKSbox personally, inside your organisation, in commercial products, even in products that compete with LUKSbox. Modify it. Redistribute it (modified or not). Apache 2.0 is OSI-approved open source - the only restrictions are bookkeeping (keep the LICENSE and NOTICE files, mark modified files, propagate copyright headers) and a patent-retaliation clause (sue someone for patent infringement related to the code, lose your license).
What Apache 2.0 explicitly does NOT grant is the right to use the LUKSbox or Penthertz trademarks. The code is free; the brand is reserved. See TRADEMARK.md.
For the canonical text see the Apache License 2.0.
Is LUKSbox really open source?
Yes. Apache 2.0 is one of the most widely-adopted OSI-approved open source licenses, used by Kubernetes, Rust itself, Tailscale's client, Bitwarden's libraries, the entire RustCrypto ecosystem, Apple's Swift, and basically every modern infrastructure project. You can package LUKSbox into Debian, Fedora, Arch, NixOS, Homebrew, or any other distro without restriction. You can fork it, sell it, build a hosted service from it, integrate it into a closed-source product - all permitted. The only thing you can't do is call the result "LUKSbox" or imply Penthertz endorsement.
Can I use LUKSbox in my company?
Yes. Internal use is unlimited and unrestricted. You can deploy LUKSbox on every employee laptop, build internal tooling that calls it, train your support team on it, sell consulting services that use it. The license restriction kicks in only if your COMMERCIAL PRODUCT is itself a LUKSbox-derived encrypted-container tool.
Hardware support
Which security keys work?
Any CTAP2-compliant FIDO2 authenticator with the hmac-secret
extension. There is a difference between what we have actually
exercised end-to-end in our lab and what is spec-compliant but
not yet in our test matrix, see
FIDO2 keyslots, Supported devices
for the full split table.
- Tested end-to-end: YubiKey 4 / 5 / Bio (USB-A, USB-C, NFC, Lightning) and Yubico Security Key Series (same Infineon stack as YubiKey 5, around €29-€35, the cheapest first-party Yubico device for LUKSbox use), Google Titan Security Key v2 (USB-C / NFC), SoloKey 2 / Solo 2 (incl. stateless mode), Windows Hello platform authenticator (Win11 22H2+).
- On the next-release test plan: Nitrokey 3, USB Armory Mk II
- custom FIDO2 firmware (research / DIY only, see the side-channel note in the Choosing a hardware key section for why USB Armory is not a daily-driver recommendation).
- Spec-compliant but not yet in our matrix: Trezor Safe 3 / 5, Token2 PIN+, OnlyKey, and any other CTAP2 + hmac-secret device. These should work; if you successfully use one, please tell us so we can move it to the "Tested" row in the next release.
For a price + audit-history comparison of these devices, see Choosing a hardware key.
What if my key produces a really long credential ID?
Slot layout V3 (current default for new vaults) accepts cred IDs up to 352 bytes. Reported real-world sizes range from 64 B (YubiKey) to 288 B (Google Titan). If your device exceeds 352 B, file an issue and we'll bump the cap.
Does it work without a hardware key?
Yes. Every vault can have a passphrase keyslot. FIDO2, TPM 2.0, and hybrid-PQ are all optional layers on top.
Do I need a TPM?
No. The TPM keyslot is one option among five families (passphrase, FIDO2, Windows Hello, TPM 2.0, hybrid PQ); a vault with no TPM slot opens identically on any machine. Use a TPM slot when you want to bind the vault to a specific machine on top of the other factors. Today TPM keyslots are Linux only, Windows TBS support is tracked.
How do I let LUKSbox use the TPM without root?
Add yourself to the tss group on most distros, or drop the udev
rule from
docs/TPM_LINUX_PERMISSIONS.md.
The release tarball's dist/install.sh offers to do this
interactively. The wizard's TPM-permissions diagnostic also prints
the exact remediation commands when it detects the issue.
Post-quantum
Why ML-KEM-768 / 1024 specifically?
These are the FIPS 203 (August 2024) NIST-standardised PQ key
encapsulation algorithms. ML-KEM-768 is security category 3 (~AES-192
strength); ML-KEM-1024 is category 5 (~AES-256). Both exceed ANSSI's
"Renforce" tier; ML-KEM-1024 qualifies for "Eleve". RustCrypto's
ml-kem crate
is FIPS-validation-in-progress.
Should I use post-quantum keyslots?
Yes if you're protecting data that needs to stay confidential past
2035 against a CRQC adversary who can capture USB-HID traffic
during your enrollment / unlock today. No if you don't have a way
to keep the separate .kyber seed file on trusted storage that's
SEPARATE from the vault file. See
Post-quantum keyslots.
Why hybrid PQ instead of pure ML-KEM?
Hybrid keyslots derive the wrap-KEK via HKDF-SHA256 over both an Argon2id-stretched passphrase (or FIDO2 hmac-secret) AND an ML-KEM shared secret. If a future cryptanalytic break hits one primitive, the other still protects the vault. ML-KEM is young; pairing it with battle-tested classical primitives is the standard PQ-transition guidance.
Recovery + losing things
What if I lose my YubiKey?
Depends on the keyslot kind AND on whether you enrolled a backup slot. The mode-vs-recoverability matrix is the next question; the short version:
Fido2HmacSecret(the "wrap" radio in the GUI / wizard): random MVK wrapped under the device. Without a backup slot you cannot recover. Enroll a passphrase or second-device backup BEFORE you need it.Fido2DerivedMvk(the "FIDO2-direct" radio): MVK is derived from the device. You can still add a backup passphrase at create time (the GUI form has a field for it; the wizard asks). With the backup, you recover by passphrase; without it, the vault is lost if the device dies.
See Recovery for the step-by-step.
Why are there two FIDO2 modes (wrap vs direct), and what's the practical difference?
Two SlotKind values back the FIDO2 family:
Fido2HmacSecret("wrap" mode, default radio), a fresh random MVK is generated and AEAD-wrapped under a KEK derived from the authenticator's hmac-secret response. The wrapped MVK lives inside the keyslot on disk.Fido2DerivedMvk("FIDO2-direct" radio), the MVK is the HKDF expansion of the hmac-secret response. There is no FIDO2-side wrapped MVK on disk for that slot; the keyslot stores only the salt + cred ID.
What that gets you depends entirely on whether you enrol a backup:
| Configuration | Wrapped MVK on disk? | Recover from device loss? | Offline brute-force surface |
|---|---|---|---|
| Wrap, no backup | Yes (under FIDO2-derived KEK only) | No | Wrap KEK is FIDO2-derived; brute-force needs to break CTAP2 hmac-secret (very strong) |
| Wrap + passphrase backup (added later via the keyslot manager) | Yes (one slot per kind) | Yes (use backup) | The passphrase slot is the weakest link; Argon2id slows it |
| Direct, no backup | No (this is direct mode's defining property) | No | Nothing to brute-force at all |
| Direct + passphrase backup (filled at create time, auto-enrolled) | Yes (a passphrase slot is added; same MVK is wrapped under the passphrase KEK) | Yes (use backup) | Same as wrap + backup: passphrase slot is the weakest link |
So:
- If you enrol a passphrase backup in either mode, the two modes collapse to functionally the same thing on the offline-disk-stolen attack surface. The wrap mode's FIDO2-side ciphertext is irrelevant once a passphrase slot exists; the attacker would target the passphrase slot anyway.
- The "no wrapped MVK on disk" property of
Fido2DerivedMvkonly exists in the no-backup configuration. Enrolling a backup passphrase silently removes that property. That's the design trade-off the GUI's create form now spells out beside the backup field. - Pick
Fido2HmacSecret(wrap) for the conventional setup (multiple keyslots, recovery-friendly). - Pick
Fido2DerivedMvk(direct) without a backup if you want the strongest single-factor property (no offline brute-force attack surface at all) and accept that losing the device loses the vault.
What if my TPM dies or I reinstall the OS?
A TPM keyslot is bound to that specific TPM chip's endorsement seed.
If you reinstall the OS the seed is preserved (it's in the chip, not
the OS); if the chip is replaced or the device is wiped at firmware
level, that slot is unrecoverable. Always add a backup slot
(passphrase or FIDO2) when bootstrapping a TPM-only vault. The
GUI surfaces a warning to that effect on the create flow; the wizard
prompts for explicit confirmation; the CLI prints the same warning
when you bootstrap with --kind tpm2 / tpm2-pin / tpm2-fido2.
What if I forget my passphrase?
If you have another keyslot enrolled (FIDO2 or another passphrase), unlock with it and enroll a fresh passphrase. If passphrase is your only keyslot: vault is unrecoverable. Argon2id at the default preset takes 10^14 years to brute-force a 5-word EFF passphrase - not "a few months with a powerful computer."
Can I rotate the master key?
Yes - luksbox rotate-mvk <vault>. Use this after revoking a
compromised keyslot. See
luksbox rotate-mvk.
Comparison with other tools
How does it compare to LUKS2 / cryptsetup?
| LUKS2 | LUKSbox | |
|---|---|---|
| FIDO2 keyslots | systemd-cryptenroll integration | First-class slot kind, multi-device, hybrid-PQ-FIDO2 |
| Post-quantum | None | ML-KEM-768 / 1024 hybrid |
| Mounted as | Block device (kernel dm-crypt) | FUSE / WinFsp filesystem |
| On-disk format | LUKS2 (binary header + JSON metadata) | LUKSbox (custom 8 KiB header + postcard metadata) |
| Compatibility | Decades of cryptsetup | Pre-1.0, format may evolve |
| Implementation | C, kernel + userspace | Pure Rust, all userspace |
How does it compare to VeraCrypt?
VeraCrypt has no hardware-key support, no post-quantum, and is written in C/C++. LUKSbox has both as first-class, in memory-safe Rust. VeraCrypt is more battle-tested; LUKSbox is more aggressive about modern cryptography.
How does it compare to age?
age is a file encryption tool, not a vault manager. age encrypts single files; LUKSbox manages a mountable container with multiple files, in-place edits, and per-chunk integrity. age has no hardware key or PQ support. Different problem domains.
Operations + integration
Is the on-disk format stable?
Pre-1.0 the format may evolve under audit guidance. We provide migration tools for any breaking change. v1.0 will lock the format; any v1.x release will read any vault from any other v1.x release.
Does it upload anything?
No. Zero network calls in the codebase outside what luksbox check update does (an opt-in HTTPS GET to GitHub Releases). No telemetry,
no analytics, no phone-home. Verifiable by reading the source.
Can I use LUKSbox programmatically?
The Rust crates (luksbox-core, luksbox-format, luksbox-fido2,
luksbox-pq, luksbox-vfs, luksbox-mount) are designed to be
used as libraries. The luksbox CLI is itself a thin wrapper
around them. See Build from source for the workspace
layout.
Plausible deniability / hidden volumes?
Not yet. There's no "duress passphrase" feature that opens a decoy vault. On the roadmap if there's user demand.
Where to ask further questions
- Bug reports + feature requests: GitHub Issues
- Security disclosure: see Disclosure
- Commercial inquiries: [email protected]
- Penthertz: penthertz.com