Build and Verify a dm-verity Image with veritysetup

You will create a disposable data image and its dm-verity hash image, save the trusted root hash, and verify the pair without creating a kernel mapping. The same workflow applies to real read-only data devices, but the examples below are deliberately confined to files that can be thrown away.

This guide uses veritysetup 2.7.0 from cryptsetup-bin 2:2.7.0-1ubuntu4.2. Allow about fifteen minutes. You need a shell, enough space for two small files, and a data image whose contents will not change while you test it. Formatting writes verification metadata to the hash device, so do not point these examples at a disk containing useful data.

1. Check the installed defaults

Start with read-only commands. They need no elevated privileges:

$ veritysetup --version
veritysetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ veritysetup --help | tail -n 5
        Hash: sha256, Data block (bytes): 4096, Hash block (bytes): 4096, Salt size: 32, Hash format: 1

Those are the compiled-in defaults on this installation: SHA-256, 4096-byte data and hash blocks, a 32-byte salt, and format 1. The help output is the right place to confirm defaults after an upgrade. A format operation can override several of them, but the matching values must be supplied again when using --no-superblock.

2. Create a disposable test image

Choose a private temporary directory and create exactly 1 MiB of data. This is an ordinary file operation, not an elevated command:

$ WORKDIR=$(mktemp -d /tmp/veritysetup-demo.XXXXXX)
$ truncate -s 1M "$WORKDIR/data.img"
$ ls -l "$WORKDIR/data.img"
-rw-r--r-- 1 ... 1048576 ... data.img

Keep data.img unchanged after formatting. dm-verity is read-only and detects later changes, rather than keeping a writable copy in step with the hash tree.

3. Format the hash image and save the root hash

Formatting calculates the verification tree and stores it in the hash image. If the hash path does not exist, veritysetup creates it. The root hash file contains hexadecimal text and, with this command, has no terminating newline:

$ veritysetup format \
    --root-hash-file "$WORKDIR/root.hash" \
    "$WORKDIR/data.img" "$WORKDIR/hash.img"
VERITY header information for .../hash.img
UUID:             ...
Hash type:        1
Data blocks:      256
Data block size:  4096
Hash blocks:      3
Hash block size:  4096
Hash algorithm:   sha256
Salt:             ...
Root hash:        ...
Hash device size: 16384 [bytes]
$ wc -c "$WORKDIR/root.hash"
64 .../root.hash

The UUID, salt, and root hash are generated values, so your output will differ. Protect the root hash from accidental replacement. For a real image, publish or store it separately from an untrusted data-and-hash bundle. Formatting is not encryption and does not prove that the original data was trustworthy.

4. Inspect the stored metadata

Use dump to read the on-disk superblock without activating a device:

$ veritysetup dump "$WORKDIR/hash.img"
VERITY header information for .../hash.img
UUID:             ...
Hash type:        1
Data blocks:      256
Data block size:  4096
Hash blocks:      3
Hash block size:  4096
Hash algorithm:   sha256
Salt:             ...
Hash device size: 16384 [bytes]

Compare the data-block count, block sizes, algorithm, and salt with the values recorded during provisioning. dump does not replace the root hash as a trust decision; it only reports metadata from the hash device.

5. Verify without creating a mapping

Use verify for a userspace check. It reads the data and hash devices but does not create a device under /dev/mapper:

$ veritysetup verify \
    --root-hash-file "$WORKDIR/root.hash" \
    "$WORKDIR/data.img" "$WORKDIR/hash.img"
$ printf 'verify exit: %s\n' "$?"
verify exit: 0

Exit status 0 means the data matched the supplied root hash. A non-zero status means the check failed or the arguments were wrong. Do not replace the root hash with a value copied from an untrusted error report. If you use inline syntax instead, the equivalent final argument is a hexadecimal root hash: veritysetup verify DATA HASH ROOT_HASH.

6. Activate a read-only mapping when you need one

# veritysetup open \
    --root-hash-file /path/to/root.hash \
    /dev/EXAMPLE_DATA verity-demo /dev/EXAMPLE_HASH
# veritysetup status verity-demo
# ls -l /dev/mapper/verity-demo

The mapping is always read-only. With a superblock, the stored parameters are read from the hash device. With --no-superblock, repeat the format-time options such as --data-block-size, --hash-block-size, --data-blocks, --hash-offset, --hash, and --salt; omitting one can make the mapping invalid or verify the wrong layout.

When finished, remove the mapping. This is the undo operation and normally also requires root:

# veritysetup close verity-demo
# test ! -e /dev/mapper/verity-demo && echo 'mapping closed'
mapping closed

If close reports that the device is busy, stop readers first. --deferred can postpone removal until the last user closes it, but that changes when the mapping disappears and should be used only when that behaviour is intentional.

7. Avoid weakening the integrity check

By default, a detected corruption makes the kernel I/O fail. --ignore-corruption logs the event and continues, which can expose data that failed verification. --restart-on-corruption and --panic-on-corruption can reboot or panic the kernel, so they need an explicit recovery design rather than casual troubleshooting.

Likewise, --check-at-most-once verifies a data block only on its first read. The manpage warns that this reduces security because later online tampering is not detected. Leave it out unless you have measured the trade-off and can explain why it is acceptable. FEC options can recover certain corruptions, but their device, offsets, roots, block sizes, and image layout must match the format operation.