Crate fs_verity

This crate implements utilities for working with fs-verity functionality of the Linux kernel.

What is fs-verity?

This allows you to make a file permanently immutable and have the kernel calculate and store a Merkle tree hash for the file that will be instantly retrievable from that point on. The kernel will also refuse to load any part of the file into memory unless it matches the corresponding parts of the Merkle tree, meaning as long as you trust the kernel the fs-verity measurement returned for a file will always match the data you read from that file. This means that even if the filesystem was tampered with while the system was off, the file contents cannot be changed without also changing or removing the verity hash, or causing reads from the file to fail.

TLDR: It allows you to make a file immutable and allows you to instantly get a reliable hash for that file at any time.

What is this crate?

You can think of it as a pure Rust replacement for the main parts of libfsverity.

It consists of two parts:

• An implementation of sha2::digest::Digest which can calculate an fs-verity measurement in userland Rust code. This is useful for e.g. servers and build systems which may not want to (or be able to) enable fs-verity for files, but still need to know the digest values so they can be used to create e.g. a signed manifest file containing all the digests.
• On Linux systems, two functions which allow you to enable fs-verity for a file, and to fetch the digest for the file from the kernel once it’s enabled. This uses the ioctl interface directly.

This was mostly produced as a coding exercise. It works and is pretty clean (well, as much as is possible under the API constraints I set myself) and thoroughly commented, but it is currently a bit slower than the C implementation because that uses libcrypto’s assembly code for SHA256, and the SHA256 implementation in RustCrypto is not quite as fast.

One neat aspect of this implementation is that it works in a completely streaming manner, accepting any amount of input in chunks of whatever size.

Modules

linux

Functions to enable fs-verity on a file and to return its hash.

Structs

FsVerityDigest

Calculates an fs-verity measurement over the input data.

Enums

InnerHashAlgorithm

Enum of the supported inner hash algorithms.

Constants

DEFAULT_BLOCK_SIZE

Currently the kernel requires the fs-verity block size to be equal to the system page size, which is usually 4096. Some modern 64 bit ARM systems have a 64kB page size though.

MAX_DIGEST_SIZE

Maximum size of digests, as described in the Linux kernel documentation.

MAX_LEVELS

Linux has a hardcoded limit of 8, see FS_VERITY_MAX_LEVELS in /fs/verity/fsverity_private.h in the Linux source. In reality you are not likely to hit this limit ever, e.g. with SHA256 you’d need more than usize::MAX input bytes.

MAX_SALT_SIZE

Maximum size of salts, as described in the Linux kernel documentation

Traits

DynFsVerityDigest

For trait objects of FsVerityDigest, when the inner hash is not statically known

InnerHash

Trait for the inner hash algorithms we support (currently implemented for Sha256 and Sha512).

Functions

new_dyn

Like FsVerityDigest::new, but you can choose the hash algorithm at runtime.

new_dyn_with_salt

Like FsVerityDigest::new_with_salt, but you can choose the hash algorithm at runtime.

new_dyn_with_salt_and_block_size

Like FsVerityDigest::new_with_salt_and_block_size, but you can choose the hash algorithm at runtime.

Type Aliases

FsVeritySha256

Alias for FsVerityDigest<Sha256>

FsVeritySha512

Alias for FsVerityDigest<Sha512>