# LUKSbox calls its on-disk format v1.0.1 while the crate is still at 0.5.2

> An Apache-2.0 encrypted container written in Rust across twelve crates, wrapping a single master volume key with passphrase, FIDO2, TPM and ML-KEM keyslots. The security story is mostly self-assessed: fourteen internal audit rounds, no third-party audit, and two allow-listed advisories.

**PentHertz/LUKSbox** — Store sensitive files in the cloud, or on shared media without trusting the host. LUKSbox is a Rust-based encrypted-container tool with passphrase, FIDO2 (YubiKey, Titan, Nitrokey, Windows Hello), TPM 2.0/SEP, and hybrid post-quantum (ML-KEM-768 / 1024) keyslots. Mounts as a real drive on Linux, macOS, and Windows.

- Repository: https://github.com/PentHertz/LUKSbox
- Website: https://luksbox.penthertz.com
- Stars: 742 · Forks: 58
- Language: Rust
- License: Apache-2.0
- Published: 2026-09-19 · Updated: 2026-09-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/penthertz-luksbox

## Two version counters run in parallel, and only one of them is public

The workspace manifest sets version 0.5.2, edition 2024 and rust-version 1.88, and the release history agrees with it: v0.5.1 on 2026-08-03, v0.5.2-rc.1 on 2026-08-11 and v0.5.2 on 2026-08-12, with the last push dated the same day as the final tag. The second counter lives in the format. A comment beside the AEAD dependencies says AES-GCM-SIV is the default suite for new vaults from format v1.0.1 onward, so the on-disk format is already past 1.0 while the software carrying it is described as a pre-1.0 release whose format is locked. Two version lines moving at different speeds is a reasonable design, but it means a vault written by this build carries a format number a user will never see in a release tag, and nothing in the README maps one onto the other.

## Three AEAD suites coexist, and existing vaults never migrate on their own

The workspace depends on aes-gcm, aes-gcm-siv and chacha20poly1305, and the security table lists all three as file-chunk and metadata AEAD choices with AES-256-GCM-SIV marked as the default. The reasoning for preferring SIV is spelled out in a manifest comment: it is the nonce-misuse-resistant construction from RFC 8452, it keeps the same 12-byte nonce and 16-byte tag wire shape as AES-GCM so the on-disk chunk layout is byte-identical, and a nonce collision under the same key becomes detectable rather than catastrophic. The cost is a permanent split. Pre-existing vaults stay on whatever suite their header was stamped with at create time, so a directory of vaults can legitimately hold two generations of cipher choice with no automatic upgrade path between them.

## Every keyslot wraps one master volume key, so the slots are the vault

The key hierarchy is the part worth understanding before trusting the design. The master volume key is the root secret. Keyslots do not encrypt files, they wrap that one key, and everything else derives from it through HKDF-SHA256 with a per-purpose info string: the header HMAC key, the metadata AEAD key, per-file keys and the anchor HMAC key. That makes keyslot management the whole risk surface. Losing keyslot material loses the master volume key, and revoking a slot is one-way, since the revoked material can no longer recover that key from this vault even if it is restored. Passphrase entry goes through Argon2id at 256 MiB, three iterations and a parallelism of four, with those cost parameters bounded by the parser so a crafted header cannot turn a passphrase check into a denial of service.

## Fourteen internal audit rounds, and no third-party audit has happened

The status page is unusually specific, which makes the gap in it easier to see. The workspace test suite reports 600+ passing and 0 failing, with a few platform-gated tests skipping off-platform. cargo audit reports zero vulnerabilities and zero unsound advisories while carrying two allow-listed unmaintained ones, paste as a compile-time-only proc-macro from the TPM stack and registry on Windows and WinFsp only, both written up in audit.toml and SECURITY.md. Fuzzing totals more than 30 million iterations across ten libFuzzer harnesses, and the tree holds both a fuzz/ directory and a separate fuzz-afl/ one alongside FUZZING.md. Internal audit rounds are listed at 14 with per-round details kept internal, and third-party audit is recorded as not yet performed, with an engagement scope package available on request.

## A vault is a travelling copy, and the fix for a lost one is a plaintext copy

The README carries an explicit warning that is worth reading before anything else on the page. A LUKSbox vault is a travelling copy, not a master copy, and 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. Three forensic commands are offered, header-backup, check and extract with tolerate-errors, which help in many damage scenarios but cannot recover bytes that are no longer on disk or no longer AEAD-tagged. The recommended mitigation is blunt: always keep an unencrypted copy somewhere you trust for any file you cannot afford to lose. That is honest, and it also means the strongest claim the project makes applies to files you have a second unprotected copy of.

## Looking like random data depends on taking the header out of the file

A vault is one .lbx file, optionally with a separate .hdr header and a .kyber post-quantum sidecar that you can keep on different storage. The comparison table credits LUKSbox with the provider seeing one indistinguishable-from-random blob, and in the row for how the vault file looks it adds the qualifier in parentheses: with detached header. So the property depends on a configuration choice rather than following from the format, and a single-file vault is the arrangement most people would reach for first. Tamper evidence is spread across the same pieces. An HMAC-SHA256 covers the entire 8 KiB header, each chunk carries associated data built from file id, chunk index and generation so substitution, position swaps and replays of older chunks are all detectable, and whole-vault rollback is covered by the anchor sidecar.

## Twelve crates split by platform concern, and a compare page naming seven rivals

The workspace has twelve members, and their names describe the work rather than a layering: luksbox-core, luksbox-format, luksbox-fido2, luksbox-pq, luksbox-vfs, luksbox-fuse-t, luksbox-mount, luksbox-cli, luksbox-gui, luksbox-tpm, luksbox-sep and luksbox-ct-bench. Platform work is visible in the names, with a TPM crate scoped to Linux and Windows and a SEP crate standing alongside a FUSE one, matching the claim that a vault mounts as a real drive on Linux, macOS and Windows. The manifest also carries a constant-time bench crate, which is the kind of companion tool that shows up when nonce handling was treated as a threat. Two smaller inconsistencies sit in the same file: the workspace homepage is penthertz.com while the project site is luksbox.penthertz.com, and the architecture diagram in the README opens with the four unlock paths and the key derivation fan-out, then stops partway through the rest of the graph.

## Conclusion

The engineering deserves more credit than the surrounding claims. One master volume key with per-purpose HKDF derivation, per-chunk AEAD that binds a file id, chunk index and generation into the associated data, a rollback anchor, and Argon2id cost parameters bounded by the parser so a hostile header cannot turn a passphrase check into a denial of service are all real design decisions rather than adjectives. The caveats are stated plainly enough that they should shape your decision instead of being skimmed past. A vault is a single point of failure, the suggested mitigation is a plaintext copy kept elsewhere, the on-disk format already reads v1.0.1 while the crate sits at 0.5.2, and the audit evidence is fourteen internal rounds with the details kept internal and no third-party review yet. Use it for the travelling copy the project says it is, on cloud sync or shared media you do not control, and do not let it be the only copy of anything that matters until an external audit exists.

## FAQ

### Does LUKSbox support unlocking with a TPM?

Yes, through a TPM 2.0 sealed key encryption key on Linux and Windows, with an optional PIN and a fused mode that combines the TPM with FIDO2. Windows Hello is named as one of the supported FIDO2 authenticators.

### What files make up a LUKSbox vault?

One .lbx container, optionally with a separate .hdr header and a .kyber post-quantum sidecar that can be kept on different storage from the container.

### Has the LUKSbox vault format had an outside security audit?

Not yet. The status table records third-party audit as not performed, with an engagement scope package available on request, and lists 14 internal audit rounds whose per-round details are kept internal.

### What happens when a LUKSbox keyslot is revoked?

That material can no longer recover the master volume key from the vault. Every other key derives from the master volume key, so losing access to all keyslots means losing the data.

### Which cipher does a newly created LUKSbox vault use?

AES-256-GCM-SIV, the nonce-misuse-resistant construction from RFC 8452, as the default suite from format v1.0.1 onward. AES-256-GCM and ChaCha20-Poly1305 remain available, and earlier vaults stay on whatever their header recorded.

### Can LUKSbox recover a damaged vault file?

The commands header-backup, check and extract with tolerate-errors help in many damage scenarios, but the project states they cannot recover bytes that are no longer on disk or no longer AEAD-tagged.

## Sources

- [License: Apache-2.0](https://github.com/PentHertz/LUKSbox/blob/main/LICENSE)
- [PentHertz/LUKSbox on GitHub](https://github.com/PentHertz/LUKSbox)
- [Project website](https://luksbox.penthertz.com)
- [README](https://github.com/PentHertz/LUKSbox/blob/main/README.md)
- [Releases](https://github.com/PentHertz/LUKSbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/penthertz-luksbox