LUKSbox

LUKSbox

Encrypted vaults that survive the next decade.
Open-source, FIDO2 + TPM 2.0 native, post-quantum-ready.
Store sensitive files in the cloud or on shared media without trusting the host.

Built by

Website | Docs | Security | Fuzzing | Compare

What it solves

You probably already store sensitive files where you don’t fully control the storage: cloud sync (iCloud, Drive, Dropbox, OneDrive, S3, Backblaze), NAS units, USB sticks that travel, backup tapes that end up at a recycler. The provider promises encryption-at-rest “with their keys.” LUKSbox encrypts the file before it ever leaves your machine, under your keys, in a single container that is opaque to the provider and tamper-evident on the way back.

A LUKSbox vault is one file (.lbx), optionally with a separate header (.hdr) and post-quantum sidecar (.kyber) that you keep on different storage. Drop it on any cloud or shared medium. The provider sees one indistinguishable-from-random blob and cannot decrypt it even under legal compulsion. Mount it locally as a real drive when you need to use it.

The full per-tool comparison (vs LUKS2 / VeraCrypt / age / gocryptfs / Cryptomator / BitLocker / FileVault) lives at https://luksbox.penthertz.com/compare/.

A LUKSbox vault is a travelling copy, not a master copy. Use it for the cloud, a USB stick, a vault you share with a colleague or client, anywhere you would not put plaintext. Like every encrypted container it is a single point of failure: if the .lbx file is corrupted or every keyslot becomes inaccessible, the data is gone. The forensic toolkit (header-backup, check, extract --tolerate-errors) helps in many damage scenarios but cannot recover bytes that are no longer on disk or no longer AEAD-tagged. Always keep an unencrypted copy somewhere you trust for any file you cannot afford to lose.

Status

This is a pre-1.0 release. The on-disk format is locked, the cryptographic primitives are NIST/RFC standards built on RustCrypto, and 15 internal audit rounds have shipped. 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 LUKSbox is built for and what it does today.

How a vault is opened

The Master Volume Key (MVK) is the root secret. Keyslots do not encrypt files directly; they wrap the MVK. Once a valid keyslot unwraps the MVK, every other key in the vault is derived from it via HKDF-SHA256 with a per-purpose info string. Lose the keyslot material, lose the MVK; revoke a slot and that material is permanently unable to recover the MVK from this vault.

For the full architecture map (on-disk graph, unlock sequence, concurrency / crash-safety pipeline, on-disk footprint), see https://luksbox.penthertz.com/docs/security/architecture/.

Security mechanisms

The full attack matrix (defended vs not defended) is at https://luksbox.penthertz.com/docs/security/threat-model/.

Quick start

# Create a vault (defaults: AES-256-GCM-SIV, Argon2id interactive)
luksbox create my-vault.lbx

# Mount it on a drive letter / mountpoint (runs in the background;
# add -f to keep it in the foreground)
luksbox mount my-vault.lbx /mnt/v       # Linux/macOS
luksbox mount my-vault.lbx Z:           # Windows
luksbox umount Z:                       # unmount (or /mnt/v)

# Add a FIDO2 hardware factor
luksbox enroll my-vault.lbx --kind fido2

# Add a TPM 2.0 keyslot bound to this machine (Linux / Windows)
luksbox enroll my-vault.lbx --kind tpm2

# Hybrid post-quantum: needs a separate `.kyber` seed file
luksbox create my-vault.lbx --kind hybrid-pq \
    --pq-hybrid /media/usb/my.kyber

# Vaults use the v3 format by default: no per-vault size ceiling, plus
# crash-safety sidecar mirrors (needs LUKSbox v0.2.1+ to open). Pass
# --format v2 only to share with a pre-v0.2.0 reader; v2 uses inline
# chunk lists with a practical ceiling around 10 GiB.
luksbox create my-vault.lbx --format v2

# Migrate an existing v2 vault up to the v3 format (source untouched)
luksbox migrate-to-v3 old-v2.lbx --dst new-v3.lbx

# Cap the vault file at 6 GiB (0 = unlimited, the default), see where
# its size goes, and give the free space at its end back to the disk
luksbox create my-vault.lbx --max-size 6G
luksbox size my-vault.lbx
luksbox size my-vault.lbx --shrink

# Interactive walkthrough, no flags to remember
luksbox wizard

Three interfaces, one on-disk format: the luksbox CLI for scripts, the luksbox wizard interactive TUI, and the luksbox-gui desktop application. See https://luksbox.penthertz.com/docs/ for per-flow walkthroughs.

Install

The .deb and .rpm packages now Recommend tpm-udev + tpm2-tools (Debian / Ubuntu) and tpm2-tss + tpm2-tools (Fedora / RHEL / openSUSE), so installing them via apt / dnf brings the /dev/tpm* udev rules and the tss system group along for the ride. After install you still need to add yourself to the group once and log back in, that is the Debian / Fedora convention for any package that grants new device access:

sudo usermod -aG tss "$USER"
# log out + log back in, then verify:
id | tr , '\n' | grep tss

The Linux release tarball’s dist/install.sh --tpm-setup does the same thing for users who installed via tarball instead of apt / dnf and don’t have tpm-udev / tpm2-tss already.

Help find bugs

LUKSbox is a young codebase. The cryptography rests on standardised primitives and well-audited Rust libraries (RustCrypto, libfido2, tss-esapi), but the integration layer and the on-disk format are ours. We want external eyes on this.

Run the fuzzers

Every parser that touches attacker-controlled bytes has a libFuzzer harness in fuzz/ and an AFL++ harness in fuzz-afl/. PR CI runs each libFuzzer target for 5 minutes on the persistent corpus; a dedicated server runs the AFL++ campaigns for hours per release.

cargo install cargo-fuzz
cd fuzz
cargo +nightly fuzz run header_parse -- -max_total_time=300

The current target list (header_parse, keyslot_parse, metadata_parse, hybrid_sidecar_parse, seed_file_parse, auth_then_process, header_roundtrip, winfsp_path_parse, webauthn_device_path, vfs_ops) plus per-target invariants is in FUZZING.md.

Add corpus seeds

The fastest way to push fuzzing further is dropping a real-world input file into fuzz/corpus/<target_name>/ and opening a PR. Examples that would help today:

• Real headers from old vault layouts (V1 / V2) for header_parse
• Authenticator-specific cred IDs (Google Titan, SoloKey stateless, Trezor) for keyslot_parse
• Edge-case Windows paths (UNC, network share, long path with device-namespace prefix) for winfsp_path_parse
• Truncated / extended .hybrid sidecars for hybrid_sidecar_parse

Add a new fuzz target

If a parser doesn’t have a harness yet and you can imagine an attacker shaping its input, please add one. See the harness template in FUZZING.md.

Suggest a regression test

If you spot a code path where invariants aren’t tested but feel like they should be, file a regular GitHub issue (label security-regression) with the invariant in plain English. We write the test and credit the suggestion in the changelog.

Run the AFL++ campaign

scripts/fuzz_server.sh runs an AFL++ campaign indefinitely against any target. If you have spare cycles and want to find something the libFuzzer 5-minute PR run misses, this is the lever.

Reporting issues

Suspected vulnerabilities take priority over everything else. We respond within 72 hours and credit reporters in the public changelog

• in any advisory we publish.

Repository layout

Documentation

The full documentation lives at https://luksbox.penthertz.com/:

In-repo references for contributors:

• SECURITY.md, disclosure policy + threat model summary
• BUILDING.md, per-platform build instructions
• TESTING.md, test taxonomy + how to run each tier
• FUZZING.md, fuzz harness setup + target list
• DEVELOPMENT.md, maintainer dev workflow + release process
• docs/CRYPTO_SPEC.md, per-operation cryptographic walkthrough
• docs/VAULT_SIZE.md, maximum vault size and giving back free space
• docs/SECURITY_ARCHITECTURE.md, security architecture map (mirrors the website page)
• docs/HARDWARE_SIDE_CHANNEL_NOTES.md, published side-channel attacks against FIDO2 silicon
• docs/TPM_LINUX_PERMISSIONS.md, end-user playbook for /dev/tpmrm0 access
• docs/PROJECT_OVERVIEW.md, project overview + comparison vs LUKS2 / VeraCrypt
• docs/TPM_FUTURE_IMPROVEMENTS.md, TPM roadmap (PCR sealing, attestation) + the shipped Windows TBS design record

License

Source code is licensed under the Apache License, Version 2.0. LUKSbox is OSI-approved open source: read the source, audit the cryptography, build it yourself, modify it, redistribute it, and use it in any product including commercial offerings that compete with LUKSbox. The Apache 2.0 grant includes an explicit patent license from every contributor, which matters for a cryptography project.

What’s explicitly NOT granted by the copyright license is the right to use the LUKSbox or Penthertz trademarks in your derived work; see TRADEMARK.md. You can fork the code and ship it; you cannot call your fork “LUKSbox” or imply endorsement by Penthertz.

The NOTICE file contains the attribution that downstream redistributors must propagate (per the license’s Notices section).

The DISCLAIMER restates the no-warranty / no-liability clauses (LICENSE sections 7 and 8), the data-loss reality of any encrypted container, and the export-control responsibility, in plain English. Read it once before relying on LUKSbox to protect material information.

Author

Maintained by Sébastien Dudek, Penthertz (penthertz.com, @PentHertz, [email protected]). See SECURITY.md sec.1 for the responsible-disclosure flow.