luksbox header-restore

Replace a damaged on-disk header with a previously saved backup.

luksbox header-restore <PATH> <INPUT> [--no-verify] [--header <HDR>]

Replaces the on-disk header with bytes from a previously saved backup file. By default, the new header is HMAC-verified against the current MVK before being written, which prevents an attacker who replaces your backup file from silently installing a header that authenticates under their own MVK.

In inline mode this rewrites the first 8 KiB of the vault file in place, then fsyncs it. In detached mode (--header /path/to.hdr, inherited from the common unlock flags) it atomically replaces the sidecar via temp + rename + parent-dir fsync.

Examples

Default: HMAC-verify before writing

luksbox header-restore my.lbx /media/usb/my.hdrbak
# input /media/usb/my.hdrbak: parses as a valid header (cipher Aes256GcmSiv, header_salt prefix 09ec28b5)
#   HMAC verify: OK (the backup was sealed under this vault's current MVK)
# restored inline header to my.lbx (in-place write of bytes 0..8192, fsynced)

header-restore opens the vault, recovers the live MVK from a keyslot, then HMAC-checks the backup file before overwriting anything. If the check fails, the on-disk header is not touched.

Damaged on-disk header: skip verify

luksbox header-restore my.lbx /media/usb/my.hdrbak --no-verify
# input ...: parses as a valid header (cipher ...)
# warning: --no-verify is set; the backup file is NOT being HMAC-checked
#  against the current MVK. Use this only if you trust the source of
#  the backup file.
# restored inline header to my.lbx (in-place write of bytes 0..8192, fsynced)

--no-verify is the only option when the on-disk header is so damaged that you cannot unlock the container at all (since the default verify path needs to recover the MVK first). Use it only when the backup file came from a trusted source.

Detached-header vault

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

The sidecar at /media/usb/my.hdr is atomic-replaced. The vault file itself is not touched.

What gets written

Mode	What is rewritten	Atomicity
Inline (no `--header`)	Bytes 0..8192 of the `.lbx` file, in place	Not atomic across crashes (single `pwrite`+`fsync`); the rest of the vault is untouched
Detached (`--header <p>`)	Entire content of `<p>`	Temp + rename + parent-dir fsync

For inline mode, take a fresh header-backup immediately before running header-restore if you are paranoid about a crash mid-write leaving the header half-rewritten.

Security notes

The default-on HMAC verify is what prevents the attack "swap the user's backup file, install a header that opens with the attacker's MVK on the next restore". --no-verify opts out of that check; use it only when the on-disk MVK is unrecoverable.
A backup taken before the most recent enroll / revoke / rotate-mvk is stale. The HMAC verify will reject it because the live MVK differs. Always re-run header-backup after operations that mutate the header.
A backup from a different vault will fail the verify with HMAC of <input> does NOT verify against the vault's current MVK.

Failure modes

Failure	Cause
`not a valid LUKSbox header at <input>`	Backup file's magic / structure is wrong
`reading 8192 bytes from <input>: failed to fill whole buffer`	Backup file is shorter than 8 KiB
`HMAC of <input> does NOT verify against the vault's current MVK`	Backup is for a different vault, an older MVK, or has been tampered. Use `--no-verify` only if you can vouch for the backup's source
`could not unlock the vault to HMAC-verify the new header against the current MVK`	The on-disk header is too damaged to unlock with. Run with `--no-verify`

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