Expand description
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 anfs-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) enablefs-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 theioctl
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.
Structs
- Calculates an fs-verity measurement over the input data.
Enums
- Enum of the supported inner hash algorithms.
Constants
- 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. - Maximum size of digests, as described in the Linux kernel documentation.
- 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 thanusize::MAX
input bytes. - Maximum size of salts, as described in the Linux kernel documentation
Traits
- For trait objects of
FsVerityDigest
, when the inner hash is not statically known
Functions
- Like
FsVerityDigest::new
, but you can choose the hash algorithm at runtime. - Like
FsVerityDigest::new_with_salt
, but you can choose the hash algorithm at runtime. - Like
FsVerityDigest::new_with_salt_and_block_size
, but you can choose the hash algorithm at runtime.
Type Definitions
- Alias for
FsVerityDigest<Sha256>
- Alias for
FsVerityDigest<Sha512>