1 .. SPDX-License-Identifier: GPL-2.0
2
3 .. _fsverity:
4
5 ==============================================
6 fs-verity: read-only file-based authenticity p
7 ==============================================
8
9 Introduction
10 ============
11
12 fs-verity (``fs/verity/``) is a support layer
13 hook into to support transparent integrity and
14 of read-only files. Currently, it is supporte
15 btrfs filesystems. Like fscrypt, not too much
16 code is needed to support fs-verity.
17
18 fs-verity is similar to `dm-verity
19 <https://www.kernel.org/doc/Documentation/devi
20 but works on files rather than block devices.
21 filesystems supporting fs-verity, userspace ca
22 causes the filesystem to build a Merkle tree f
23 it to a filesystem-specific location associate
24
25 After this, the file is made readonly, and all
26 automatically verified against the file's Merk
27 corrupted data, including mmap reads, will fai
28
29 Userspace can use another ioctl to retrieve th
30 the "fs-verity file digest", which is a hash t
31 tree root hash) that fs-verity is enforcing fo
32 executes in constant time, regardless of the f
33
34 fs-verity is essentially a way to hash a file
35 subject to the caveat that reads which would v
36 fail at runtime.
37
38 Use cases
39 =========
40
41 By itself, fs-verity only provides integrity p
42 detection of accidental (non-malicious) corrup
43
44 However, because fs-verity makes retrieving th
45 efficient, it's primarily meant to be used as
46 authentication (detection of malicious modific
47 (logging file hashes before use).
48
49 A standard file hash could be used instead of
50 this is inefficient if the file is large and o
51 be accessed. This is often the case for Andro
52 (APK) files, for example. These typically con
53 classes, and other resources that are infreque
54 accessed on a particular device. It would be
55 read and hash the entire file before starting
56
57 Unlike an ahead-of-time hash, fs-verity also r
58 time it's paged in. This ensures that malicio
59 undetectably change the contents of the file a
60
61 fs-verity does not replace or obsolete dm-veri
62 still be used on read-only filesystems. fs-ve
63 must live on a read-write filesystem because t
64 updated and potentially user-installed, so dm-
65
66 fs-verity does not mandate a particular scheme
67 file hashes. (Similarly, dm-verity does not m
68 scheme for authenticating its block device roo
69 authenticating fs-verity file hashes include:
70
71 - Trusted userspace code. Often, the userspac
72 files can be trusted to authenticate them.
73 application that wants to authenticate data
74 or an application loader that is part of the
75 is already authenticated in a different way,
76 from a read-only partition that uses dm-veri
77 authenticate applications before loading the
78 trusted userspace code can authenticate a fi
79 retrieving its fs-verity digest using `FS_IO
80 verifying a signature of it using any usersp
81 library that supports digital signatures.
82
83 - Integrity Measurement Architecture (IMA). I
84 file digests as an alternative to its tradit
85 "IMA appraisal" enforces that files contain
86 signature in their "security.ima" extended a
87 by the IMA policy. For more information, se
88
89 - Trusted userspace code in combination with `
90 verification`_. This approach should be use
91
92 User API
93 ========
94
95 FS_IOC_ENABLE_VERITY
96 --------------------
97
98 The FS_IOC_ENABLE_VERITY ioctl enables fs-veri
99 in a pointer to a struct fsverity_enable_arg,
100 follows::
101
102 struct fsverity_enable_arg {
103 __u32 version;
104 __u32 hash_algorithm;
105 __u32 block_size;
106 __u32 salt_size;
107 __u64 salt_ptr;
108 __u32 sig_size;
109 __u32 __reserved1;
110 __u64 sig_ptr;
111 __u64 __reserved2[11];
112 };
113
114 This structure contains the parameters of the
115 the file. It must be initialized as follows:
116
117 - ``version`` must be 1.
118 - ``hash_algorithm`` must be the identifier fo
119 use for the Merkle tree, such as FS_VERITY_H
120 ``include/uapi/linux/fsverity.h`` for the li
121 - ``block_size`` is the Merkle tree block size
122 v6.3 and later, this can be any power of 2 b
123 1024 and the minimum of the system page size
124 block size. In earlier versions, the page s
125 value.
126 - ``salt_size`` is the size of the salt in byt
127 provided. The salt is a value that is prepe
128 block; it can be used to personalize the has
129 file or device. Currently the maximum salt
130 - ``salt_ptr`` is the pointer to the salt, or
131 provided.
132 - ``sig_size`` is the size of the builtin sign
133 builtin signature is provided. Currently th
134 (somewhat arbitrarily) limited to 16128 byte
135 - ``sig_ptr`` is the pointer to the builtin s
136 builtin signature is provided. A builtin si
137 if the `Built-in signature verification`_ fe
138 is not needed for IMA appraisal, and it is n
139 signature is being handled entirely in users
140 - All reserved fields must be zeroed.
141
142 FS_IOC_ENABLE_VERITY causes the filesystem to
143 the file and persist it to a filesystem-specif
144 with the file, then mark the file as a verity
145 take a long time to execute on large files, an
146 fatal signals.
147
148 FS_IOC_ENABLE_VERITY checks for write access t
149 it must be executed on an O_RDONLY file descri
150 can have the file open for writing. Attempts
151 writing while this ioctl is executing will fai
152 is necessary to guarantee that no writable fil
153 after verity is enabled, and to guarantee that
154 stable while the Merkle tree is being built ov
155
156 On success, FS_IOC_ENABLE_VERITY returns 0, an
157 verity file. On failure (including the case o
158 fatal signal), no changes are made to the file
159
160 FS_IOC_ENABLE_VERITY can fail with the followi
161
162 - ``EACCES``: the process does not have write
163 - ``EBADMSG``: the builtin signature is malfor
164 - ``EBUSY``: this ioctl is already running on
165 - ``EEXIST``: the file already has verity enab
166 - ``EFAULT``: the caller provided inaccessible
167 - ``EFBIG``: the file is too large to enable v
168 - ``EINTR``: the operation was interrupted by
169 - ``EINVAL``: unsupported version, hash algori
170 reserved bits are set; or the file descripto
171 regular file nor a directory.
172 - ``EISDIR``: the file descriptor refers to a
173 - ``EKEYREJECTED``: the builtin signature does
174 - ``EMSGSIZE``: the salt or builtin signature
175 - ``ENOKEY``: the ".fs-verity" keyring doesn't
176 needed to verify the builtin signature
177 - ``ENOPKG``: fs-verity recognizes the hash al
178 available in the kernel's crypto API as curr
179 for SHA-512, missing CONFIG_CRYPTO_SHA512).
180 - ``ENOTTY``: this type of filesystem does not
181 - ``EOPNOTSUPP``: the kernel was not configure
182 support; or the filesystem superblock has no
183 feature enabled on it; or the filesystem doe
184 on this file. (See `Filesystem support`_.)
185 - ``EPERM``: the file is append-only; or, a bu
186 required and one was not provided.
187 - ``EROFS``: the filesystem is read-only
188 - ``ETXTBSY``: someone has the file open for w
189 caller's file descriptor, another open file
190 reference held by a writable memory map.
191
192 FS_IOC_MEASURE_VERITY
193 ---------------------
194
195 The FS_IOC_MEASURE_VERITY ioctl retrieves the
196 The fs-verity file digest is a cryptographic d
197 the file contents that are being enforced on r
198 a Merkle tree and is different from a traditio
199
200 This ioctl takes in a pointer to a variable-le
201
202 struct fsverity_digest {
203 __u16 digest_algorithm;
204 __u16 digest_size; /* input/output
205 __u8 digest[];
206 };
207
208 ``digest_size`` is an input/output field. On
209 initialized to the number of bytes allocated f
210 ``digest`` field.
211
212 On success, 0 is returned and the kernel fills
213 follows:
214
215 - ``digest_algorithm`` will be the hash algori
216 digest. It will match ``fsverity_enable_arg
217 - ``digest_size`` will be the size of the dige
218 for SHA-256. (This can be redundant with ``
219 - ``digest`` will be the actual bytes of the d
220
221 FS_IOC_MEASURE_VERITY is guaranteed to execute
222 regardless of the size of the file.
223
224 FS_IOC_MEASURE_VERITY can fail with the follow
225
226 - ``EFAULT``: the caller provided inaccessible
227 - ``ENODATA``: the file is not a verity file
228 - ``ENOTTY``: this type of filesystem does not
229 - ``EOPNOTSUPP``: the kernel was not configure
230 support, or the filesystem superblock has no
231 feature enabled on it. (See `Filesystem sup
232 - ``EOVERFLOW``: the digest is longer than the
233 ``digest_size`` bytes. Try providing a larg
234
235 FS_IOC_READ_VERITY_METADATA
236 ---------------------------
237
238 The FS_IOC_READ_VERITY_METADATA ioctl reads ve
239 verity file. This ioctl is available since Li
240
241 This ioctl allows writing a server program tha
242 and serves it to a client program, such that t
243 fs-verity compatible verification of the file.
244 if the client doesn't trust the server and if
245 provide the storage for the client.
246
247 This is a fairly specialized use case, and mos
248 need this ioctl.
249
250 This ioctl takes in a pointer to the following
251
252 #define FS_VERITY_METADATA_TYPE_MERKLE_TREE
253 #define FS_VERITY_METADATA_TYPE_DESCRIPTOR
254 #define FS_VERITY_METADATA_TYPE_SIGNATURE
255
256 struct fsverity_read_metadata_arg {
257 __u64 metadata_type;
258 __u64 offset;
259 __u64 length;
260 __u64 buf_ptr;
261 __u64 __reserved;
262 };
263
264 ``metadata_type`` specifies the type of metada
265
266 - ``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` read
267 Merkle tree. The blocks are returned in ord
268 to the leaf level. Within each level, the b
269 the same order that their hashes are themsel
270 See `Merkle tree`_ for more information.
271
272 - ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads
273 descriptor. See `fs-verity descriptor`_.
274
275 - ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads
276 which was passed to FS_IOC_ENABLE_VERITY, if
277 signature verification`_.
278
279 The semantics are similar to those of ``pread(
280 specifies the offset in bytes into the metadat
281 ``length`` specifies the maximum number of byt
282 metadata item. ``buf_ptr`` is the pointer to
283 cast to a 64-bit integer. ``__reserved`` must
284 number of bytes read is returned. 0 is return
285 metadata item. The returned length may be les
286 example if the ioctl is interrupted.
287
288 The metadata returned by FS_IOC_READ_VERITY_ME
289 to be authenticated against the file digest th
290 `FS_IOC_MEASURE_VERITY`_, as the metadata is e
291 implement fs-verity compatible verification an
292 malicious disk, the metadata will indeed match
293 this ioctl, the filesystem is allowed to just
294 blocks from disk without actually verifying th
295
296 FS_IOC_READ_VERITY_METADATA can fail with the
297
298 - ``EFAULT``: the caller provided inaccessible
299 - ``EINTR``: the ioctl was interrupted before
300 - ``EINVAL``: reserved fields were set, or ``o
301 overflowed
302 - ``ENODATA``: the file is not a verity file,
303 FS_VERITY_METADATA_TYPE_SIGNATURE was reques
304 have a builtin signature
305 - ``ENOTTY``: this type of filesystem does not
306 this ioctl is not yet implemented on it
307 - ``EOPNOTSUPP``: the kernel was not configure
308 support, or the filesystem superblock has no
309 feature enabled on it. (See `Filesystem sup
310
311 FS_IOC_GETFLAGS
312 ---------------
313
314 The existing ioctl FS_IOC_GETFLAGS (which isn'
315 can also be used to check whether a file has f
316 To do so, check for FS_VERITY_FL (0x00100000)
317
318 The verity flag is not settable via FS_IOC_SET
319 FS_IOC_ENABLE_VERITY instead, since parameters
320
321 statx
322 -----
323
324 Since Linux v5.5, the statx() system call sets
325 the file has fs-verity enabled. This can perf
326 FS_IOC_GETFLAGS and FS_IOC_MEASURE_VERITY beca
327 opening the file, and opening verity files can
328
329 .. _accessing_verity_files:
330
331 Accessing verity files
332 ======================
333
334 Applications can transparently access a verity
335 non-verity one, with the following exceptions:
336
337 - Verity files are readonly. They cannot be o
338 truncate()d, even if the file mode bits allo
339 one of these things will fail with EPERM. H
340 metadata such as owner, mode, timestamps, an
341 allowed, since these are not measured by fs-
342 can also still be renamed, deleted, and link
343
344 - Direct I/O is not supported on verity files.
345 I/O on such files will fall back to buffered
346
347 - DAX (Direct Access) is not supported on veri
348 would circumvent the data verification.
349
350 - Reads of data that doesn't match the verity
351 with EIO (for read()) or SIGBUS (for mmap()
352
353 - If the sysctl "fs.verity.require_signatures"
354 file is not signed by a key in the ".fs-veri
355 opening the file will fail. See `Built-in s
356
357 Direct access to the Merkle tree is not suppor
358 verity file is copied, or is backed up and res
359 its "verity"-ness. fs-verity is primarily mea
360 executables that are managed by a package mana
361
362 File digest computation
363 =======================
364
365 This section describes how fs-verity hashes th
366 Merkle tree to produce the digest which crypto
367 the file contents. This algorithm is the same
368 that support fs-verity.
369
370 Userspace only needs to be aware of this algor
371 compute fs-verity file digests itself, e.g. in
372
373 .. _fsverity_merkle_tree:
374
375 Merkle tree
376 -----------
377
378 The file contents is divided into blocks, wher
379 configurable but is usually 4096 bytes. The e
380 zero-padded if needed. Each block is then has
381 level of hashes. Then, the hashes in this fir
382 into 'blocksize'-byte blocks (zero-padding the
383 these blocks are hashed, producing the second
384 proceeds up the tree until only a single block
385 this block is the "Merkle tree root hash".
386
387 If the file fits in one block and is nonempty,
388 root hash" is simply the hash of the single da
389 is empty, then the "Merkle tree root hash" is
390
391 The "blocks" here are not necessarily the same
392
393 If a salt was specified, then it's zero-padded
394 of the input size of the hash algorithm's comp
395 64 bytes for SHA-256 or 128 bytes for SHA-512.
396 prepended to every data or Merkle tree block t
397
398 The purpose of the block padding is to cause e
399 over the same amount of data, which simplifies
400 keeps open more possibilities for hardware acc
401 of the salt padding is to make the salting "fr
402 state is precomputed, then imported for each h
403
404 Example: in the recommended configuration of S
405 128 hash values fit in each block. Thus, each
406 tree is approximately 128 times smaller than t
407 large files the Merkle tree's size converges t
408 the original file size. However, for small fi
409 significant, making the space overhead proport
410
411 .. _fsverity_descriptor:
412
413 fs-verity descriptor
414 --------------------
415
416 By itself, the Merkle tree root hash is ambigu
417 can't a distinguish a large file from a small
418 is exactly the top-level hash block of the fir
419 also arise from the convention of padding to t
420
421 To solve this problem, the fs-verity file dige
422 as a hash of the following structure, which co
423 root hash as well as other fields such as the
424
425 struct fsverity_descriptor {
426 __u8 version; /* must be
427 __u8 hash_algorithm; /* Merkle
428 __u8 log_blocksize; /* log2 of
429 __u8 salt_size; /* size of
430 __le32 __reserved_0x04; /* must be
431 __le64 data_size; /* size of
432 __u8 root_hash[64]; /* Merkle
433 __u8 salt[32]; /* salt pr
434 __u8 __reserved[144]; /* must be
435 };
436
437 Built-in signature verification
438 ===============================
439
440 CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds sup
441 verification of fs-verity builtin signatures.
442
443 **IMPORTANT**! Please take great care before
444 It is not the only way to do signatures with f
445 alternatives (such as userspace signature veri
446 appraisal) can be much better. It's also easy
447 of thinking this feature solves more problems
448
449 Enabling this option adds the following:
450
451 1. At boot time, the kernel creates a keyring
452 root user can add trusted X.509 certificate
453 the add_key() system call.
454
455 2. `FS_IOC_ENABLE_VERITY`_ accepts a pointer t
456 detached signature in DER format of the fil
457 On success, the ioctl persists the signatur
458 tree. Then, any time the file is opened, t
459 file's actual digest against this signature
460 in the ".fs-verity" keyring.
461
462 3. A new sysctl "fs.verity.require_signatures"
463 When set to 1, the kernel requires that all
464 correctly signed digest as described in (2)
465
466 The data that the signature as described in (2
467 is the fs-verity file digest in the following
468
469 struct fsverity_formatted_digest {
470 char magic[8]; /*
471 __le16 digest_algorithm;
472 __le16 digest_size;
473 __u8 digest[];
474 };
475
476 That's it. It should be emphasized again that
477 signatures are not the only way to do signatur
478 `Use cases`_ for an overview of ways in which
479 fs-verity builtin signatures have some major l
480 be carefully considered before using them:
481
482 - Builtin signature verification does *not* ma
483 that any files actually have fs-verity enabl
484 complete authentication policy. Currently,
485 way to complete the authentication policy is
486 code to explicitly check whether files have
487 signature before they are accessed. (With
488 fs.verity.require_signatures=1, just checkin
489 enabled suffices.) But, in this case the tr
490 could just store the signature alongside the
491 itself using a cryptographic library, instea
492
493 - A file's builtin signature can only be set a
494 fs-verity is being enabled on the file. Cha
495 builtin signature later requires re-creating
496
497 - Builtin signature verification uses the same
498 all fs-verity enabled files on the system.
499 trusted for different files; each key is all
500
501 - The sysctl fs.verity.require_signatures appl
502 Setting it to 1 only works when all users of
503 agree that it should be set to 1. This limi
504 fs-verity from being used in cases where it
505
506 - Builtin signature verification can only use
507 that are supported by the kernel. For examp
508 yet support Ed25519, even though this is oft
509 algorithm that is recommended for new crypto
510
511 - fs-verity builtin signatures are in PKCS#7 f
512 keys are in X.509 format. These formats are
513 including by some other kernel features (whi
514 builtin signatures use them), and are very f
515 Unfortunately, history has shown that code t
516 these formats (which are from the 1990s and
517 often has vulnerabilities as a result of the
518 complexity is not inherent to the cryptograp
519
520 fs-verity users who do not need advanced fea
521 PKCS#7 should strongly consider using simple
522 Ed25519 keys and signatures, and verifying s
523
524 fs-verity users who choose to use X.509 and
525 still consider that verifying those signatur
526 flexible (for other reasons mentioned earlie
527 eliminates the need to enable CONFIG_FS_VERI
528 and its associated increase in kernel attack
529 it can even be necessary, since advanced X.5
530 do not always work as intended with the kern
531 kernel does not check X.509 certificate vali
532
533 Note: IMA appraisal, which supports fs-verit
534 for its signatures, so it partially avoids t
535 here. IMA appraisal does use X.509.
536
537 Filesystem support
538 ==================
539
540 fs-verity is supported by several filesystems,
541 CONFIG_FS_VERITY kconfig option must be enable
542 any of these filesystems.
543
544 ``include/linux/fsverity.h`` declares the inte
545 ``fs/verity/`` support layer and filesystems.
546 must provide an ``fsverity_operations`` struct
547 methods to read and write the verity metadata
548 location, including the Merkle tree blocks and
549 ``fsverity_descriptor``. Filesystems must als
550 ``fs/verity/`` at certain times, such as when
551 pages have been read into the pagecache. (See
552
553 ext4
554 ----
555
556 ext4 supports fs-verity since Linux v5.4 and e
557
558 To create verity files on an ext4 filesystem,
559 been formatted with ``-O verity`` or had ``tun
560 it. "verity" is an RO_COMPAT filesystem featu
561 kernels will only be able to mount the filesys
562 versions of e2fsck will be unable to check the
563
564 Originally, an ext4 filesystem with the "verit
565 mounted when its block size was equal to the s
566 (typically 4096 bytes). In Linux v6.3, this l
567
568 ext4 sets the EXT4_VERITY_FL on-disk inode fla
569 can only be set by `FS_IOC_ENABLE_VERITY`_, an
570
571 ext4 also supports encryption, which can be us
572 fs-verity. In this case, the plaintext data i
573 the ciphertext. This is necessary in order to
574 digest meaningful, since every file is encrypt
575
576 ext4 stores the verity metadata (Merkle tree a
577 past the end of the file, starting at the firs
578 i_size. This approach works because (a) verit
579 and (b) pages fully beyond i_size aren't visib
580 be read/written internally by ext4 with only s
581 changes to ext4. This approach avoids having
582 EA_INODE feature and on rearchitecturing ext4'
583 support paging multi-gigabyte xattrs into memo
584 encrypting xattrs. Note that the verity metad
585 when the file is, since it contains hashes of
586
587 ext4 only allows verity on extent-based files.
588
589 f2fs
590 ----
591
592 f2fs supports fs-verity since Linux v5.4 and f
593
594 To create verity files on an f2fs filesystem,
595 been formatted with ``-O verity``.
596
597 f2fs sets the FADVISE_VERITY_BIT on-disk inode
598 It can only be set by `FS_IOC_ENABLE_VERITY`_,
599 cleared.
600
601 Like ext4, f2fs stores the verity metadata (Me
602 fsverity_descriptor) past the end of the file,
603 64K boundary beyond i_size. See explanation f
604 Moreover, f2fs supports at most 4096 bytes of
605 which usually wouldn't be enough for even a si
606
607 f2fs doesn't support enabling verity on files
608 atomic or volatile writes pending.
609
610 btrfs
611 -----
612
613 btrfs supports fs-verity since Linux v5.15. V
614 marked with a RO_COMPAT inode flag, and the ve
615 in separate btree items.
616
617 Implementation details
618 ======================
619
620 Verifying data
621 --------------
622
623 fs-verity ensures that all reads of a verity f
624 regardless of which syscall is used to do the
625 read(), pread()) and regardless of whether it'
626 later read (unless the later read can return c
627 already verified). Below, we describe how fil
628
629 Pagecache
630 ~~~~~~~~~
631
632 For filesystems using Linux's pagecache, the `
633 ``->readahead()`` methods must be modified to
634 they are marked Uptodate. Merely hooking ``->
635 insufficient, since ``->read_iter()`` is not u
636
637 Therefore, fs/verity/ provides the function fs
638 which verifies data that has been read into th
639 inode. The containing folio must still be loc
640 it's not yet readable by userspace. As needed
641 fsverity_verify_blocks() will call back into t
642 hash blocks via fsverity_operations::read_merk
643
644 fsverity_verify_blocks() returns false if veri
645 case, the filesystem must not set the folio Up
646 as per the usual Linux pagecache behavior, att
647 read() from the part of the file containing th
648 EIO, and accesses to the folio within a memory
649
650 In principle, verifying a data block requires
651 path in the Merkle tree from the data block to
652 However, for efficiency the filesystem may cac
653 Therefore, fsverity_verify_blocks() only ascen
654 blocks until an already-verified hash block is
655 the path to that block.
656
657 This optimization, which is also used by dm-ve
658 excellent sequential read performance. This i
659 127 in 128 times for 4K blocks and SHA-256) th
660 bottom level of the tree will already be cache
661 reading a previous data block. However, rando
662
663 Block device based filesystems
664 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
665
666 Block device based filesystems (e.g. ext4 and
667 the pagecache, so the above subsection applies
668 also usually read many data blocks from a file
669 structure called a "bio". To make it easier f
670 filesystems to support fs-verity, fs/verity/ a
671 fsverity_verify_bio() which verifies all data
672
673 ext4 and f2fs also support encryption. If a v
674 encrypted, the data must be decrypted before b
675 support this, these filesystems allocate a "po
676 each bio and store it in ``->bi_private``::
677
678 struct bio_post_read_ctx {
679 struct bio *bio;
680 struct work_struct work;
681 unsigned int cur_step;
682 unsigned int enabled_steps;
683 };
684
685 ``enabled_steps`` is a bitmask that specifies
686 verity, or both is enabled. After the bio com
687 postprocessing step the filesystem enqueues th
688 workqueue, and then the workqueue work does th
689 verification. Finally, folios where no decryp
690 occurred are marked Uptodate, and the folios a
691
692 On many filesystems, files can contain holes.
693 ``->readahead()`` simply zeroes hole blocks an
694 corresponding data to be up-to-date; no bios a
695 this case from bypassing fs-verity, filesystem
696 fsverity_verify_blocks() to verify hole blocks
697
698 Filesystems also disable direct I/O on verity
699 direct I/O would bypass fs-verity.
700
701 Userspace utility
702 =================
703
704 This document focuses on the kernel, but a use
705 fs-verity can be found at:
706
707 https://git.kernel.org/pub/scm/fs/fsve
708
709 See the README.md file in the fsverity-utils s
710 including examples of setting up fs-verity pro
711
712 Tests
713 =====
714
715 To test fs-verity, use xfstests. For example,
716 <https://github.com/tytso/xfstests-bld/blob/ma
717
718 kvm-xfstests -c ext4,f2fs,btrfs -g verity
719
720 FAQ
721 ===
722
723 This section answers frequently asked question
724 weren't already directly answered in other par
725
726 :Q: Why isn't fs-verity part of IMA?
727 :A: fs-verity and IMA (Integrity Measurement A
728 different focuses. fs-verity is a filesys
729 hashing individual files using a Merkle tr
730 specifies a system-wide policy that specif
731 hashed and what to do with those hashes, s
732 authenticate them, or add them to a measur
733
734 IMA supports the fs-verity hashing mechani
735 to full file hashes, for those who want th
736 security benefits of the Merkle tree based
737 doesn't make sense to force all uses of fs
738 IMA. fs-verity already meets many users'
739 standalone filesystem feature, and it's te
740 filesystem features e.g. with xfstests.
741
742 :Q: Isn't fs-verity useless because the attack
743 hashes in the Merkle tree, which is stored
744 :A: To verify the authenticity of an fs-verity
745 the authenticity of the "fs-verity file di
746 incorporates the root hash of the Merkle t
747
748 :Q: Isn't fs-verity useless because the attack
749 verity file with a non-verity one?
750 :A: See `Use cases`_. In the initial use case
751 userspace code that authenticates the file
752 tool to do this job efficiently and secure
753 userspace code will consider non-verity fi
754
755 :Q: Why does the Merkle tree need to be stored
756 store just the root hash?
757 :A: If the Merkle tree wasn't stored on-disk,
758 compute the entire tree when the file is f
759 just one byte is being read. This is a fu
760 how Merkle tree hashing works. To verify
761 verify the whole path to the root hash, in
762 (the thing which the root hash is a hash o
763 node isn't stored on-disk, you have to com
764 children, and so on until you've actually
765
766 That defeats most of the point of doing a
767 since if you have to hash the whole file a
768 then you could simply do sha256(file) inst
769 simpler, and a bit faster too.
770
771 It's true that an in-memory Merkle tree co
772 advantage of verification on every read ra
773 first read. However, it would be ineffici
774 hash page gets evicted (you can't pin the
775 memory, since it may be very large), in or
776 again need to hash everything below it in
777 defeats most of the point of doing a Merkl
778 a single block read could trigger re-hashi
779
780 :Q: But couldn't you store just the leaf nodes
781 :A: See previous answer; this really just move
782 one could alternatively interpret the data
783 leaf nodes of the Merkle tree. It's true
784 computed much faster if the leaf level is
785 the data, but that's only because each lev
786 size of the level below (assuming the reco
787 SHA-256 and 4K blocks). For the exact sam
788 "just the leaf nodes" you'd already be sto
789 tree, so you might as well simply store th
790
791 :Q: Can the Merkle tree be built ahead of time
792 part of a package that is installed to man
793 :A: This isn't currently supported. It was pa
794 design, but was removed to simplify the ke
795 wasn't a critical use case. Files are usu
796 used many times, and cryptographic hashing
797 most modern processors.
798
799 :Q: Why doesn't fs-verity support writes?
800 :A: Write support would be very difficult and
801 completely different design, so it's well
802 fs-verity. Write support would require:
803
804 - A way to maintain consistency between th
805 including all levels of hashes, since co
806 (especially of potentially the entire fi
807 The main options for solving this are da
808 copy-on-write, and log-structured volume
809 retrofit existing filesystems with new c
810 Data journalling is available on ext4, b
811
812 - Rebuilding the Merkle tree after every w
813 extremely inefficient. Alternatively, a
814 dictionary structure such as an "authent
815 be used. However, this would be far mor
816
817 Compare it to dm-verity vs. dm-integrity.
818 simple: the kernel just verifies read-only
819 read-only Merkle tree. In contrast, dm-in
820 but is slow, is much more complex, and doe
821 full-device authentication since it authen
822 independently, i.e. there is no "root hash
823 make sense for the same device-mapper targ
824 very different cases; the same applies to
825
826 :Q: Since verity files are immutable, why isn'
827 :A: The existing "immutable" bit (FS_IMMUTABLE
828 specific set of semantics which not only m
829 read-only, but also prevent the file from
830 linked to, or having its owner or mode cha
831 properties are unwanted for fs-verity, so
832 bit isn't appropriate.
833
834 :Q: Why does the API use ioctls instead of set
835 :A: Abusing the xattr interface for basically
836 heavily frowned upon by most of the Linux
837 An xattr should really just be an xattr on
838 e.g. magically trigger construction of a M
839
840 :Q: Does fs-verity support remote filesystems?
841 :A: So far all filesystems that have implement
842 local filesystems, but in principle any fi
843 per-file verity metadata can support fs-ve
844 whether it's local or remote. Some filesy
845 options of where to store the verity metad
846 to store it past the end of the file and "
847 by manipulating i_size. The data verifica
848 by ``fs/verity/`` also assume that the fil
849 pagecache, but both local and remote files
850
851 :Q: Why is anything filesystem-specific at all
852 be implemented entirely at the VFS level?
853 :A: There are many reasons why this is not pos
854 difficult, including the following:
855
856 - To prevent bypassing verification, folio
857 Uptodate until they've been verified. C
858 filesystem is responsible for marking fo
859 ``->readahead()``. Therefore, currently
860 the VFS to do the verification on its ow
861 require significant changes to the VFS a
862
863 - It would require defining a filesystem-i
864 the verity metadata. Extended attribute
865 because (a) the Merkle tree may be gigab
866 filesystems assume that all xattrs fit i
867 filesystem block, and (b) ext4 and f2fs
868 encrypt xattrs, yet the Merkle tree *mus
869 file contents are, because it stores has
870 file contents.
871
872 So the verity metadata would have to be
873 file. Using a separate file would be ve
874 metadata is fundamentally part of the fi
875 it could cause problems where users coul
876 but not the metadata file or vice versa.
877 having it be in the same file would brea
878 filesystems' notion of i_size were divor
879 which would be complex and require chang
880
881 - It's desirable that FS_IOC_ENABLE_VERITY
882 transaction mechanism so that either the
883 verity enabled, or no changes were made.
884 states to occur after a crash may cause
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.