Lines Matching +full:in +full:- +full:tree
1 .. SPDX-License-Identifier: GPL-2.0
6 fs-verity: read-only file-based authenticity protection
12 fs-verity (``fs/verity/``) is a support layer that filesystems can
14 of read-only files. Currently, it is supported by the ext4, f2fs, and
15 btrfs filesystems. Like fscrypt, not too much filesystem-specific
16 code is needed to support fs-verity.
18 fs-verity is similar to `dm-verity
19 <https://www.kernel.org/doc/Documentation/admin-guide/device-mapper/verity.rst>`_
21 filesystems supporting fs-verity, userspace can execute an ioctl that
22 causes the filesystem to build a Merkle tree for the file and persist
23 it to a filesystem-specific location associated with the file.
26 automatically verified against the file's Merkle tree. Reads of any
30 the "fs-verity file digest", which is a hash that includes the Merkle
31 tree root hash) that fs-verity is enforcing for the file. This ioctl
32 executes in constant time, regardless of the file size.
34 fs-verity is essentially a way to hash a file in constant time,
41 By itself, fs-verity only provides integrity protection, i.e.
42 detection of accidental (non-malicious) corruption.
44 However, because fs-verity makes retrieving the file hash extremely
49 A standard file hash could be used instead of fs-verity. However,
57 Unlike an ahead-of-time hash, fs-verity also re-verifies data each
58 time it's paged in. This ensures that malicious disk firmware can't
61 fs-verity does not replace or obsolete dm-verity. dm-verity should
62 still be used on read-only filesystems. fs-verity is for files that
63 must live on a read-write filesystem because they are independently
64 updated and potentially user-installed, so dm-verity cannot be used.
66 fs-verity does not mandate a particular scheme for authenticating its
67 file hashes. (Similarly, dm-verity does not mandate a particular
69 authenticating fs-verity file hashes include:
71 - Trusted userspace code. Often, the userspace code that accesses
75 is already authenticated in a different way, such as by being loaded
76 from a read-only partition that uses dm-verity) and that wants to
77 authenticate applications before loading them. In these cases, this
79 retrieving its fs-verity digest using `FS_IOC_MEASURE_VERITY`_, then
83 - Integrity Measurement Architecture (IMA). IMA supports fs-verity
86 signature in their "security.ima" extended attribute, as controlled
89 - Integrity Policy Enforcement (IPE). IPE supports enforcing access
91 including those protected by fs-verity's built-in signatures.
92 "IPE policy" specifically allows for the authorization of fs-verity
95 files with a verified fs-verity's built-in signature. For
97 modes, please refer to :doc:`IPE admin guide </admin-guide/LSM/ipe>`.
99 - Trusted userspace code in combination with `Built-in signature
106 --------------------
108 The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes
109 in a pointer to a struct fsverity_enable_arg, defined as
124 This structure contains the parameters of the Merkle tree to build for
127 - ``version`` must be 1.
128 - ``hash_algorithm`` must be the identifier for the hash algorithm to
129 use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256. See
131 - ``block_size`` is the Merkle tree block size, in bytes. In Linux
134 block size. In earlier versions, the page size was the only allowed
136 - ``salt_size`` is the size of the salt in bytes, or 0 if no salt is
140 - ``salt_ptr`` is the pointer to the salt, or NULL if no salt is
142 - ``sig_size`` is the size of the builtin signature in bytes, or 0 if no
145 - ``sig_ptr`` is the pointer to the builtin signature, or NULL if no
147 if the `Built-in signature verification`_ feature is being used. It
149 signature is being handled entirely in userspace.
150 - All reserved fields must be zeroed.
152 FS_IOC_ENABLE_VERITY causes the filesystem to build a Merkle tree for
153 the file and persist it to a filesystem-specific location associated
164 stable while the Merkle tree is being built over it.)
172 - ``EACCES``: the process does not have write access to the file
173 - ``EBADMSG``: the builtin signature is malformed
174 - ``EBUSY``: this ioctl is already running on the file
175 - ``EEXIST``: the file already has verity enabled
176 - ``EFAULT``: the caller provided inaccessible memory
177 - ``EFBIG``: the file is too large to enable verity on
178 - ``EINTR``: the operation was interrupted by a fatal signal
179 - ``EINVAL``: unsupported version, hash algorithm, or block size; or
182 - ``EISDIR``: the file descriptor refers to a directory
183 - ``EKEYREJECTED``: the builtin signature doesn't match the file
184 - ``EMSGSIZE``: the salt or builtin signature is too long
185 - ``ENOKEY``: the ".fs-verity" keyring doesn't contain the certificate
187 - ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not
188 available in the kernel's crypto API as currently configured (e.g.
189 for SHA-512, missing CONFIG_CRYPTO_SHA512).
190 - ``ENOTTY``: this type of filesystem does not implement fs-verity
191 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
193 feature enabled on it; or the filesystem does not support fs-verity
195 - ``EPERM``: the file is append-only; or, a builtin signature is
197 - ``EROFS``: the filesystem is read-only
198 - ``ETXTBSY``: someone has the file open for writing. This can be the
203 ---------------------
206 The fs-verity file digest is a cryptographic digest that identifies
208 a Merkle tree and is different from a traditional full-file digest.
210 This ioctl takes in a pointer to a variable-length structure::
219 initialized to the number of bytes allocated for the variable-length
222 On success, 0 is returned and the kernel fills in the structure as
225 - ``digest_algorithm`` will be the hash algorithm used for the file
227 - ``digest_size`` will be the size of the digest in bytes, e.g. 32
228 for SHA-256. (This can be redundant with ``digest_algorithm``.)
229 - ``digest`` will be the actual bytes of the digest.
231 FS_IOC_MEASURE_VERITY is guaranteed to execute in constant time,
236 - ``EFAULT``: the caller provided inaccessible memory
237 - ``ENODATA``: the file is not a verity file
238 - ``ENOTTY``: this type of filesystem does not implement fs-verity
239 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
242 - ``EOVERFLOW``: the digest is longer than the specified
246 ---------------------------
253 fs-verity compatible verification of the file. This only makes sense
257 This is a fairly specialized use case, and most fs-verity users won't
260 This ioctl takes in a pointer to the following structure::
276 - ``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the
277 Merkle tree. The blocks are returned in order from the root level
278 to the leaf level. Within each level, the blocks are returned in
280 See `Merkle tree`_ for more information.
282 - ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity
283 descriptor. See `fs-verity descriptor`_.
285 - ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the builtin signature
286 which was passed to FS_IOC_ENABLE_VERITY, if any. See `Built-in
290 specifies the offset in bytes into the metadata item to read from, and
293 cast to a 64-bit integer. ``__reserved`` must be 0. On success, the
301 implement fs-verity compatible verification anyway (though absent a
303 this ioctl, the filesystem is allowed to just read the Merkle tree
308 - ``EFAULT``: the caller provided inaccessible memory
309 - ``EINTR``: the ioctl was interrupted before any data was read
310 - ``EINVAL``: reserved fields were set, or ``offset + length``
312 - ``ENODATA``: the file is not a verity file, or
315 - ``ENOTTY``: this type of filesystem does not implement fs-verity, or
317 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
322 ---------------
324 The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
325 can also be used to check whether a file has fs-verity enabled or not.
326 To do so, check for FS_VERITY_FL (0x00100000) in the returned flags.
332 -----
335 the file has fs-verity enabled. This can perform better than
345 non-verity one, with the following exceptions:
347 - Verity files are readonly. They cannot be opened for writing or
351 allowed, since these are not measured by fs-verity. Verity files
354 - Direct I/O is not supported on verity files. Attempts to use direct
357 - DAX (Direct Access) is not supported on verity files, because this
360 - Reads of data that doesn't match the verity Merkle tree will fail
363 - If the sysctl "fs.verity.require_signatures" is set to 1 and the
364 file is not signed by a key in the ".fs-verity" keyring, then
365 opening the file will fail. See `Built-in signature verification`_.
367 Direct access to the Merkle tree is not supported. Therefore, if a
369 its "verity"-ness. fs-verity is primarily meant for files like
375 This section describes how fs-verity hashes the file contents using a
376 Merkle tree to produce the digest which cryptographically identifies
378 that support fs-verity.
381 compute fs-verity file digests itself, e.g. in order to sign files.
385 Merkle tree
386 -----------
390 zero-padded if needed. Each block is then hashed, producing the first
391 level of hashes. Then, the hashes in this first level are grouped
392 into 'blocksize'-byte blocks (zero-padding the ends as needed) and
394 proceeds up the tree until only a single block remains. The hash of
395 this block is the "Merkle tree root hash".
397 If the file fits in one block and is nonempty, then the "Merkle tree
399 is empty, then the "Merkle tree root hash" is all zeroes.
403 If a salt was specified, then it's zero-padded to the closest multiple
405 64 bytes for SHA-256 or 128 bytes for SHA-512. The padded salt is
406 prepended to every data or Merkle tree block that is hashed.
414 Example: in the recommended configuration of SHA-256 and 4K blocks,
415 128 hash values fit in each block. Thus, each level of the Merkle
416 tree is approximately 128 times smaller than the previous, and for
417 large files the Merkle tree's size converges to approximately 1/127 of
423 fs-verity descriptor
424 --------------------
426 By itself, the Merkle tree root hash is ambiguous. For example, it argument
428 is exactly the top-level hash block of the first file. Ambiguities
431 To solve this problem, the fs-verity file digest is actually computed
432 as a hash of the following structure, which contains the Merkle tree
437 __u8 hash_algorithm; /* Merkle tree hash algorithm */
438 __u8 log_blocksize; /* log2 of size of data and tree blocks */
439 __u8 salt_size; /* size of salt in bytes; 0 if none */
441 __le64 data_size; /* size of file the Merkle tree is built over */
442 __u8 root_hash[64]; /* Merkle tree root hash */
447 Built-in signature verification
450 CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds supports for in-kernel
451 verification of fs-verity builtin signatures.
454 It is not the only way to do signatures with fs-verity, and the
461 1. At boot time, the kernel creates a keyring named ".fs-verity". The
466 detached signature in DER format of the file's fs-verity digest.
468 tree. Then, any time the file is opened, the kernel verifies the
470 in the ".fs-verity" keyring. This verification happens as long as the
472 "fs.verity.require_signatures" described in the next item. The IPE LSM
474 that contain a verified built-in fsverity signature.
478 correctly signed digest as described in (2).
480 The data that the signature as described in (2) must be a signature of
481 is the fs-verity file digest in the following format::
490 That's it. It should be emphasized again that fs-verity builtin
491 signatures are not the only way to do signatures with fs-verity. See
492 `Use cases`_ for an overview of ways in which fs-verity can be used.
493 fs-verity builtin signatures have some major limitations that should
496 - Builtin signature verification does *not* make the kernel enforce
497 that any files actually have fs-verity enabled. Thus, it is not a
500 code to explicitly check whether files have fs-verity enabled with a
502 fs.verity.require_signatures=1, just checking whether fs-verity is
503 enabled suffices.) But, in this case the trusted userspace code
507 - Another approach is to utilize fs-verity builtin signature
508 verification in conjunction with the IPE LSM, which supports defining
509 a kernel-enforced, system-wide authentication policy that allows only
510 files with a verified fs-verity builtin signature to perform certain
513 Please refer to :doc:`IPE admin guide </admin-guide/LSM/ipe>` for
516 - A file's builtin signature can only be set at the same time that
517 fs-verity is being enabled on the file. Changing or deleting the
518 builtin signature later requires re-creating the file.
520 - Builtin signature verification uses the same set of public keys for
521 all fs-verity enabled files on the system. Different keys cannot be
524 - The sysctl fs.verity.require_signatures applies system-wide.
525 Setting it to 1 only works when all users of fs-verity on the system
527 fs-verity from being used in cases where it would be helpful.
529 - Builtin signature verification can only use signature algorithms
534 - fs-verity builtin signatures are in PKCS#7 format, and the public
535 keys are in X.509 format. These formats are commonly used,
536 including by some other kernel features (which is why the fs-verity
543 fs-verity users who do not need advanced features of X.509 and
545 Ed25519 keys and signatures, and verifying signatures in userspace.
547 fs-verity users who choose to use X.509 and PKCS#7 anyway should
548 still consider that verifying those signatures in userspace is more
549 flexible (for other reasons mentioned earlier in this document) and
551 and its associated increase in kernel attack surface. In some cases
556 Note: IMA appraisal, which supports fs-verity, does not use PKCS#7
563 fs-verity is supported by several filesystems, described below. The
564 CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on
570 methods to read and write the verity metadata to a filesystem-specific
571 location, including the Merkle tree blocks and
572 ``fsverity_descriptor``. Filesystems must also call functions in
577 ----
579 ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.
582 been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
589 (typically 4096 bytes). In Linux v6.3, this limitation was removed.
591 ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It
595 fs-verity. In this case, the plaintext data is verified rather than
596 the ciphertext. This is necessary in order to make the fs-verity file
599 ext4 stores the verity metadata (Merkle tree and fsverity_descriptor)
606 support paging multi-gigabyte xattrs into memory, and to support
610 ext4 only allows verity on extent-based files.
613 ----
615 f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.
618 been formatted with ``-O verity``.
620 f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
624 Like ext4, f2fs stores the verity metadata (Merkle tree and
628 which usually wouldn't be enough for even a single Merkle tree block.
634 -----
636 btrfs supports fs-verity since Linux v5.15. Verity-enabled inodes are
638 in separate btree items.
644 --------------
646 fs-verity ensures that all reads of a verity file's data are verified,
655 For filesystems using Linux's pagecache, the ``->read_folio()`` and
656 ``->readahead()`` methods must be modified to verify folios before
657 they are marked Uptodate. Merely hooking ``->read_iter()`` would be
658 insufficient, since ``->read_iter()`` is not used for memory maps.
667 fsverity_verify_blocks() returns false if verification failed; in this
673 In principle, verifying a data block requires verifying the entire
674 path in the Merkle tree from the data block to the root hash.
676 Therefore, fsverity_verify_blocks() only ascends the tree reading hash
677 blocks until an already-verified hash block is seen. It then verifies
680 This optimization, which is also used by dm-verity, results in
682 127 in 128 times for 4K blocks and SHA-256) the hash block from the
683 bottom level of the tree will already be cached and checked from
689 Block device based filesystems (e.g. ext4 and f2fs) in Linux also use
693 filesystems to support fs-verity, fs/verity/ also provides a function
694 fsverity_verify_bio() which verifies all data blocks in a bio.
698 support this, these filesystems allocate a "post-read context" for
699 each bio and store it in ``->bi_private``::
716 ``->readahead()`` simply zeroes hole blocks and considers the
717 corresponding data to be up-to-date; no bios are issued. To prevent
718 this case from bypassing fs-verity, filesystems use
722 direct I/O would bypass fs-verity.
728 fs-verity can be found at:
730 https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git
732 See the README.md file in the fsverity-utils source tree for details,
733 including examples of setting up fs-verity protected files.
738 To test fs-verity, use xfstests. For example, using `kvm-xfstests
739 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
741 kvm-xfstests -c ext4,f2fs,btrfs -g verity
746 This section answers frequently asked questions about fs-verity that
747 weren't already directly answered in other parts of this document.
749 :Q: Why isn't fs-verity part of IMA?
750 :A: fs-verity and IMA (Integrity Measurement Architecture) have
751 different focuses. fs-verity is a filesystem-level mechanism for
752 hashing individual files using a Merkle tree. In contrast, IMA
753 specifies a system-wide policy that specifies which files are
757 IMA supports the fs-verity hashing mechanism as an alternative
759 security benefits of the Merkle tree based hash. However, it
760 doesn't make sense to force all uses of fs-verity to be through
761 IMA. fs-verity already meets many users' needs even as a
765 :Q: Isn't fs-verity useless because the attacker can just modify the
766 hashes in the Merkle tree, which is stored on-disk?
767 :A: To verify the authenticity of an fs-verity file you must verify
768 the authenticity of the "fs-verity file digest", which
769 incorporates the root hash of the Merkle tree. See `Use cases`_.
771 :Q: Isn't fs-verity useless because the attacker can just replace a
772 verity file with a non-verity one?
773 :A: See `Use cases`_. In the initial use case, it's really trusted
774 userspace code that authenticates the files; fs-verity is just a
776 userspace code will consider non-verity files to be inauthentic.
778 :Q: Why does the Merkle tree need to be stored on-disk? Couldn't you
780 :A: If the Merkle tree wasn't stored on-disk, then you'd have to
781 compute the entire tree when the file is first accessed, even if
783 how Merkle tree hashing works. To verify a leaf node, you need to
786 node isn't stored on-disk, you have to compute it by hashing its
789 That defeats most of the point of doing a Merkle tree-based hash,
794 It's true that an in-memory Merkle tree could still provide the
797 hash page gets evicted (you can't pin the entire Merkle tree into
798 memory, since it may be very large), in order to restore it you
799 again need to hash everything below it in the tree. This again
800 defeats most of the point of doing a Merkle tree-based hash, since
801 a single block read could trigger re-hashing gigabytes of data.
806 leaf nodes of the Merkle tree. It's true that the tree can be
810 SHA-256 and 4K blocks). For the exact same reason, by storing
812 tree, so you might as well simply store the whole tree.
814 :Q: Can the Merkle tree be built ahead of time, e.g. distributed as
822 :Q: Why doesn't fs-verity support writes?
825 fs-verity. Write support would require:
827 - A way to maintain consistency between the data and hashes,
831 copy-on-write, and log-structured volume. But it's very hard to
835 - Rebuilding the Merkle tree after every write, which would be
840 Compare it to dm-verity vs. dm-integrity. dm-verity is very
841 simple: the kernel just verifies read-only data against a
842 read-only Merkle tree. In contrast, dm-integrity supports writes
844 full-device authentication since it authenticates each sector
846 make sense for the same device-mapper target to support these two
847 very different cases; the same applies to fs-verity.
852 read-only, but also prevent the file from being deleted, renamed,
854 properties are unwanted for fs-verity, so reusing the immutable
860 An xattr should really just be an xattr on-disk, not an API to
861 e.g. magically trigger construction of a Merkle tree.
863 :Q: Does fs-verity support remote filesystems?
864 :A: So far all filesystems that have implemented fs-verity support are
865 local filesystems, but in principle any filesystem that can store
866 per-file verity metadata can support fs-verity, regardless of
874 :Q: Why is anything filesystem-specific at all? Shouldn't fs-verity
879 - To prevent bypassing verification, folios must not be marked
882 ``->readahead()``. Therefore, currently it's not possible for
886 - It would require defining a filesystem-independent way to store
888 because (a) the Merkle tree may be gigabytes, but many
891 encrypt xattrs, yet the Merkle tree *must* be encrypted when the
895 So the verity metadata would have to be stored in an actual
900 having it be in the same file would break applications unless
904 - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's