1.. SPDX-License-Identifier: GPL-2.0 2 3.. _fsverity: 4 5======================================================= 6fs-verity: read-only file-based authenticity protection 7======================================================= 8 9Introduction 10============ 11 12fs-verity (``fs/verity/``) is a support layer that filesystems can 13hook into to support transparent integrity and authenticity protection 14of read-only files. Currently, it is supported by the ext4 and f2fs 15filesystems. Like fscrypt, not too much filesystem-specific code is 16needed to support fs-verity. 17 18fs-verity is similar to `dm-verity 19<https://www.kernel.org/doc/Documentation/device-mapper/verity.txt>`_ 20but works on files rather than block devices. On regular files on 21filesystems supporting fs-verity, userspace can execute an ioctl that 22causes the filesystem to build a Merkle tree for the file and persist 23it to a filesystem-specific location associated with the file. 24 25After this, the file is made readonly, and all reads from the file are 26automatically verified against the file's Merkle tree. Reads of any 27corrupted data, including mmap reads, will fail. 28 29Userspace can use another ioctl to retrieve the root hash (actually 30the "file measurement", which is a hash that includes the root hash) 31that fs-verity is enforcing for the file. This ioctl executes in 32constant time, regardless of the file size. 33 34fs-verity is essentially a way to hash a file in constant time, 35subject to the caveat that reads which would violate the hash will 36fail at runtime. 37 38Use cases 39========= 40 41By itself, the base fs-verity feature only provides integrity 42protection, i.e. detection of accidental (non-malicious) corruption. 43 44However, because fs-verity makes retrieving the file hash extremely 45efficient, it's primarily meant to be used as a tool to support 46authentication (detection of malicious modifications) or auditing 47(logging file hashes before use). 48 49Trusted userspace code (e.g. operating system code running on a 50read-only partition that is itself authenticated by dm-verity) can 51authenticate the contents of an fs-verity file by using the 52`FS_IOC_MEASURE_VERITY`_ ioctl to retrieve its hash, then verifying a 53digital signature of it. 54 55A standard file hash could be used instead of fs-verity. However, 56this is inefficient if the file is large and only a small portion may 57be accessed. This is often the case for Android application package 58(APK) files, for example. These typically contain many translations, 59classes, and other resources that are infrequently or even never 60accessed on a particular device. It would be slow and wasteful to 61read and hash the entire file before starting the application. 62 63Unlike an ahead-of-time hash, fs-verity also re-verifies data each 64time it's paged in. This ensures that malicious disk firmware can't 65undetectably change the contents of the file at runtime. 66 67fs-verity does not replace or obsolete dm-verity. dm-verity should 68still be used on read-only filesystems. fs-verity is for files that 69must live on a read-write filesystem because they are independently 70updated and potentially user-installed, so dm-verity cannot be used. 71 72The base fs-verity feature is a hashing mechanism only; actually 73authenticating the files is up to userspace. However, to meet some 74users' needs, fs-verity optionally supports a simple signature 75verification mechanism where users can configure the kernel to require 76that all fs-verity files be signed by a key loaded into a keyring; see 77`Built-in signature verification`_. Support for fs-verity file hashes 78in IMA (Integrity Measurement Architecture) policies is also planned. 79 80User API 81======== 82 83FS_IOC_ENABLE_VERITY 84-------------------- 85 86The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes 87in a pointer to a :c:type:`struct fsverity_enable_arg`, defined as 88follows:: 89 90 struct fsverity_enable_arg { 91 __u32 version; 92 __u32 hash_algorithm; 93 __u32 block_size; 94 __u32 salt_size; 95 __u64 salt_ptr; 96 __u32 sig_size; 97 __u32 __reserved1; 98 __u64 sig_ptr; 99 __u64 __reserved2[11]; 100 }; 101 102This structure contains the parameters of the Merkle tree to build for 103the file, and optionally contains a signature. It must be initialized 104as follows: 105 106- ``version`` must be 1. 107- ``hash_algorithm`` must be the identifier for the hash algorithm to 108 use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256. See 109 ``include/uapi/linux/fsverity.h`` for the list of possible values. 110- ``block_size`` must be the Merkle tree block size. Currently, this 111 must be equal to the system page size, which is usually 4096 bytes. 112 Other sizes may be supported in the future. This value is not 113 necessarily the same as the filesystem block size. 114- ``salt_size`` is the size of the salt in bytes, or 0 if no salt is 115 provided. The salt is a value that is prepended to every hashed 116 block; it can be used to personalize the hashing for a particular 117 file or device. Currently the maximum salt size is 32 bytes. 118- ``salt_ptr`` is the pointer to the salt, or NULL if no salt is 119 provided. 120- ``sig_size`` is the size of the signature in bytes, or 0 if no 121 signature is provided. Currently the signature is (somewhat 122 arbitrarily) limited to 16128 bytes. See `Built-in signature 123 verification`_ for more information. 124- ``sig_ptr`` is the pointer to the signature, or NULL if no 125 signature is provided. 126- All reserved fields must be zeroed. 127 128FS_IOC_ENABLE_VERITY causes the filesystem to build a Merkle tree for 129the file and persist it to a filesystem-specific location associated 130with the file, then mark the file as a verity file. This ioctl may 131take a long time to execute on large files, and it is interruptible by 132fatal signals. 133 134FS_IOC_ENABLE_VERITY checks for write access to the inode. However, 135it must be executed on an O_RDONLY file descriptor and no processes 136can have the file open for writing. Attempts to open the file for 137writing while this ioctl is executing will fail with ETXTBSY. (This 138is necessary to guarantee that no writable file descriptors will exist 139after verity is enabled, and to guarantee that the file's contents are 140stable while the Merkle tree is being built over it.) 141 142On success, FS_IOC_ENABLE_VERITY returns 0, and the file becomes a 143verity file. On failure (including the case of interruption by a 144fatal signal), no changes are made to the file. 145 146FS_IOC_ENABLE_VERITY can fail with the following errors: 147 148- ``EACCES``: the process does not have write access to the file 149- ``EBADMSG``: the signature is malformed 150- ``EBUSY``: this ioctl is already running on the file 151- ``EEXIST``: the file already has verity enabled 152- ``EFAULT``: the caller provided inaccessible memory 153- ``EINTR``: the operation was interrupted by a fatal signal 154- ``EINVAL``: unsupported version, hash algorithm, or block size; or 155 reserved bits are set; or the file descriptor refers to neither a 156 regular file nor a directory. 157- ``EISDIR``: the file descriptor refers to a directory 158- ``EKEYREJECTED``: the signature doesn't match the file 159- ``EMSGSIZE``: the salt or signature is too long 160- ``ENOKEY``: the fs-verity keyring doesn't contain the certificate 161 needed to verify the signature 162- ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not 163 available in the kernel's crypto API as currently configured (e.g. 164 for SHA-512, missing CONFIG_CRYPTO_SHA512). 165- ``ENOTTY``: this type of filesystem does not implement fs-verity 166- ``EOPNOTSUPP``: the kernel was not configured with fs-verity 167 support; or the filesystem superblock has not had the 'verity' 168 feature enabled on it; or the filesystem does not support fs-verity 169 on this file. (See `Filesystem support`_.) 170- ``EPERM``: the file is append-only; or, a signature is required and 171 one was not provided. 172- ``EROFS``: the filesystem is read-only 173- ``ETXTBSY``: someone has the file open for writing. This can be the 174 caller's file descriptor, another open file descriptor, or the file 175 reference held by a writable memory map. 176 177FS_IOC_MEASURE_VERITY 178--------------------- 179 180The FS_IOC_MEASURE_VERITY ioctl retrieves the measurement of a verity 181file. The file measurement is a digest that cryptographically 182identifies the file contents that are being enforced on reads. 183 184This ioctl takes in a pointer to a variable-length structure:: 185 186 struct fsverity_digest { 187 __u16 digest_algorithm; 188 __u16 digest_size; /* input/output */ 189 __u8 digest[]; 190 }; 191 192``digest_size`` is an input/output field. On input, it must be 193initialized to the number of bytes allocated for the variable-length 194``digest`` field. 195 196On success, 0 is returned and the kernel fills in the structure as 197follows: 198 199- ``digest_algorithm`` will be the hash algorithm used for the file 200 measurement. It will match ``fsverity_enable_arg::hash_algorithm``. 201- ``digest_size`` will be the size of the digest in bytes, e.g. 32 202 for SHA-256. (This can be redundant with ``digest_algorithm``.) 203- ``digest`` will be the actual bytes of the digest. 204 205FS_IOC_MEASURE_VERITY is guaranteed to execute in constant time, 206regardless of the size of the file. 207 208FS_IOC_MEASURE_VERITY can fail with the following errors: 209 210- ``EFAULT``: the caller provided inaccessible memory 211- ``ENODATA``: the file is not a verity file 212- ``ENOTTY``: this type of filesystem does not implement fs-verity 213- ``EOPNOTSUPP``: the kernel was not configured with fs-verity 214 support, or the filesystem superblock has not had the 'verity' 215 feature enabled on it. (See `Filesystem support`_.) 216- ``EOVERFLOW``: the digest is longer than the specified 217 ``digest_size`` bytes. Try providing a larger buffer. 218 219FS_IOC_GETFLAGS 220--------------- 221 222The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity) 223can also be used to check whether a file has fs-verity enabled or not. 224To do so, check for FS_VERITY_FL (0x00100000) in the returned flags. 225 226The verity flag is not settable via FS_IOC_SETFLAGS. You must use 227FS_IOC_ENABLE_VERITY instead, since parameters must be provided. 228 229statx 230----- 231 232Since Linux v5.5, the statx() system call sets STATX_ATTR_VERITY if 233the file has fs-verity enabled. This can perform better than 234FS_IOC_GETFLAGS and FS_IOC_MEASURE_VERITY because it doesn't require 235opening the file, and opening verity files can be expensive. 236 237Accessing verity files 238====================== 239 240Applications can transparently access a verity file just like a 241non-verity one, with the following exceptions: 242 243- Verity files are readonly. They cannot be opened for writing or 244 truncate()d, even if the file mode bits allow it. Attempts to do 245 one of these things will fail with EPERM. However, changes to 246 metadata such as owner, mode, timestamps, and xattrs are still 247 allowed, since these are not measured by fs-verity. Verity files 248 can also still be renamed, deleted, and linked to. 249 250- Direct I/O is not supported on verity files. Attempts to use direct 251 I/O on such files will fall back to buffered I/O. 252 253- DAX (Direct Access) is not supported on verity files, because this 254 would circumvent the data verification. 255 256- Reads of data that doesn't match the verity Merkle tree will fail 257 with EIO (for read()) or SIGBUS (for mmap() reads). 258 259- If the sysctl "fs.verity.require_signatures" is set to 1 and the 260 file's verity measurement is not signed by a key in the fs-verity 261 keyring, then opening the file will fail. See `Built-in signature 262 verification`_. 263 264Direct access to the Merkle tree is not supported. Therefore, if a 265verity file is copied, or is backed up and restored, then it will lose 266its "verity"-ness. fs-verity is primarily meant for files like 267executables that are managed by a package manager. 268 269File measurement computation 270============================ 271 272This section describes how fs-verity hashes the file contents using a 273Merkle tree to produce the "file measurement" which cryptographically 274identifies the file contents. This algorithm is the same for all 275filesystems that support fs-verity. 276 277Userspace only needs to be aware of this algorithm if it needs to 278compute the file measurement itself, e.g. in order to sign the file. 279 280.. _fsverity_merkle_tree: 281 282Merkle tree 283----------- 284 285The file contents is divided into blocks, where the block size is 286configurable but is usually 4096 bytes. The end of the last block is 287zero-padded if needed. Each block is then hashed, producing the first 288level of hashes. Then, the hashes in this first level are grouped 289into 'blocksize'-byte blocks (zero-padding the ends as needed) and 290these blocks are hashed, producing the second level of hashes. This 291proceeds up the tree until only a single block remains. The hash of 292this block is the "Merkle tree root hash". 293 294If the file fits in one block and is nonempty, then the "Merkle tree 295root hash" is simply the hash of the single data block. If the file 296is empty, then the "Merkle tree root hash" is all zeroes. 297 298The "blocks" here are not necessarily the same as "filesystem blocks". 299 300If a salt was specified, then it's zero-padded to the closest multiple 301of the input size of the hash algorithm's compression function, e.g. 30264 bytes for SHA-256 or 128 bytes for SHA-512. The padded salt is 303prepended to every data or Merkle tree block that is hashed. 304 305The purpose of the block padding is to cause every hash to be taken 306over the same amount of data, which simplifies the implementation and 307keeps open more possibilities for hardware acceleration. The purpose 308of the salt padding is to make the salting "free" when the salted hash 309state is precomputed, then imported for each hash. 310 311Example: in the recommended configuration of SHA-256 and 4K blocks, 312128 hash values fit in each block. Thus, each level of the Merkle 313tree is approximately 128 times smaller than the previous, and for 314large files the Merkle tree's size converges to approximately 1/127 of 315the original file size. However, for small files, the padding is 316significant, making the space overhead proportionally more. 317 318.. _fsverity_descriptor: 319 320fs-verity descriptor 321-------------------- 322 323By itself, the Merkle tree root hash is ambiguous. For example, it 324can't a distinguish a large file from a small second file whose data 325is exactly the top-level hash block of the first file. Ambiguities 326also arise from the convention of padding to the next block boundary. 327 328To solve this problem, the verity file measurement is actually 329computed as a hash of the following structure, which contains the 330Merkle tree root hash as well as other fields such as the file size:: 331 332 struct fsverity_descriptor { 333 __u8 version; /* must be 1 */ 334 __u8 hash_algorithm; /* Merkle tree hash algorithm */ 335 __u8 log_blocksize; /* log2 of size of data and tree blocks */ 336 __u8 salt_size; /* size of salt in bytes; 0 if none */ 337 __le32 sig_size; /* must be 0 */ 338 __le64 data_size; /* size of file the Merkle tree is built over */ 339 __u8 root_hash[64]; /* Merkle tree root hash */ 340 __u8 salt[32]; /* salt prepended to each hashed block */ 341 __u8 __reserved[144]; /* must be 0's */ 342 }; 343 344Note that the ``sig_size`` field must be set to 0 for the purpose of 345computing the file measurement, even if a signature was provided (or 346will be provided) to `FS_IOC_ENABLE_VERITY`_. 347 348Built-in signature verification 349=============================== 350 351With CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y, fs-verity supports putting 352a portion of an authentication policy (see `Use cases`_) in the 353kernel. Specifically, it adds support for: 354 3551. At fs-verity module initialization time, a keyring ".fs-verity" is 356 created. The root user can add trusted X.509 certificates to this 357 keyring using the add_key() system call, then (when done) 358 optionally use keyctl_restrict_keyring() to prevent additional 359 certificates from being added. 360 3612. `FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted 362 detached signature in DER format of the file measurement. On 363 success, this signature is persisted alongside the Merkle tree. 364 Then, any time the file is opened, the kernel will verify the 365 file's actual measurement against this signature, using the 366 certificates in the ".fs-verity" keyring. 367 3683. A new sysctl "fs.verity.require_signatures" is made available. 369 When set to 1, the kernel requires that all verity files have a 370 correctly signed file measurement as described in (2). 371 372File measurements must be signed in the following format, which is 373similar to the structure used by `FS_IOC_MEASURE_VERITY`_:: 374 375 struct fsverity_signed_digest { 376 char magic[8]; /* must be "FSVerity" */ 377 __le16 digest_algorithm; 378 __le16 digest_size; 379 __u8 digest[]; 380 }; 381 382fs-verity's built-in signature verification support is meant as a 383relatively simple mechanism that can be used to provide some level of 384authenticity protection for verity files, as an alternative to doing 385the signature verification in userspace or using IMA-appraisal. 386However, with this mechanism, userspace programs still need to check 387that the verity bit is set, and there is no protection against verity 388files being swapped around. 389 390Filesystem support 391================== 392 393fs-verity is currently supported by the ext4 and f2fs filesystems. 394The CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity 395on either filesystem. 396 397``include/linux/fsverity.h`` declares the interface between the 398``fs/verity/`` support layer and filesystems. Briefly, filesystems 399must provide an ``fsverity_operations`` structure that provides 400methods to read and write the verity metadata to a filesystem-specific 401location, including the Merkle tree blocks and 402``fsverity_descriptor``. Filesystems must also call functions in 403``fs/verity/`` at certain times, such as when a file is opened or when 404pages have been read into the pagecache. (See `Verifying data`_.) 405 406ext4 407---- 408 409ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2. 410 411To create verity files on an ext4 filesystem, the filesystem must have 412been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on 413it. "verity" is an RO_COMPAT filesystem feature, so once set, old 414kernels will only be able to mount the filesystem readonly, and old 415versions of e2fsck will be unable to check the filesystem. Moreover, 416currently ext4 only supports mounting a filesystem with the "verity" 417feature when its block size is equal to PAGE_SIZE (often 4096 bytes). 418 419ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It 420can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared. 421 422ext4 also supports encryption, which can be used simultaneously with 423fs-verity. In this case, the plaintext data is verified rather than 424the ciphertext. This is necessary in order to make the file 425measurement meaningful, since every file is encrypted differently. 426 427ext4 stores the verity metadata (Merkle tree and fsverity_descriptor) 428past the end of the file, starting at the first 64K boundary beyond 429i_size. This approach works because (a) verity files are readonly, 430and (b) pages fully beyond i_size aren't visible to userspace but can 431be read/written internally by ext4 with only some relatively small 432changes to ext4. This approach avoids having to depend on the 433EA_INODE feature and on rearchitecturing ext4's xattr support to 434support paging multi-gigabyte xattrs into memory, and to support 435encrypting xattrs. Note that the verity metadata *must* be encrypted 436when the file is, since it contains hashes of the plaintext data. 437 438Currently, ext4 verity only supports the case where the Merkle tree 439block size, filesystem block size, and page size are all the same. It 440also only supports extent-based files. 441 442f2fs 443---- 444 445f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0. 446 447To create verity files on an f2fs filesystem, the filesystem must have 448been formatted with ``-O verity``. 449 450f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files. 451It can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be 452cleared. 453 454Like ext4, f2fs stores the verity metadata (Merkle tree and 455fsverity_descriptor) past the end of the file, starting at the first 45664K boundary beyond i_size. See explanation for ext4 above. 457Moreover, f2fs supports at most 4096 bytes of xattr entries per inode 458which wouldn't be enough for even a single Merkle tree block. 459 460Currently, f2fs verity only supports a Merkle tree block size of 4096. 461Also, f2fs doesn't support enabling verity on files that currently 462have atomic or volatile writes pending. 463 464Implementation details 465====================== 466 467Verifying data 468-------------- 469 470fs-verity ensures that all reads of a verity file's data are verified, 471regardless of which syscall is used to do the read (e.g. mmap(), 472read(), pread()) and regardless of whether it's the first read or a 473later read (unless the later read can return cached data that was 474already verified). Below, we describe how filesystems implement this. 475 476Pagecache 477~~~~~~~~~ 478 479For filesystems using Linux's pagecache, the ``->readpage()`` and 480``->readpages()`` methods must be modified to verify pages before they 481are marked Uptodate. Merely hooking ``->read_iter()`` would be 482insufficient, since ``->read_iter()`` is not used for memory maps. 483 484Therefore, fs/verity/ provides a function fsverity_verify_page() which 485verifies a page that has been read into the pagecache of a verity 486inode, but is still locked and not Uptodate, so it's not yet readable 487by userspace. As needed to do the verification, 488fsverity_verify_page() will call back into the filesystem to read 489Merkle tree pages via fsverity_operations::read_merkle_tree_page(). 490 491fsverity_verify_page() returns false if verification failed; in this 492case, the filesystem must not set the page Uptodate. Following this, 493as per the usual Linux pagecache behavior, attempts by userspace to 494read() from the part of the file containing the page will fail with 495EIO, and accesses to the page within a memory map will raise SIGBUS. 496 497fsverity_verify_page() currently only supports the case where the 498Merkle tree block size is equal to PAGE_SIZE (often 4096 bytes). 499 500In principle, fsverity_verify_page() verifies the entire path in the 501Merkle tree from the data page to the root hash. However, for 502efficiency the filesystem may cache the hash pages. Therefore, 503fsverity_verify_page() only ascends the tree reading hash pages until 504an already-verified hash page is seen, as indicated by the PageChecked 505bit being set. It then verifies the path to that page. 506 507This optimization, which is also used by dm-verity, results in 508excellent sequential read performance. This is because usually (e.g. 509127 in 128 times for 4K blocks and SHA-256) the hash page from the 510bottom level of the tree will already be cached and checked from 511reading a previous data page. However, random reads perform worse. 512 513Block device based filesystems 514~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 515 516Block device based filesystems (e.g. ext4 and f2fs) in Linux also use 517the pagecache, so the above subsection applies too. However, they 518also usually read many pages from a file at once, grouped into a 519structure called a "bio". To make it easier for these types of 520filesystems to support fs-verity, fs/verity/ also provides a function 521fsverity_verify_bio() which verifies all pages in a bio. 522 523ext4 and f2fs also support encryption. If a verity file is also 524encrypted, the pages must be decrypted before being verified. To 525support this, these filesystems allocate a "post-read context" for 526each bio and store it in ``->bi_private``:: 527 528 struct bio_post_read_ctx { 529 struct bio *bio; 530 struct work_struct work; 531 unsigned int cur_step; 532 unsigned int enabled_steps; 533 }; 534 535``enabled_steps`` is a bitmask that specifies whether decryption, 536verity, or both is enabled. After the bio completes, for each needed 537postprocessing step the filesystem enqueues the bio_post_read_ctx on a 538workqueue, and then the workqueue work does the decryption or 539verification. Finally, pages where no decryption or verity error 540occurred are marked Uptodate, and the pages are unlocked. 541 542Files on ext4 and f2fs may contain holes. Normally, ``->readpages()`` 543simply zeroes holes and sets the corresponding pages Uptodate; no bios 544are issued. To prevent this case from bypassing fs-verity, these 545filesystems use fsverity_verify_page() to verify hole pages. 546 547ext4 and f2fs disable direct I/O on verity files, since otherwise 548direct I/O would bypass fs-verity. (They also do the same for 549encrypted files.) 550 551Userspace utility 552================= 553 554This document focuses on the kernel, but a userspace utility for 555fs-verity can be found at: 556 557 https://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/fsverity-utils.git 558 559See the README.md file in the fsverity-utils source tree for details, 560including examples of setting up fs-verity protected files. 561 562Tests 563===== 564 565To test fs-verity, use xfstests. For example, using `kvm-xfstests 566<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: 567 568 kvm-xfstests -c ext4,f2fs -g verity 569 570FAQ 571=== 572 573This section answers frequently asked questions about fs-verity that 574weren't already directly answered in other parts of this document. 575 576:Q: Why isn't fs-verity part of IMA? 577:A: fs-verity and IMA (Integrity Measurement Architecture) have 578 different focuses. fs-verity is a filesystem-level mechanism for 579 hashing individual files using a Merkle tree. In contrast, IMA 580 specifies a system-wide policy that specifies which files are 581 hashed and what to do with those hashes, such as log them, 582 authenticate them, or add them to a measurement list. 583 584 IMA is planned to support the fs-verity hashing mechanism as an 585 alternative to doing full file hashes, for people who want the 586 performance and security benefits of the Merkle tree based hash. 587 But it doesn't make sense to force all uses of fs-verity to be 588 through IMA. As a standalone filesystem feature, fs-verity 589 already meets many users' needs, and it's testable like other 590 filesystem features e.g. with xfstests. 591 592:Q: Isn't fs-verity useless because the attacker can just modify the 593 hashes in the Merkle tree, which is stored on-disk? 594:A: To verify the authenticity of an fs-verity file you must verify 595 the authenticity of the "file measurement", which is basically the 596 root hash of the Merkle tree. See `Use cases`_. 597 598:Q: Isn't fs-verity useless because the attacker can just replace a 599 verity file with a non-verity one? 600:A: See `Use cases`_. In the initial use case, it's really trusted 601 userspace code that authenticates the files; fs-verity is just a 602 tool to do this job efficiently and securely. The trusted 603 userspace code will consider non-verity files to be inauthentic. 604 605:Q: Why does the Merkle tree need to be stored on-disk? Couldn't you 606 store just the root hash? 607:A: If the Merkle tree wasn't stored on-disk, then you'd have to 608 compute the entire tree when the file is first accessed, even if 609 just one byte is being read. This is a fundamental consequence of 610 how Merkle tree hashing works. To verify a leaf node, you need to 611 verify the whole path to the root hash, including the root node 612 (the thing which the root hash is a hash of). But if the root 613 node isn't stored on-disk, you have to compute it by hashing its 614 children, and so on until you've actually hashed the entire file. 615 616 That defeats most of the point of doing a Merkle tree-based hash, 617 since if you have to hash the whole file ahead of time anyway, 618 then you could simply do sha256(file) instead. That would be much 619 simpler, and a bit faster too. 620 621 It's true that an in-memory Merkle tree could still provide the 622 advantage of verification on every read rather than just on the 623 first read. However, it would be inefficient because every time a 624 hash page gets evicted (you can't pin the entire Merkle tree into 625 memory, since it may be very large), in order to restore it you 626 again need to hash everything below it in the tree. This again 627 defeats most of the point of doing a Merkle tree-based hash, since 628 a single block read could trigger re-hashing gigabytes of data. 629 630:Q: But couldn't you store just the leaf nodes and compute the rest? 631:A: See previous answer; this really just moves up one level, since 632 one could alternatively interpret the data blocks as being the 633 leaf nodes of the Merkle tree. It's true that the tree can be 634 computed much faster if the leaf level is stored rather than just 635 the data, but that's only because each level is less than 1% the 636 size of the level below (assuming the recommended settings of 637 SHA-256 and 4K blocks). For the exact same reason, by storing 638 "just the leaf nodes" you'd already be storing over 99% of the 639 tree, so you might as well simply store the whole tree. 640 641:Q: Can the Merkle tree be built ahead of time, e.g. distributed as 642 part of a package that is installed to many computers? 643:A: This isn't currently supported. It was part of the original 644 design, but was removed to simplify the kernel UAPI and because it 645 wasn't a critical use case. Files are usually installed once and 646 used many times, and cryptographic hashing is somewhat fast on 647 most modern processors. 648 649:Q: Why doesn't fs-verity support writes? 650:A: Write support would be very difficult and would require a 651 completely different design, so it's well outside the scope of 652 fs-verity. Write support would require: 653 654 - A way to maintain consistency between the data and hashes, 655 including all levels of hashes, since corruption after a crash 656 (especially of potentially the entire file!) is unacceptable. 657 The main options for solving this are data journalling, 658 copy-on-write, and log-structured volume. But it's very hard to 659 retrofit existing filesystems with new consistency mechanisms. 660 Data journalling is available on ext4, but is very slow. 661 662 - Rebuilding the the Merkle tree after every write, which would be 663 extremely inefficient. Alternatively, a different authenticated 664 dictionary structure such as an "authenticated skiplist" could 665 be used. However, this would be far more complex. 666 667 Compare it to dm-verity vs. dm-integrity. dm-verity is very 668 simple: the kernel just verifies read-only data against a 669 read-only Merkle tree. In contrast, dm-integrity supports writes 670 but is slow, is much more complex, and doesn't actually support 671 full-device authentication since it authenticates each sector 672 independently, i.e. there is no "root hash". It doesn't really 673 make sense for the same device-mapper target to support these two 674 very different cases; the same applies to fs-verity. 675 676:Q: Since verity files are immutable, why isn't the immutable bit set? 677:A: The existing "immutable" bit (FS_IMMUTABLE_FL) already has a 678 specific set of semantics which not only make the file contents 679 read-only, but also prevent the file from being deleted, renamed, 680 linked to, or having its owner or mode changed. These extra 681 properties are unwanted for fs-verity, so reusing the immutable 682 bit isn't appropriate. 683 684:Q: Why does the API use ioctls instead of setxattr() and getxattr()? 685:A: Abusing the xattr interface for basically arbitrary syscalls is 686 heavily frowned upon by most of the Linux filesystem developers. 687 An xattr should really just be an xattr on-disk, not an API to 688 e.g. magically trigger construction of a Merkle tree. 689 690:Q: Does fs-verity support remote filesystems? 691:A: Only ext4 and f2fs support is implemented currently, but in 692 principle any filesystem that can store per-file verity metadata 693 can support fs-verity, regardless of whether it's local or remote. 694 Some filesystems may have fewer options of where to store the 695 verity metadata; one possibility is to store it past the end of 696 the file and "hide" it from userspace by manipulating i_size. The 697 data verification functions provided by ``fs/verity/`` also assume 698 that the filesystem uses the Linux pagecache, but both local and 699 remote filesystems normally do so. 700 701:Q: Why is anything filesystem-specific at all? Shouldn't fs-verity 702 be implemented entirely at the VFS level? 703:A: There are many reasons why this is not possible or would be very 704 difficult, including the following: 705 706 - To prevent bypassing verification, pages must not be marked 707 Uptodate until they've been verified. Currently, each 708 filesystem is responsible for marking pages Uptodate via 709 ``->readpages()``. Therefore, currently it's not possible for 710 the VFS to do the verification on its own. Changing this would 711 require significant changes to the VFS and all filesystems. 712 713 - It would require defining a filesystem-independent way to store 714 the verity metadata. Extended attributes don't work for this 715 because (a) the Merkle tree may be gigabytes, but many 716 filesystems assume that all xattrs fit into a single 4K 717 filesystem block, and (b) ext4 and f2fs encryption doesn't 718 encrypt xattrs, yet the Merkle tree *must* be encrypted when the 719 file contents are, because it stores hashes of the plaintext 720 file contents. 721 722 So the verity metadata would have to be stored in an actual 723 file. Using a separate file would be very ugly, since the 724 metadata is fundamentally part of the file to be protected, and 725 it could cause problems where users could delete the real file 726 but not the metadata file or vice versa. On the other hand, 727 having it be in the same file would break applications unless 728 filesystems' notion of i_size were divorced from the VFS's, 729 which would be complex and require changes to all filesystems. 730 731 - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's 732 transaction mechanism so that either the file ends up with 733 verity enabled, or no changes were made. Allowing intermediate 734 states to occur after a crash may cause problems. 735