Inspect a FileVault2 Header Safely with cryptsetup

Picked up a Mac disk and need to know what you are dealing with before you touch it? cryptsetup fvault2Dump reads and displays the header from a FVAULT2, or FileVault2-compatible, device without activating it or changing a single byte on disk. Allow about ten minutes for a straightforward inspection.

You need the cryptsetup-bin package, the device path, and, if the header is protected, the passphrase or a key file. This guide covers cryptsetup 2.7.0, installed here as package version 2:2.7.0-1ubuntu4.2. The command is normally read-only, but the credentials and output are still security-sensitive, so do not test it on a device you cannot identify.

1. Confirm the installed command

Check the binary and package before choosing options. These are ordinary, read-only commands:

$ command -v cryptsetup
/usr/sbin/cryptsetup
$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ dpkg-query -W -f='${Package} ${Version}\n' cryptsetup-bin
cryptsetup-bin 2:2.7.0-1ubuntu4.2

The first line can differ if your distribution installs the binary elsewhere. If the package or version is not the one you expected, stop and check which installation your shell will run.

2. Identify the device without guessing

Replace /dev/DEVICE with the exact block-device path from your inventory, storage documentation or another trusted inspection process:

$ DEVICE=/dev/DEVICE
$ printf 'chosen device: %s\n' "$DEVICE"
chosen device: /dev/DEVICE

Do not use a partition or disk just because its name looks plausible. On a system using udev, lsblk can help you compare names, sizes and serial information, but it does not prove a device contains FVAULT2 metadata:

$ lsblk -o NAME,PATH,SIZE,TYPE,MODEL,SERIAL
NAME   PATH        SIZE TYPE MODEL       SERIAL
...    ...         ...  ...  ...         ...

Some block devices can only be opened by root. Add sudo to the dump command if normal permissions produce a permission error. Elevation is not a repair and does not make an unknown device safe to inspect.

3. Dump header information

Run the action with the device as its final argument, adding sudo if permissions require it:

$ cryptsetup fvault2Dump "$DEVICE"

$ sudo cryptsetup fvault2Dump "$DEVICE"

The output is device-specific header information, so record it only in a location approved for storage metadata. A successful command does not mount the device, create a mapping or alter the header. The exit status is the first useful check:

$ status=$?
$ printf 'cryptsetup exit status: %s\n' "$status"
cryptsetup exit status: 0

Checkpoint: a non-zero exit status should only appear when the command could not inspect the device, and you should still be able to account for the exact device path used.

4. Handle a passphrase without putting it in shell history

If the device asks for a passphrase, cryptsetup reads it from the terminal. Leave the prompt visible and type it there. Do not append the passphrase to the command, put it in an environment variable, or paste it into a shell history entry.

For an unattended or repeatable run, the manpage supports --key-file, also written -d. A dash means standard input, which lets a separate program supply the secret without it ever touching the command line:

$ secret_provider | cryptsetup fvault2Dump --key-file - "$DEVICE"

Treat secret_provider as a placeholder for an approved secret-management mechanism. Do not replace it with echo 'my-passphrase': that exposes the secret to process inspection, terminal history or logs. If the provider emits a trailing newline, remember that key-file input is byte-oriented.

A regular key file can be selected explicitly:

$ sudo cryptsetup fvault2Dump --key-file /secure/path/DEVICE.key "$DEVICE"

Protect the key file like the passphrase, and remove it using your normal secure secret-retirement process once it is no longer needed. That is an operational change outside this read-only inspection, so do not delete a shared key file just because this example is finished.

5. Bound key-file input when its format requires it

--keyfile-offset skips bytes at the start of a key file.
--keyfile-size, or -l, limits how many bytes are read, useful when a file holds a fixed record or trailing data must not count as part of the secret.

$ sudo cryptsetup fvault2Dump \
    --key-file /secure/path/DEVICE.key \
    --keyfile-offset 0 \
    --keyfile-size KEY_LENGTH \
    "$DEVICE"

Replace KEY_LENGTH with the verified number of bytes, not an estimate; the count starts after the offset. Request more than cryptsetup's compiled-in maximum and the operation aborts, so check cryptsetup --help on this installation for the relevant defaults. A wrong offset or size usually means authentication failure, not proof the device is damaged.

6. Set a finite prompt timeout when appropriate

The interactive passphrase prompt waits forever by default, which is inconvenient for a boot or maintenance script where a stalled process can block later work. Set --timeout, or -t, in seconds when a finite wait is required:

$ sudo cryptsetup fvault2Dump --timeout 30 "$DEVICE"

The timeout applies only to passphrase input from the terminal and has no effect with --key-file. It is not a retry policy and does not make a bad credential valid. If the command exits after the timeout, check the exit status and the surrounding service or script logs.

7. Keep the volume key out of normal output

Warning: do not add --dump-volume-key to an ordinary header inspection. It prints the device volume key in the displayed information, and that key can decrypt the container without its passphrase, so anyone who obtains it may bypass the passphrase entirely.

If a controlled recovery procedure genuinely requires the key, the safer manpage-supported alternative is --volume-key-file PATH, which writes the volume key to a file instead of printing it. This still creates a highly sensitive secret that must be approved, access-controlled, audited and securely retired by your recovery process. Treat accidental exposure as a key compromise: the manpage warns that the device must be erased to prevent further access. Do not run either option for routine diagnosis.

8. Investigate failures without changing the device

Common failures have different meanings:

Missing device or permission error. Points to the path or access controls. Recheck lsblk output and use sudo only once the device identity is established.
Passphrase or key-file failure. Points to the credential bytes, offset or size. Do not respond by trying random devices or destructive recovery commands.
Unrecognised format. The target may not be FVAULT2, the path may be wrong, or the header may be unavailable. Preserve the original media and get specialist advice before writing anything.

For a reproducible diagnostic, add --debug to a failed command and protect the resulting output. Debug lines are prefixed with #. Check for device identifiers, paths and other sensitive data before sharing any logs:

$ sudo cryptsetup fvault2Dump --debug "$DEVICE" > fvault2-dump.out 2> fvault2-dump.err
$ printf 'exit status: %s\n' "$?"
exit status: 1

The status and diagnostic text vary by failure. The output files here are new local files, so remove them through your normal log-retention process once the investigation is complete. The dump itself changes no persistent cryptsetup configuration and has no undo command.

Done means

You confirmed the installed cryptsetup and cryptsetup-bin versions.
You identified the exact FVAULT2-compatible device before invoking the action.
You inspected header information and checked the exit status.
You kept passphrases out of shell history, command arguments and logs.
You left --dump-volume-key disabled unless an approved recovery process required it.
You did not mount, activate, erase, reformat or otherwise write to the device.