luksbox check

Walk every used chunk in the vault, AEAD-decrypt it, and report per-chunk status.

luksbox check <PATH> [--json] [--stop-on-first-error] [--unlock-args]

Walks every used chunk in the vault, AEAD-decrypts it, and reports per-chunk status (ok or aead_fail). Surfaces the exact (file_path, chunk_idx, on-disk slot_offset, generation) of every chunk the runtime would refuse to decrypt at mount time. Read-only.

Exit code is non-zero if any chunk fails AEAD verification, so check plays nicely with && chains in scripts and with cron-job alerting.

Requires unlock material (passphrase, FIDO2, TPM, or hybrid).

Examples

Basic (human-readable)

luksbox check my.lbx
# checked 1 file(s), 3 chunk(s): 3 OK, 0 BAD

On a healthy vault, exit code 0. On a vault with one corrupted chunk:

luksbox check my.lbx
# BAD  /payload chunk_idx=1 chunk_id=1 gen=5 off=1060892 : crypto: AEAD failure
#
# checked 1 file(s), 3 chunk(s): 2 OK, 1 BAD
# re-run with --json to capture the per-failure details for a bug report.
# error: 1 chunk(s) failed AEAD verification, see above

JSON output

luksbox check my.lbx --json

{
  "vault": "my.lbx",
  "summary": {
    "files": 1,
    "chunks_total": 3,
    "chunks_ok": 2,
    "chunks_bad": 1
  },
  "failures": [
    {
      "file_id": 2,
      "path": "/payload",
      "chunk_idx": 1,
      "chunk_id": 1,
      "generation": 5,
      "slot_offset": 1060892,
      "error": "crypto: AEAD failure"
    }
  ],
  "stopped_on_first_error": false
}

Stop on first error

luksbox check my.lbx --stop-on-first-error

Faster on large vaults when you just want a yes/no answer; off by default since the typical use is "tell me everything that is broken in one pass".

Exit codes

What check actually does

For every file in the decrypted metadata tree, check derives the file's HKDF subkey, then for each chunk reference attempts AEAD_open(suite, file_key, nonce, aad, ciphertext) using the same inputs the runtime would use at mount or get time. Failures are surfaced; successes are tallied.

A single bit flip anywhere inside a chunk's nonce, ciphertext, or tag is enough to fail. check does not distinguish bit rot from deliberate tampering: both look like AEAD failure, which is exactly the security guarantee the format provides.

Use cases

• Pre-mount sanity check. Run luksbox check vault.lbx && luksbox mount vault.lbx mnt in a script. The vault only mounts if every chunk is intact.
• Periodic integrity scan. Cron the command against vaults stored on cloud sync, old USB drives, or SD cards. The output pinpoints the affected file before a user hits the failure.
• Post-incident audit. After a suspected disk failure, check --json produces a structured report you can attach to a bug ticket or run-book entry without redoing the manual chunk-by- chunk debugging.

Limitations

• check only inspects chunks that are referenced by some inode. Chunk slots that are on the free-list (freed by rm / truncate) are not scanned: the format does not promise their contents are decryptable.
• check needs the metadata tree. If the metadata blob itself fails AEAD or fails structural validation, open_vfs errors out before check ever sees a chunk. In that case, header-dump would also fail (for the same reason). There is no current recovery path from "metadata blob destroyed but chunks intact"; that gap is documented in the forensics page.
• Vaults with the FLAG_HIDE_SIZE_HEADER flag still scan every chunk; the size-header bytes inside chunk 0 are not interpreted by check.

See the forensics page for the full recovery flow this subcommand fits into.