Skip to main content

TECH VEDA

Corporate on-site training - Submit proposal Pick your modulesSharpen your kernel skills: deep dives, drivers, Yocto, CVEs, careers — updated daily. Read the blog →
Tutorials

Building Linux for a RISC-V Board — Part 7: Anchoring the Root Hash

Protect the rootfs with dm-verity on QEMU RISC-V and make the root hash arrive from the signed FIT, not from U-Boot's environment.

Building Linux for a RISC-V Board — Part 7: Anchoring the Root Hash

Parts 4 and 5 made U-Boot refuse a kernel whose signature does not check out, but nothing in that chain looks at the root filesystem. dm-verity closes the gap, and what decides whether it is real protection is where the root hash comes from: U-Boot copies its own bootargs environment variable over /chosen/bootargs in the signed devicetree, so a root hash delivered through the environment is not covered by the signature at all. This part builds the verity device, writes its table by hand, and puts the root hash where the Part 4 signature reaches it.

Part 5 left the board refusing to run a kernel, devicetree or boot script that was not signed with your key. Part 3 gave it an ext4 root filesystem on /dev/vda1. Together they give a board that verifies everything it loads and nothing it mounts. This part protects the root filesystem with dm-verity and spends most of its length on the root hash. Our earlier post on how a read-only rootfs stays verified covers why the root hash needs an anchor; this part builds that anchor on QEMU, where every number can be checked.

What you need before you start

The ~/rv directory as Parts 3 to 5 left it: linux-6.12.111 built, u-boot at v2026.10, opensbi at v1.9, the rootfs tree, and the keys/dev.key and keys/dev.crt pair from Part 4. Two new host packages, cryptsetup-bin for veritysetup and squashfs-tools. Nothing needs sudo.

Every host command runs in ~/rv; => is U-Boot and / # is the guest shell. Host output below is real output from veritysetup 2.7.0, squashfs-tools 4.6.1 and e2fsprogs 1.47.0. U-Boot source is v2026.10 (commit 5508406582f6); kernel source was read at v6.12 and v7.3, identical in both.

What the Part 4 signature does not cover

Part 4 read the protected node list out of the FIT:

raghu@techveda.org:~$ fdtget -t s fit.itb /configurations/conf-1/signature-1 hashed-nodes
/ /configurations/conf-1 /images/kernel /images/kernel/hash-1 /images/fdt /images/fdt/hash-1 /images/script /images/script/hash-1

The root filesystem is not in that list and cannot be, because it is not in the FIT. Rewriting /sbin/init inside the image takes two debugfs commands:

raghu@techveda.org:~$ printf '#!/bin/sh\nexec /bin/sh\n' > evil-init
raghu@techveda.org:~$ sha256sum rootfs.ext4 | cut -c1-16
49d71a82b7f180f8
raghu@techveda.org:~$ debugfs -w -R "rm /sbin/init" rootfs.ext4
raghu@techveda.org:~$ debugfs -w -R "write evil-init /sbin/init" rootfs.ext4
Allocated inode: 21
raghu@techveda.org:~$ sha256sum rootfs.ext4 | cut -c1-16
47d0edf475fd0c62

The filesystem changed; fit.itb did not, so its signature still checks out. U-Boot prints sha256,rsa2048:dev+ OK and the kernel runs an init somebody else wrote.

A disk layout that can hold a verity device

The fix is to record the root hash in the signed FIT, and that forces a layout change. Part 4 kept fit.itb at /boot/fit.itb on partition 1, which is the root filesystem. Writing the root hash into fit.itb would change the bytes that hash covers, changing the hash, changing fit.itb again. No value satisfies both conditions, so the signed artifact has to sit outside the area it protects.

raghu@techveda.org:~$ truncate -s 320M disk.img
raghu@techveda.org:~$ printf 'label: dos
start=1MiB, size=32MiB, type=83, bootable
size=64MiB, type=83
size=8MiB, type=83
' | sfdisk disk.img

Partition 1 holds fit.itb and is read with the same load virtio 0:1 command as before. It needs no verity protection, because U-Boot checks the FIT signature. Partition 2 becomes the verity data device and partition 3 the hash tree, so the kernel sees /dev/vda2 and /dev/vda3. The kernel image leaves the root filesystem, since Part 4 packages Image inside the FIT.

Build a root filesystem whose hash is reproducible

The root hash must be known when you sign the FIT, so it is a build output. If a rebuild of the same sources gives a different root hash, the image and the signed FIT are a matched pair no pipeline can regenerate.

ext4 does not give you that. Two mke2fs runs over one directory, with the UUID fixed by -U, the directory hash seed fixed by -E hash_seed and every file timestamp pinned, differed in exactly two 4 KiB blocks, both inside the inode table:

raghu@techveda.org:~$ cmp -l rootfs.ext4 rootfs2.ext4 | awk '{print int(($1-1)/4096)}' | sort -nu
37
38
raghu@techveda.org:~$ dumpe2fs rootfs.ext4 2>/dev/null | grep 'Inode table'
  Inode table at 37-2084 (+37)

The fields that usually explain this are identical in both images. I did not isolate the one that varies, and claim only the measurement: the images are not byte-identical, and their root hashes differ.

squashfs is reproducible once its two time fields are pinned, and is read-only, which a verity device wants anyway:

raghu@techveda.org:~$ mksquashfs rootfs rootfs.sqfs -noappend -all-root -all-time 1762560000 -mkfs-time 1762560000
raghu@techveda.org:~$ mksquashfs rootfs rootfs2.sqfs -noappend -all-root -all-time 1762560000 -mkfs-time 1762560000
raghu@techveda.org:~$ cmp rootfs.sqfs rootfs2.sqfs && echo identical
identical

Without those options the images differ at byte 9, where the squashfs superblock keeps its creation time. Use squashfs or erofs here, not ext4.

Format the hash tree and read the numbers

Pass --salt. The salt is random by default and is part of the root hash, so two runs on one image otherwise differ.

raghu@techveda.org:~$ veritysetup format --salt=1122334455667788990011223344556677889900112233445566778899001122 rootfs.sqfs verity-hash.img
VERITY header information for verity-hash.img
UUID:                   55901c57-040c-43ea-9be7-5b145c9f957c
Hash type:              1
Data blocks:            6145
Data block size:        4096
Hash blocks:            50
Hash block size:        4096
Hash algorithm:         sha256
Salt:                   1122334455667788990011223344556677889900112233445566778899001122
Root hash:              7aae458090b47b2ad3a6948aca736fe4910826e1a34b55a5b3a679475865e884

The 50 hash blocks are arithmetic you can check. A 4096-byte block holds 128 SHA-256 digests, so 6145 leaves need 49 blocks, and those 49 fit in 1 block above them.

The hash device has 51 blocks, because block 0 is the verity superblock; it held 64 non-zero bytes. Block 1 is the single top-level hash block, and hashing it with the salt in front reproduces the root hash:

raghu@techveda.org:~$ python3 -c 'import hashlib;s=bytes.fromhex("11223344556677889900"*3+"1122");print(hashlib.sha256(s+open("verity-hash.img","rb").read()[4096:8192]).hexdigest())'
7aae458090b47b2ad3a6948aca736fe4910826e1a34b55a5b3a679475865e884

So the root hash is not a hash of the filesystem, but of the one block above the whole tree. That is what lets verification proceed one data block at a time.

Writing the table and handing it to the kernel

The kernel documentation fixes the parameter order as <version> <dev> <hash_dev> <data_block_size> <hash_block_size> <num_data_blocks> <hash_start_block> <algorithm> <digest> <salt>, then an optional argument count and those arguments. Two values are derived: the length is in 512-byte sectors, so 6145 blocks of 4096 bytes is 49160 sectors, and hash_start_block is 1, because of the superblock above. That field is the one that catches people: veritysetup open works the offset out from the superblock, so a hand-written 0 points the kernel at the header instead of the tree and every block fails.

dm-mod.create= creates the device at init time, no initramfs. Its syntax is <name>,<uuid>,<minor>,<flags>,<table>, and drivers/md/dm-init.c is strict:

	/* There are 5 fields: name,uuid,minor,flags,table; */
	char *field[5];
	...
	for (i = 0; i < ARRAY_SIZE(field) - 1; i++) {
		field[i+1] = str_field_delimit(&field[i], ',');
		if (!field[i+1])
			return ERR_PTR(-EINVAL);
	}

All four commas must be present even when uuid and minor are empty, so the name is followed by ,,,. Flags are compared against the literals ro and rw; anything else returns -EINVAL. The target is checked against dm_allowed_targets, which lists crypt, delay, linear, snapshot-origin, striped and verity. DM_MAX_STR_SIZE caps the string at 4096 characters; the line below uses 225.

console=ttyS0 rootwait ro root=/dev/dm-0 dm-mod.create="vroot,,,ro,0 49160 verity 1 /dev/vda2 /dev/vda3 4096 4096 6145 1 sha256 7aae458090b47b2ad3a6948aca736fe4910826e1a34b55a5b3a679475865e884 1122334455667788990011223344556677889900112233445566778899001122 1 restart_on_corruption"

The table contains spaces, so the value is quoted. That works because next_arg() in lib/cmdline.c tracks an in_quote flag, does not end the argument on whitespace inside quotes, and strips the outer quotes. The device appears as /dev/dm-0, rootwait matters as much as in Part 3, and dm-mod.waitfor= is the remedy if the backing device is not ready when dm-init runs.

Where the root hash comes from, and why the environment is the wrong place

Part 4’s boot.cmd set the command line with setenv bootargs 'console=ttyS0 root=/dev/vda1 rootwait rw', so appending the verity table there, root hash and all, looks like the next step. First read what U-Boot does with that variable, in boot/fdt_support.c:

__weak const char *board_fdt_chosen_bootargs(const struct fdt_property *fdt_ba)
{
	return env_get("bootargs");
}

...
	str = board_fdt_chosen_bootargs(fdt_get_property(fdt, nodeoffset,
							 "bootargs", NULL));

	if (str) {
		err = fdt_setprop(fdt, nodeoffset, "bootargs", str,
				  strlen(str) + 1);

The weak default is handed the bootargs property already in the devicetree and ignores it, returning the environment variable instead. When that variable is set, fdt_setprop overwrites /chosen/bootargs in the verified devicetree. A grep of the v2026.10 tree finds no board overriding this function, so it is every board’s behaviour.

Part 4’s arrangement does hold, for a reason easy to lose: the script running setenv is itself a signed image in conf-1, so the command line is as trustworthy as the script. The protection comes from the script being signed, not from the environment being safe. The concrete failure is to set your own command line, carrying your own root hash, then boot the genuine signed FIT:

=> setenv bootargs 'console=ttyS0 rootwait ro root=/dev/dm-0 dm-mod.create="vroot,,,ro,0 49160 verity 1 /dev/vda2 /dev/vda3 4096 4096 6145 1 sha256 <attacker digest> <attacker salt> 0"'
=> bootm ${scriptaddr}#conf-1

Kernel, devicetree and script are untouched and genuinely signed, so verification passes and U-Boot prints the + and OK. The kernel then builds a verity device around the attacker’s root hash, which verifies the attacker’s filesystem perfectly. dm-verity is working as designed; it was given the wrong anchor. On this board CONFIG_ENV_IS_NOWHERE means nothing persists, so that needs console access. With the environment in flash it needs only a write to that partition.

Putting the root hash in the signed devicetree

The fix uses the one helpful property of that weak default: when env_get("bootargs") returns NULL, str is NULL, the if (str) block is skipped and the devicetree’s own value survives. So put the command line in the devicetree source and leave the variable unset.

/dts-v1/;
/ {
	chosen {
		bootargs = "console=ttyS0 rootwait ro root=/dev/dm-0 dm-mod.create=\"vroot,,,ro,0 49160 verity 1 /dev/vda2 /dev/vda3 4096 4096 6145 1 sha256 7aae458090b47b2ad3a6948aca736fe4910826e1a34b55a5b3a679475865e884 1122334455667788990011223344556677889900112233445566778899001122 1 restart_on_corruption\"";
	};
};
raghu@techveda.org:~$ dtc -I dts -O dtb -o chosen.dtb chosen.dts
raghu@techveda.org:~$ fdtget -t s chosen.dtb /chosen bootargs
console=ttyS0 rootwait ro root=/dev/dm-0 dm-mod.create="vroot,,,ro,0 49160 verity 1 /dev/vda2 /dev/vda3 4096 4096 6145 1 sha256 7aae458090b47b2ad3a6948aca736fe4910826e1a34b55a5b3a679475865e884 1122334455667788990011223344556677889900112233445566778899001122 1 restart_on_corruption"

The inner quotes are escaped because a devicetree string property is itself quoted, and the readback confirms they survived. Compile that node into the devicetree Part 4 packages as its fdt image, delete the setenv bootargs line from boot.cmd, and rebuild the FIT otherwise unchanged: conf-1 already names the fdt image, so the signature covers the root hash with no edit to the .its file.

How to check the chain on your own board

Start with the configuration:

raghu@techveda.org:~$ grep -E 'BLK_DEV_DM|DM_INIT|DM_VERITY|SQUASHFS=|CRYPTO_SHA256' linux-6.12.111/.config
CONFIG_BLK_DEV_DM=y
CONFIG_DM_INIT=y
CONFIG_DM_VERITY=y
CONFIG_SQUASHFS=y
CONFIG_CRYPTO_SHA256=y

CONFIG_DM_INIT is declared depends on BLK_DEV_DM=y, so with device-mapper modular the option is not offered and the symptom is a missing menu entry rather than an error. CONFIG_DM_VERITY is a tristate, and =m gives a kernel that builds, boots and cannot mount its own root, for the reason Part 3 gave about virtio-blk. To have the root hash carry its own signature instead, CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG adds the root_hash_sig_key_desc option, checked against the kernel’s trusted keyring.

Then, on the running device:

/ # cat /proc/cmdline
/ # dmsetup status vroot
/ # veritysetup status vroot

dmsetup status ends in V while the device is valid and C once corruption has been seen. A failing block is logged by drivers/md/dm-verity-target.c as %s: %s block %llu is corrupted, so a real failure reads device-mapper: verity: 254:0: data block 1234 is corrupted.

Then compare that command line against the devicetree that was signed: extract the fdt image from the FIT and run fdtget -t s <dtb> /chosen bootargs on it. A difference means something overwrote the signed value. At the U-Boot prompt run printenv bootargs: if it prints anything, that value wins over the devicetree and the root hash in use is not the signed one.

Behind those checks is one test, the same for any verified-boot design. Follow the root hash backwards through every component that touches it and stop only at something a signature already covers. If the trace ends at an environment variable, a writable file, or a value typed at a prompt, there is no anchor.

This material is also covered as a structured programme in TECH VEDA’s training tracks.

Limits, and what was not verified

The machine used here has no device-mapper, so the verity device was never activated and no RISC-V boot was captured.

Run as shown: the veritysetup format listing, both reproducibility comparisons, the cmp and dumpe2fs block numbers, the debugfs edit and its two sha256sum values, the independent recomputation of the root hash, and the dtc and fdtget pair. The root hash and salt above are real values for one test tree; yours will differ, because the root hash is a property of your bytes.

Read from source rather than executed: the dm-verity field order, the dm-mod.create parsing rules, the command-line quoting, the fdt_chosen() behaviour and the configuration dependencies. The failure in the environment section follows from that source and from Part 4’s own boot script; it was not captured in a session.

Two design limits worth stating: restart_on_corruption needs user-space support to avoid a restart loop, and a squashfs root is read-only, so writable state now needs its own partition.

Key takeaways

  • A signed FIT covers only the images its configuration names, so a verified boot can still mount a filesystem someone else wrote. The signed artifact cannot live inside the area its own root hash protects, hence the separate boot partition.
  • Build the verity data with squashfs and pinned -all-time and -mkfs-time, and pass --salt. Otherwise the root hash changes on every rebuild and cannot be signed in advance.
  • In a hand-written table hash_start_block is 1, because block 0 of the hash device is the verity superblock. veritysetup open hides that; dm-mod.create= does not.
  • dm-mod.create= needs all four commas, exactly ro or rw for flags, and a quoted value, since the table contains spaces.
  • U-Boot’s fdt_chosen() overwrites /chosen/bootargs from the bootargs environment variable, so put the root hash in the signed devicetree and leave that variable unset.
Was this worth your time?

Frequently asked questions

Why not simply add the verity table to the existing boot script?
It does work on this board, because the script is one of the signed images in the FIT configuration, so the command line it sets is as trustworthy as the script. But the protection comes from the script being signed, not from the environment being safe, and anything that sets bootargs afterwards silently replaces the root hash.

Why does the root hash change when I rebuild the same root filesystem?
Two reasons, both fixable. veritysetup format generates a random salt unless you pass --salt, and the salt is part of the root hash. Separately, an ext4 image built twice from one directory is not byte-identical even with the UUID and all timestamps pinned, so use squashfs with -all-time and -mkfs-time.

Do I need an initramfs to set up dm-verity before mounting the root?
No. CONFIG_DM_INIT enables the dm-mod.create= kernel parameter, which creates the mapped device at init time, and the root is then given as root=/dev/dm-0. That option depends on BLK_DEV_DM=y, so device-mapper must be built in rather than modular.

Further reading

RB
Raghu Bharadwaj

Founder, TECH VEDA — 20+ years teaching the Linux kernel, device drivers and embedded systems.

Follow on LinkedIn

Get new posts by email

Kernel, embedded Linux and AI-era engineering — a few sharp reads a month. No spam.

We email occasionally and never share your address.