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 ---------------------------
255 to a client program, such that the client can do its own fs-verity
261 images in userspace (such as with ``mkfs.ext4 -d``).
263 This is a fairly specialized use case, and most fs-verity users won't
266 This ioctl takes in a pointer to the following structure::
282 - ``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the
283 Merkle tree. The blocks are returned in order from the root level
284 to the leaf level. Within each level, the blocks are returned in
286 See `Merkle tree`_ for more information.
288 - ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity
289 descriptor. See `fs-verity descriptor`_.
291 - ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the builtin signature
292 which was passed to FS_IOC_ENABLE_VERITY, if any. See `Built-in
296 specifies the offset in bytes into the metadata item to read from, and
299 cast to a 64-bit integer. ``__reserved`` must be 0. On success, the
307 implement fs-verity compatible verification anyway (though absent a
309 this ioctl, the filesystem is allowed to just read the Merkle tree
314 - ``EFAULT``: the caller provided inaccessible memory
315 - ``EINTR``: the ioctl was interrupted before any data was read
316 - ``EINVAL``: reserved fields were set, or ``offset + length``
318 - ``ENODATA``: the file is not a verity file, or
321 - ``ENOTTY``: this type of filesystem does not implement fs-verity, or
323 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
328 ---------------
330 The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
331 can also be used to check whether a file has fs-verity enabled or not.
332 To do so, check for FS_VERITY_FL (0x00100000) in the returned flags.
338 -----
341 the file has fs-verity enabled. This can perform better than
351 non-verity one, with the following exceptions:
353 - Verity files are readonly. They cannot be opened for writing or
357 allowed, since these are not measured by fs-verity. Verity files
360 - Direct I/O is not supported on verity files. Attempts to use direct
363 - DAX (Direct Access) is not supported on verity files, because this
366 - Reads of data that doesn't match the verity Merkle tree will fail
369 - If the sysctl "fs.verity.require_signatures" is set to 1 and the
370 file is not signed by a key in the ".fs-verity" keyring, then
371 opening the file will fail. See `Built-in signature verification`_.
373 Direct access to the Merkle tree is not supported. Therefore, if a
375 its "verity"-ness. fs-verity is primarily meant for files like
381 This section describes how fs-verity hashes the file contents using a
382 Merkle tree to produce the digest which cryptographically identifies
384 that support fs-verity.
387 compute fs-verity file digests itself, e.g. in order to sign files.
391 Merkle tree
392 -----------
396 zero-padded if needed. Each block is then hashed, producing the first
397 level of hashes. Then, the hashes in this first level are grouped
398 into 'blocksize'-byte blocks (zero-padding the ends as needed) and
400 proceeds up the tree until only a single block remains. The hash of
401 this block is the "Merkle tree root hash".
403 If the file fits in one block and is nonempty, then the "Merkle tree
405 is empty, then the "Merkle tree root hash" is all zeroes.
409 If a salt was specified, then it's zero-padded to the closest multiple
411 64 bytes for SHA-256 or 128 bytes for SHA-512. The padded salt is
412 prepended to every data or Merkle tree block that is hashed.
420 Example: in the recommended configuration of SHA-256 and 4K blocks,
421 128 hash values fit in each block. Thus, each level of the Merkle
422 tree is approximately 128 times smaller than the previous, and for
423 large files the Merkle tree's size converges to approximately 1/127 of
429 fs-verity descriptor
430 --------------------
432 By itself, the Merkle tree root hash is ambiguous. For example, it argument
434 is exactly the top-level hash block of the first file. Ambiguities
437 To solve this problem, the fs-verity file digest is actually computed
438 as a hash of the following structure, which contains the Merkle tree
443 __u8 hash_algorithm; /* Merkle tree hash algorithm */
444 __u8 log_blocksize; /* log2 of size of data and tree blocks */
445 __u8 salt_size; /* size of salt in bytes; 0 if none */
447 __le64 data_size; /* size of file the Merkle tree is built over */
448 __u8 root_hash[64]; /* Merkle tree root hash */
453 Built-in signature verification
456 CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds supports for in-kernel
457 verification of fs-verity builtin signatures.
460 It is not the only way to do signatures with fs-verity, and the
467 1. At boot time, the kernel creates a keyring named ".fs-verity". The
472 detached signature in DER format of the file's fs-verity digest.
474 tree. Then, any time the file is opened, the kernel verifies the
476 in the ".fs-verity" keyring. This verification happens as long as the
478 "fs.verity.require_signatures" described in the next item. The IPE LSM
480 that contain a verified built-in fsverity signature.
484 correctly signed digest as described in (2).
486 The data that the signature as described in (2) must be a signature of
487 is the fs-verity file digest in the following format::
496 That's it. It should be emphasized again that fs-verity builtin
497 signatures are not the only way to do signatures with fs-verity. See
498 `Use cases`_ for an overview of ways in which fs-verity can be used.
499 fs-verity builtin signatures have some major limitations that should
502 - Builtin signature verification does *not* make the kernel enforce
503 that any files actually have fs-verity enabled. Thus, it is not a
506 code to explicitly check whether files have fs-verity enabled with a
508 fs.verity.require_signatures=1, just checking whether fs-verity is
509 enabled suffices.) But, in this case the trusted userspace code
513 - Another approach is to utilize fs-verity builtin signature
514 verification in conjunction with the IPE LSM, which supports defining
515 a kernel-enforced, system-wide authentication policy that allows only
516 files with a verified fs-verity builtin signature to perform certain
519 Please refer to :doc:`IPE admin guide </admin-guide/LSM/ipe>` for
522 - A file's builtin signature can only be set at the same time that
523 fs-verity is being enabled on the file. Changing or deleting the
524 builtin signature later requires re-creating the file.
526 - Builtin signature verification uses the same set of public keys for
527 all fs-verity enabled files on the system. Different keys cannot be
530 - The sysctl fs.verity.require_signatures applies system-wide.
531 Setting it to 1 only works when all users of fs-verity on the system
533 fs-verity from being used in cases where it would be helpful.
535 - Builtin signature verification can only use signature algorithms
540 - fs-verity builtin signatures are in PKCS#7 format, and the public
541 keys are in X.509 format. These formats are commonly used,
542 including by some other kernel features (which is why the fs-verity
549 fs-verity users who do not need advanced features of X.509 and
551 Ed25519 keys and signatures, and verifying signatures in userspace.
553 fs-verity users who choose to use X.509 and PKCS#7 anyway should
554 still consider that verifying those signatures in userspace is more
555 flexible (for other reasons mentioned earlier in this document) and
557 and its associated increase in kernel attack surface. In some cases
562 Note: IMA appraisal, which supports fs-verity, does not use PKCS#7
569 fs-verity is supported by several filesystems, described below. The
570 CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on
576 methods to read and write the verity metadata to a filesystem-specific
577 location, including the Merkle tree blocks and
578 ``fsverity_descriptor``. Filesystems must also call functions in
583 ----
585 ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.
588 been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
595 (typically 4096 bytes). In Linux v6.3, this limitation was removed.
597 ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It
601 fs-verity. In this case, the plaintext data is verified rather than
602 the ciphertext. This is necessary in order to make the fs-verity file
605 ext4 stores the verity metadata (Merkle tree and fsverity_descriptor)
612 support paging multi-gigabyte xattrs into memory, and to support
616 ext4 only allows verity on extent-based files.
619 ----
621 f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.
624 been formatted with ``-O verity``.
626 f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
630 Like ext4, f2fs stores the verity metadata (Merkle tree and
634 which usually wouldn't be enough for even a single Merkle tree block.
640 -----
642 btrfs supports fs-verity since Linux v5.15. Verity-enabled inodes are
644 in separate btree items.
650 --------------
652 fs-verity ensures that all reads of a verity file's data are verified,
661 For filesystems using Linux's pagecache, the ``->read_folio()`` and
662 ``->readahead()`` methods must be modified to verify folios before
663 they are marked Uptodate. Merely hooking ``->read_iter()`` would be
664 insufficient, since ``->read_iter()`` is not used for memory maps.
673 fsverity_verify_blocks() returns false if verification failed; in this
679 In principle, verifying a data block requires verifying the entire
680 path in the Merkle tree from the data block to the root hash.
682 Therefore, fsverity_verify_blocks() only ascends the tree reading hash
683 blocks until an already-verified hash block is seen. It then verifies
686 This optimization, which is also used by dm-verity, results in
688 127 in 128 times for 4K blocks and SHA-256) the hash block from the
689 bottom level of the tree will already be cached and checked from
695 Block device based filesystems (e.g. ext4 and f2fs) in Linux also use
699 filesystems to support fs-verity, fs/verity/ also provides a function
700 fsverity_verify_bio() which verifies all data blocks in a bio.
704 support this, these filesystems allocate a "post-read context" for
705 each bio and store it in ``->bi_private``::
722 ``->readahead()`` simply zeroes hole blocks and considers the
723 corresponding data to be up-to-date; no bios are issued. To prevent
724 this case from bypassing fs-verity, filesystems use
728 direct I/O would bypass fs-verity.
734 fs-verity can be found at:
736 https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git
738 See the README.md file in the fsverity-utils source tree for details,
739 including examples of setting up fs-verity protected files.
744 To test fs-verity, use xfstests. For example, using `kvm-xfstests
745 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
747 kvm-xfstests -c ext4,f2fs,btrfs -g verity
752 This section answers frequently asked questions about fs-verity that
753 weren't already directly answered in other parts of this document.
755 :Q: Why isn't fs-verity part of IMA?
756 :A: fs-verity and IMA (Integrity Measurement Architecture) have
757 different focuses. fs-verity is a filesystem-level mechanism for
758 hashing individual files using a Merkle tree. In contrast, IMA
759 specifies a system-wide policy that specifies which files are
763 IMA supports the fs-verity hashing mechanism as an alternative
765 security benefits of the Merkle tree based hash. However, it
766 doesn't make sense to force all uses of fs-verity to be through
767 IMA. fs-verity already meets many users' needs even as a
771 :Q: Isn't fs-verity useless because the attacker can just modify the
772 hashes in the Merkle tree, which is stored on-disk?
773 :A: To verify the authenticity of an fs-verity file you must verify
774 the authenticity of the "fs-verity file digest", which
775 incorporates the root hash of the Merkle tree. See `Use cases`_.
777 :Q: Isn't fs-verity useless because the attacker can just replace a
778 verity file with a non-verity one?
779 :A: See `Use cases`_. In the initial use case, it's really trusted
780 userspace code that authenticates the files; fs-verity is just a
782 userspace code will consider non-verity files to be inauthentic.
784 :Q: Why does the Merkle tree need to be stored on-disk? Couldn't you
786 :A: If the Merkle tree wasn't stored on-disk, then you'd have to
787 compute the entire tree when the file is first accessed, even if
789 how Merkle tree hashing works. To verify a leaf node, you need to
792 node isn't stored on-disk, you have to compute it by hashing its
795 That defeats most of the point of doing a Merkle tree-based hash,
800 It's true that an in-memory Merkle tree could still provide the
803 hash page gets evicted (you can't pin the entire Merkle tree into
804 memory, since it may be very large), in order to restore it you
805 again need to hash everything below it in the tree. This again
806 defeats most of the point of doing a Merkle tree-based hash, since
807 a single block read could trigger re-hashing gigabytes of data.
812 leaf nodes of the Merkle tree. It's true that the tree can be
816 SHA-256 and 4K blocks). For the exact same reason, by storing
818 tree, so you might as well simply store the whole tree.
820 :Q: Can the Merkle tree be built ahead of time, e.g. distributed as
828 :Q: Why doesn't fs-verity support writes?
831 fs-verity. Write support would require:
833 - A way to maintain consistency between the data and hashes,
837 copy-on-write, and log-structured volume. But it's very hard to
841 - Rebuilding the Merkle tree after every write, which would be
846 Compare it to dm-verity vs. dm-integrity. dm-verity is very
847 simple: the kernel just verifies read-only data against a
848 read-only Merkle tree. In contrast, dm-integrity supports writes
850 full-device authentication since it authenticates each sector
852 make sense for the same device-mapper target to support these two
853 very different cases; the same applies to fs-verity.
858 read-only, but also prevent the file from being deleted, renamed,
860 properties are unwanted for fs-verity, so reusing the immutable
866 An xattr should really just be an xattr on-disk, not an API to
867 e.g. magically trigger construction of a Merkle tree.
869 :Q: Does fs-verity support remote filesystems?
870 :A: So far all filesystems that have implemented fs-verity support are
871 local filesystems, but in principle any filesystem that can store
872 per-file verity metadata can support fs-verity, regardless of
880 :Q: Why is anything filesystem-specific at all? Shouldn't fs-verity
885 - To prevent bypassing verification, folios must not be marked
888 ``->readahead()``. Therefore, currently it's not possible for
892 - It would require defining a filesystem-independent way to store
894 because (a) the Merkle tree may be gigabytes, but many
897 encrypt xattrs, yet the Merkle tree *must* be encrypted when the
901 So the verity metadata would have to be stored in an actual
906 having it be in the same file would break applications unless
910 - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's