↓ Skip to main content
Le Site de François
  1. Index/

fs-verity

Linux Kernel Integrity Filesystem Composefs Ima Android

fs-verity is a Linux kernel filesystem feature, merged in kernel 5.4, that provides read-only, content-addressable integrity verification at the individual file level. When fs-verity is enabled on a file (via the FS_IOC_ENABLE_VERITY ioctl), the kernel builds a Merkle tree of the file’s content blocks and stores it in a filesystem-specific location (in an ext4 or f2fs Merkle tree block range, or in a separate xattr-adjacent structure on btrfs). From that point, the file becomes immutable — writes are rejected — and every page read from the file is verified against the Merkle tree before being returned to userspace. The file’s fs-verity digest is the SHA-256 (or SHA-512) root hash of the Merkle tree, computable without reading the file at all once the tree is built: fsverity digest file returns this digest. A file’s fs-verity digest is a stable, content-derived identity: two files with the same content have the same digest, and any byte-level modification produces a different digest that verification will detect and reject with EIO. The kernel caches verified Merkle tree nodes in the page cache alongside file data, so the amortised verification overhead is low for sequentially-read files.

The operational model differs from dm-verity in scope and granularity. dm-verity protects an entire block device as a unit, with a single root hash committing the whole device; it cannot share blocks between two separately-verified volumes containing the same file. fs-verity protects individual files within a normally-writable filesystem, enabling a mixed-trust model where some files are verified (OS binaries, package contents) and others are not (logs, configuration, state), without partitioning the storage. The file’s Merkle tree is stored alongside the file in the same filesystem, so verified files survive copies and backups that preserve extended attributes and inode metadata. Critically, fs-verity enables content-addressable deduplication at the file level: a storage layout that uses hardlinks or composefs-style object stores can have multiple directory entries pointing to the same verified inode — the Merkle tree is computed once and shared, so the same file content verified in ten different container images costs one Merkle tree’s worth of storage and one verification path. This is the property that composefs depends on: its object store contains each unique file content exactly once, addressed by its fs-verity digest, and multiple composefs mounts (different OS images, different container layers) reference the same object store inodes, each getting fs-verity’s per-read integrity checks for free.

fs-verity integrates with three other systems in this glossary. IMA (Integrity Measurement Architecture) can read a file’s fs-verity digest from the kernel rather than computing a fresh SHA-256 hash on every access — the security.ima extended attribute can store the fs-verity digest as the reference value, and IMA appraisal compares the runtime digest against this stored value without re-reading the entire file, combining the correctness of content-based verification with the performance of an xattr lookup. This is the integrity = ima mode in fapolicyd. Android uses fs-verity for APK verification since Android 10: the Play Store’s application delivery mechanism (adb incremental) uses fs-verity to enable streaming installation — the kernel verifies each page of the APK on first access rather than requiring the entire file to be downloaded and verified before any part of it executes, enabling instant app launch from partial downloads while maintaining the same integrity guarantee as full pre-verification. composefs uses fs-verity as the content integrity layer for the object store backing its EROFS metadata images: when composefs mounts a tree, the verity overlayfs option (kernel 6.6+) instructs the kernel to enforce that each file’s content matches its fs-verity digest as recorded in the EROFS metadata — a single EROFS digest commits the metadata, the metadata commits every file’s fs-verity digest, and the kernel enforces both on every read. The composefs mount therefore achieves the same tamper-evidence property as a dm-verity image while maintaining the object-store sharing and incremental update properties of a file tree.

Related

dm-verity

Linux Kernel Integrity Storage Boot Android Device-Mapper
dm-verity is a Linux device mapper target, available since kernel 3.4, that provides transparent read-only integrity verification for block devices. When a block device is mapped through dm-verity, every data block read from the underlying device is verified against a pre-computed Merkle tree of cryptographic hashes before being returned to the caller — any modification to any block, whether from corruption, bit rot, or deliberate tampering, produces a hash mismatch that dm-verity detects and handles according to its configured error mode. The verification is transparent to the filesystem and applications mounted above it: they read from the dm-verity device as if it were a normal block device, with no awareness that every read is being hash-checked. The security guarantee is that the integrity of the entire block device is committed to by a single root hash — a 32-byte SHA-256 value that covers the entire Merkle tree and therefore the entire data volume. If the root hash is known to be correct (because it was measured into a TPM PCR, embedded in a UKI, or signed by a Secure Boot key), then any verified read from the dm-verity device is guaranteed to return exactly the data that was present when the Merkle tree was computed.

IMA (Integrity Measurement Architecture)

Security Linux Kernel Attestation Tpm Integrity
IMA (Integrity Measurement Architecture) is a Linux kernel subsystem, merged in kernel 2.6.30, that hooks into the kernel’s file access paths — execve(), mmap(), open() — and computes a cryptographic hash of each file’s contents before it is accessed, according to a configurable policy. It is the runtime half of the Linux integrity story: where TPM PCR measurements and Secure Boot cover what was loaded during the boot sequence, IMA covers what happens after the OS is running, hashing executables, libraries, kernel modules, firmware, and configuration files as they are opened, creating a continuously updated record of everything the system has actually used.

composefs

Filesystem Containers Security Linux Integrity Ostree
composefs is a Linux filesystem technology created by Alexander Larsson and Giuseppe Scrivano at Red Hat that provides cryptographically verified, read-only filesystem trees with opportunistic file-level sharing across images. Its motivating problem is a gap that neither dm-verity nor plain overlayfs fills cleanly: dm-verity provides strong integrity over a whole block device but requires a self-contained disk image and cannot share files between images; overlayfs allows layered, shared filesystems but protects only file contents (via fs-verity) and not the directory structure or metadata — an attacker who can manipulate a file’s name, permissions, or position in the tree is not caught. composefs closes that gap by separately protecting content and metadata, then composing them at mount time.