Lines Matching +full:d +full:- +full:cache +full:- +full:sets
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 and f2fs
15 filesystems. Like fscrypt, not too much filesystem-specific code is
16 needed to support fs-verity.
18 fs-verity is similar to `dm-verity
19 <https://www.kernel.org/doc/Documentation/device-mapper/verity.txt>`_
21 filesystems supporting fs-verity, userspace can execute an ioctl that
23 it to a filesystem-specific location associated with the file.
31 that fs-verity is enforcing for the file. This ioctl executes in
34 fs-verity is essentially a way to hash a file in constant time,
41 By itself, the base fs-verity feature only provides integrity
42 protection, i.e. detection of accidental (non-malicious) corruption.
44 However, because fs-verity makes retrieving the file hash extremely
50 read-only partition that is itself authenticated by dm-verity) can
51 authenticate the contents of an fs-verity file by using the
55 A standard file hash could be used instead of fs-verity. However,
63 Unlike an ahead-of-time hash, fs-verity also re-verifies data each
67 fs-verity does not replace or obsolete dm-verity. dm-verity should
68 still be used on read-only filesystems. fs-verity is for files that
69 must live on a read-write filesystem because they are independently
70 updated and potentially user-installed, so dm-verity cannot be used.
72 The base fs-verity feature is a hashing mechanism only; actually
74 users' needs, fs-verity optionally supports a simple signature
76 that 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
84 --------------------
86 The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes
106 - ``version`` must be 1.
107 - ``hash_algorithm`` must be the identifier for the hash algorithm to
110 - ``block_size`` must be the Merkle tree block size. Currently, this
114 - ``salt_size`` is the size of the salt in bytes, or 0 if no salt is
118 - ``salt_ptr`` is the pointer to the salt, or NULL if no salt is
120 - ``sig_size`` is the size of the signature in bytes, or 0 if no
122 arbitrarily) limited to 16128 bytes. See `Built-in signature
124 - ``sig_ptr`` is the pointer to the signature, or NULL if no
126 - All reserved fields must be zeroed.
129 the file and persist it to a filesystem-specific location associated
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
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
162 - ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not
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
168 feature enabled on it; or the filesystem does not support fs-verity
170 - ``EPERM``: the file is append-only; or, a signature is required and
172 - ``EROFS``: the filesystem is read-only
173 - ``ETXTBSY``: someone has the file open for writing. This can be the
178 ---------------------
184 This ioctl takes in a pointer to a variable-length structure::
193 initialized to the number of bytes allocated for the variable-length
199 - ``digest_algorithm`` will be the hash algorithm used for the file
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.
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
216 - ``EOVERFLOW``: the digest is longer than the specified
220 ---------------
222 The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
223 can also be used to check whether a file has fs-verity enabled or not.
230 -----
232 Since Linux v5.5, the statx() system call sets STATX_ATTR_VERITY if
233 the file has fs-verity enabled. This can perform better than
241 non-verity one, with the following exceptions:
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
247 allowed, since these are not measured by fs-verity. Verity files
250 - Direct I/O is not supported on verity files. Attempts to use direct
253 - DAX (Direct Access) is not supported on verity files, because this
256 - Reads of data that doesn't match the verity Merkle tree will fail
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
266 its "verity"-ness. fs-verity is primarily meant for files like
272 This section describes how fs-verity hashes the file contents using a
275 filesystems that support fs-verity.
283 -----------
287 zero-padded if needed. Each block is then hashed, producing the first
289 into 'blocksize'-byte blocks (zero-padding the ends as needed) and
300 If a salt was specified, then it's zero-padded to the closest multiple
302 64 bytes for SHA-256 or 128 bytes for SHA-512. The padded salt is
311 Example: in the recommended configuration of SHA-256 and 4K blocks,
320 fs-verity descriptor
321 --------------------
325 is exactly the top-level hash block of the first file. Ambiguities
348 Built-in signature verification
351 With CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y, fs-verity supports putting
355 1. At fs-verity module initialization time, a keyring ".fs-verity" is
366 certificates in the ".fs-verity" keyring.
382 fs-verity's built-in signature verification support is meant as a
385 the signature verification in userspace or using IMA-appraisal.
393 fs-verity is currently supported by the ext4 and f2fs filesystems.
394 The CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity
400 methods to read and write the verity metadata to a filesystem-specific
407 ----
409 ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.
412 been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
419 ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It
423 fs-verity. In this case, the plaintext data is verified rather than
434 support paging multi-gigabyte xattrs into memory, and to support
440 also only supports extent-based files.
443 ----
445 f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.
448 been formatted with ``-O verity``.
450 f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
468 --------------
470 fs-verity ensures that all reads of a verity file's data are verified,
479 For filesystems using Linux's pagecache, the ``->readpage()`` and
480 ``->readpages()`` methods must be modified to verify pages before they
481 are marked Uptodate. Merely hooking ``->read_iter()`` would be
482 insufficient, since ``->read_iter()`` is not used for memory maps.
502 efficiency the filesystem may cache the hash pages. Therefore,
504 an already-verified hash page is seen, as indicated by the PageChecked
507 This optimization, which is also used by dm-verity, results in
509 127 in 128 times for 4K blocks and SHA-256) the hash page from the
520 filesystems to support fs-verity, fs/verity/ also provides a function
525 support this, these filesystems allocate a "post-read context" for
526 each bio and store it in ``->bi_private``::
542 Files on ext4 and f2fs may contain holes. Normally, ``->readpages()``
543 simply zeroes holes and sets the corresponding pages Uptodate; no bios
544 are issued. To prevent this case from bypassing fs-verity, these
548 direct I/O would bypass fs-verity. (They also do the same for
555 fs-verity can be found at:
557 https://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/fsverity-utils.git
559 See the README.md file in the fsverity-utils source tree for details,
560 including examples of setting up fs-verity protected files.
565 To test fs-verity, use xfstests. For example, using `kvm-xfstests
566 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
568 kvm-xfstests -c ext4,f2fs -g verity
573 This section answers frequently asked questions about fs-verity that
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
580 specifies a system-wide policy that specifies which files are
584 IMA is planned to support the fs-verity hashing mechanism as an
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
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
598 :Q: Isn't fs-verity useless because the attacker can just replace a
599 verity file with a non-verity one?
601 userspace code that authenticates the files; fs-verity is just a
603 userspace code will consider non-verity files to be inauthentic.
605 :Q: Why does the Merkle tree need to be stored on-disk? Couldn't you
607 :A: If the Merkle tree wasn't stored on-disk, then you'd have to
613 node isn't stored on-disk, you have to compute it by hashing its
616 That defeats most of the point of doing a Merkle tree-based hash,
621 It's true that an in-memory Merkle tree could still provide the
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.
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
649 :Q: Why doesn't fs-verity support writes?
652 fs-verity. Write support would require:
654 - A way to maintain consistency between the data and hashes,
658 copy-on-write, and log-structured volume. But it's very hard to
662 - Rebuilding the the Merkle tree after every write, which would be
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
671 full-device authentication since it authenticates each sector
673 make sense for the same device-mapper target to support these two
674 very different cases; the same applies to fs-verity.
679 read-only, but also prevent the file from being deleted, renamed,
681 properties are unwanted for fs-verity, so reusing the immutable
687 An xattr should really just be an xattr on-disk, not an API to
690 :Q: Does fs-verity support remote filesystems?
692 principle any filesystem that can store per-file verity metadata
693 can support fs-verity, regardless of whether it's local or remote.
701 :Q: Why is anything filesystem-specific at all? Shouldn't fs-verity
706 - To prevent bypassing verification, pages must not be marked
709 ``->readpages()``. Therefore, currently it's not possible for
713 - It would require defining a filesystem-independent way to store
731 - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's