Inspect a LUKS Header Safely with cryptsetup luksDump

You will identify the installed cryptsetup version, inspect a LUKS header without opening the encrypted device, and optionally extract LUKS2 JSON metadata for a script or audit. The normal workflow is read-only. Do not use the volume-key options unless you have a documented reason and a protected destination.

These examples target cryptsetup 2.7.0, the version installed on this machine. Allow about ten minutes. You need a shell and read access to the LUKS device or detached header. A real block device may require sudo; the command itself does not always need elevated privileges.

1. Confirm the command and version

Start with ordinary, read-only checks. They do not need elevated privileges:

$ 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

Your package revision can differ even when the upstream cryptsetup version matches. Keep that distinction in notes when comparing output between hosts.

2. Dump the ordinary header information

Replace /dev/DEVICE with the LUKS device you intend to inspect. Do not guess a device name. Confirm it first with a separate inventory command such as lsblk -f. Reading a header does not unlock the data or mount a filesystem.

$ sudo cryptsetup luksDump /dev/DEVICE
LUKS header information
Version:        2
Epoch:          3
Metadata area:  16384 [bytes]
Keyslots area:  16744448 [bytes]
UUID:           01234567-89ab-cdef-0123-456789abcdef
Label:          (no label)
Subsystem:      (no subsystem)
Flags:          (no flags)

Data segments:
  0: crypt
        offset: 16777216 [bytes]
        length: (whole device)

Keyslots:
  0: luks2
        Key:        512 bits
        Priority:   normal

Tokens:
Digests:

The UUID and the number and contents of keyslots are device-specific. A LUKS2 header normally shows metadata, data segments, keyslots, tokens and digests. LUKS1 output has a different layout. Empty sections are not necessarily an error.

luksDump does not require a passphrase for this ordinary header view. If access fails, check the path, permissions and whether the target really contains a LUKS header. Adding sudo cannot turn a non-LUKS file into a valid device.

3. Handle a detached header

Some installations keep encrypted data and the LUKS header separately. In that case, pass the data device as the positional argument and point --header at the detached metadata device or file:

$ sudo cryptsetup luksDump --header /path/to/detached-header /dev/DEVICE

The header path must identify the header that belongs to the data device. A mismatched header can produce an error or misleading inspection results. Treat detached headers as security-sensitive inventory: protect their permissions and do not copy them into a public ticket or paste site.

For a detached header stored on a device rather than a file, use its explicit device path. If you are unsure which path contains the metadata, stop and consult the storage record instead of probing disks with write-capable commands.

4. Export LUKS2 JSON metadata

For LUKS2, --dump-json-metadata prints the JSON metadata area rather than the normal human-readable header. It does not include basic fields such as the UUID, so keep the ordinary dump as well when you need a complete record:

$ sudo cryptsetup luksDump --dump-json-metadata /dev/DEVICE
{
  "keyslots":{
    "0":{
      "type":"luks2",
      "key_size":64,
      "kdf":{
        "type":"argon2id"
      }
    }
  },
  "tokens":{},
  "segments":{
    "0":{
      "type":"crypt",
      "offset":"16777216"
    }
  }
}

Real output includes salts, digests, offsets and other values that vary by device. Store the output with the same care as other encryption metadata. JSON is useful for a controlled audit or parser, but do not assume that a field is stable across cryptsetup releases without checking the installed version.

5. Avoid dumping the volume key

Do not add --dump-volume-key to a routine inventory command. It asks for a passphrase and exposes the LUKS volume key, either on standard output or in a file selected with --volume-key-file. Anyone holding that key can decrypt the container without the passphrase and potentially without the LUKS header. A compromised volume key requires erasing or reencryption to prevent further access.

If a controlled recovery procedure genuinely requires the key, use a protected temporary location, restrict access before writing, and record how the file will be destroyed. For example, the following is deliberately a pattern, not a command to paste unchanged:

$ sudo install -m 600 /dev/null /secure/recovery/volume.key
$ sudo cryptsetup luksDump --dump-volume-key \
    --key-file /secure/recovery/passphrase \
    --volume-key-file /secure/recovery/volume.key \
    /dev/DEVICE
Key stored to file /secure/recovery/volume.key.

Do not use --key-file - casually with this option. The manpage warns that standard input suppresses the validation question and warning. After the approved recovery task, follow your organisation's secure destruction procedure for both the passphrase and the volume-key file. There is no cryptsetup undo command for a key that has already been copied.

6. Diagnose without changing metadata

For a failed read, first retry the exact command with --debug if the diagnostic is safe to record. Debug lines begin with # and can contain paths, device details and plugin information, so review them before sharing:

$ sudo cryptsetup --debug luksDump /dev/DEVICE
# cryptsetup 2.7.0 processing "luksDump"
... diagnostic lines ...
LUKS header information

Use --type luks1 or --type luks2 only when you have a reason to require that format. Otherwise, cryptsetup can detect the LUKS type. The --timeout option only affects terminal passphrase input and has no effect with --key-file; it is usually irrelevant to a normal header dump.

Do not use --disable-locks as a general troubleshooting switch. It is intended for restricted environments where locking cannot work, is valid only for LUKS2 and weakens metadata protection. Fix the environment or obtain an explicit operational decision before using it.