veritysetup

veritysetup command [options] [device] [arguments]
Common commands:
veritysetup format [--data-device=data_dev] [--hash-device=hash_dev] [options]
veritysetup open [--data-device=data_dev] [--hash-device=hash_dev] name hash_root [options]
veritysetup close name

--data-block-size=
    Specifies the block size (in bytes) for the data device. Must be a power of 2.

--hash-block-size=
    Specifies the block size (in bytes) for the hash device. Must be a power of 2.

--hash-algorithm=
    Selects the cryptographic hash algorithm to use (e.g., sha256, sha512).

--salt=
    Provides an optional hexadecimal salt string to be used during hash tree generation.

--data-device=
    Specifies the path to the underlying data block device.

--hash-device=
    Specifies the path to the block device or file where the hash tree will be stored or read from.

--root-hash=
    Specifies the expected root hash in hexadecimal format for opening or verifying the device.

--uuid=
    Assigns a Universal Unique Identifier (UUID) to the verity device.

veritysetup is a utility used to manage dm-verity devices, which provide authenticated integrity checking for block devices. It ensures that the contents of a block device have not been tampered with or corrupted. This is achieved by creating a cryptographic hash tree (a Merkle tree) over the entire data device. Each block's hash is stored in this tree, and a single root hash represents the integrity of the entire device.

When a dm-verity device is opened, the kernel uses the root hash to verify the integrity of data blocks as they are read. If any block's hash does not match the computed hash, an I/O error is reported, preventing the use of corrupt or malicious data. This makes veritysetup crucial for securing system partitions, especially in embedded systems and Android's Verified Boot, where verifying the integrity of the operating system is paramount. It provides a read-only view of the underlying data device.

dm-verity devices provide read-only access to the underlying data; write attempts will result in an I/O error.
The integrity guarantee relies entirely on the security and correctness of the root hash. If the root hash is compromised or incorrectly provided, the integrity check becomes unreliable.
While `veritysetup` ensures data integrity, it does not provide data encryption.

A common workflow involves first using `veritysetup format` on a data device (e.g., a system partition) and storing the resulting root hash securely. Later, to access the device, `veritysetup open` is used with the data device, the hash device, and the securely stored root hash to create a read-only dm-verity mapped device. This mapped device can then be mounted like any other block device.

The functionality of `veritysetup` relies on the Linux kernel's dm-verity module. This module must be loaded or compiled into the kernel for dm-verity devices to be recognized and managed by the operating system.

The dm-verity device mapper target was introduced in the Linux kernel as a core component for ensuring system integrity, notably driven by Android's Verified Boot initiative (since Android 4.4 KitKat). `veritysetup` emerged as the user-space tool within the cryptsetup project to manage these dm-verity devices, providing functionalities like formatting a device with a verity tree and mapping a verity device for read-only access. Its development reflects the growing need for authenticated boot and system integrity verification in various Linux-based environments.

cryptsetup(8), dmsetup(8), lsblk(8), mount(8)