luksbox header-backup

Save a copy of the 8 KiB header bytes for offline recovery.

luksbox header-backup <PATH> <OUT> [--header <HDR>]

Saves a copy of the 8 KiB header bytes (offsets, keyslots, salts, HMAC) to a separate file. Equivalent to cryptsetup luksHeaderBackup.

header-backup does not require unlock material. It just dumps the bytes that already live on disk, after a structural sanity parse to make sure they look like a LUKSbox header before saving. Output file is mode 0600 on Unix.

Examples

Inline-header vault

luksbox header-backup my.lbx /media/usb/my.hdrbak

The 8 KiB at offset 0 of my.lbx are written to /media/usb/my.hdrbak. header-backup refuses to overwrite an existing output file, so back-to-back runs need a fresh path.

Detached-header vault

luksbox header-backup my.lbx /media/usb/my.hdrbak --header /media/usb/my.hdr

When --header is set, the backup is taken from the sidecar's contents instead of the vault file's first 8 KiB.

When to run it

Right after luksbox create.
After every luksbox enroll (a new keyslot is now in the header bytes; the old backup is stale).
After every luksbox revoke.
After every luksbox rotate-mvk (this is the most important one; rotation rewrites the header HMAC under a new MVK).

Output shape

wrote 8192 bytes from my.lbx to /media/usb/my.hdrbak
  cipher: Aes256GcmSiv    metadata at offset 8192 (1048576 B)    data at offset 1056768
  populated keyslots: 1 / 8
note: keep this backup on storage SEPARATE from the vault. Anyone who
has both the .lbx and a backup of its header has the same offline
brute-force surface as anyone who has the original vault.

Security notes

The backup contains the wrapped MVK in every populated keyslot. Brute-forcing the wrapping key (Argon2id passphrase / FIDO2 hmac-secret / TPM seal) is the same problem as on the original vault. The backup does not weaken or strengthen security; it is a copy of the same authenticated-and-encrypted bytes.
Output mode is 0600 on Unix. On Windows, the file inherits the default DACL (typically owner-only). Move it to encrypted external storage as soon as you are done generating it.
The backup is opaque to anyone without a passphrase / key / TPM. It is not safe to commit to public storage.

Restoring

The matching restore subcommand is header-restore. The restore path is HMAC-verified by default against the live MVK to catch tampered or swapped backup files.

Failure modes

Failure	Cause
`output file ... already exists`	The backup target is non-empty. Pick a fresh path or `rm` the old one first
`not a valid LUKSbox header at <path>`	The vault file (or `--header` sidecar) is too damaged to even parse
`reading 8192 bytes from <path>: failed to fill whole buffer`	Vault file is shorter than 8 KiB; probably truncated

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