fs-verity Verifies Read-Only Files as They Are Read

A conventional file hash is often checked before a file is trusted. Linux fs-verity moves part of that integrity work into the filesystem. Once verity is enabled for a regular file on a supporting filesystem, the file becomes read-only and its data is checked against a persisted Merkle tree as data is read.

The mechanism has a deliberately narrow boundary. fs-verity can detect data that no longer matches the digest enforced for a verity file. Authenticating that digest against a trusted identity or release policy is a separate decision. The distinction prevents an integrity primitive from being mistaken for a complete software-trust policy.

Enabling verity commits the file to immutable content

Userspace enables the feature with FS_IOC_ENABLE_VERITY. The operation builds the Merkle tree, stores verity metadata in a filesystem-specific location, and marks the file as a verity file. The ioctl requires a read-only file descriptor, while the caller must have write access to the inode and no process may hold the file open for writing.

After successful activation, file contents cannot be written or truncated. The restriction does not give the inode all semantics of the Linux immutable flag. Metadata can still change, and the file can still be renamed, linked, or deleted.

This boundary matters for deployment systems. fs-verity protects the content represented by a particular verity inode; it does not guarantee that a pathname will forever resolve to that inode. A trusted consumer that requires an authenticated artifact must also define how it selects the file and rejects an unprotected replacement.

The digest commits to more than a root hash

File data is divided into blocks and hashed. Hashes are grouped into blocks and hashed again until a Merkle-tree root remains. This structure lets the kernel verify a requested data block using the path from that block toward the root rather than hashing the entire file for every access.

The externally measured value is the fs-verity file digest, not merely the raw Merkle root. Linux computes that digest over a descriptor containing fields such as the file size, hash algorithm, block-size information, salt, and root hash. Binding these parameters avoids ambiguities that a bare tree root would leave.

Userspace can retrieve the enforced digest with FS_IOC_MEASURE_VERITY. The operation does not need to reread the complete file, making the digest suitable as a stable identifier for policy, auditing, or signature verification.

Verification happens on the data path

For page-cache based filesystems, fs-verity verifies data before the corresponding folio is made available as valid page-cache content. This placement covers ordinary reads as well as memory-mapped access instead of protecting only one syscall interface.

If data fails verification, a normal read of the affected region fails with EIO. Access through a memory mapping can raise SIGBUS. Cached data that was already verified does not need the same work again, and verified Merkle-tree blocks can also be cached to reduce repeated tree traversal.

Direct I/O is not allowed to bypass this path. On verity files it falls back to buffered I/O, while DAX is unsupported because direct mapping of persistent storage would circumvent the verification model.

Integrity alone does not establish provenance

An attacker able to replace both an ordinary file and an unauthenticated expected hash can make those two values agree. fs-verity does not remove that trust problem. Its digest needs an authentication source when the security objective includes malicious replacement rather than accidental corruption.

One design is trusted userspace that retrieves the fs-verity digest and checks it against signed release metadata or another authenticated value. Linux integrity frameworks can also consume fs-verity properties. IMA can use fs-verity digests for appraisal, while IPE can make policy decisions using fs-verity digest or signature properties.

Linux also has optional built-in signature support for fs-verity. That facility verifies a signature associated with the file digest using keys available to the kernel. Kernel documentation cautions that this feature alone is not a complete authentication policy: a system still needs policy that requires the relevant files to be protected and authenticated.

The separation is useful. Merkle verification answers whether bytes being read still match the committed file. Authentication policy answers whether that committed file is one the system is prepared to trust.

Content protection does not cover every inode property

The fs-verity digest identifies file contents and the parameters used by the verity construction. It does not generally authenticate mutable inode metadata such as owner, mode, timestamps, or arbitrary extended attributes.

A security design that relies on those properties needs controls for them independently. For example, verifying executable bytes does not prove that surrounding directory permissions, ownership, labels, or pathname resolution have remained in an intended state.

The same scope explains the behavior of copies. The Merkle tree is maintained as filesystem verity metadata rather than exposed as ordinary file content. Copying a verity file through normal file-copy semantics creates a new file containing the bytes, but the destination does not automatically inherit verity state. Deployment tooling must explicitly enable or restore the required protection on the destination.

fs-verity and dm-verity protect different units

Both mechanisms use Merkle-tree verification, but their protected objects differ. dm-verity operates on a read-only block device and is well suited to immutable filesystem images. fs-verity operates on individual files that may reside on a read-write filesystem.

That distinction supports independently updated artifacts. A package manager or application loader can keep a writable filesystem while placing selected executables, packages, or data files under per-file verification. The rest of the filesystem does not become read-only merely because one file uses fs-verity.

The mechanisms can also coexist in a larger trust design. A read-only system image may use dm-verity, while independently installed content on writable storage uses fs-verity plus an authentication policy appropriate to that content.

Filesystem and kernel capability remain part of the contract

fs-verity is a support layer that filesystems integrate with rather than a property available on every mounted filesystem. Current Linux documentation identifies ext4, f2fs, and btrfs as supported filesystems, with filesystem-specific requirements and storage formats for verity metadata.

Applications that depend on the mechanism need to treat successful enablement and measurement as observable security state. A configuration file that requests fs-verity is not evidence that a particular artifact is protected. Errors, unsupported filesystems, incompatible options, and incomplete provisioning must remain visible to the policy layer.

fs-verity is strongest when its claim stays precise: a protected read-only file is bound to an enforced digest, and file data is checked against that commitment as it enters use. Provenance, pathname trust, metadata policy, key trust, and authorization remain separate parts of the system’s security model.