Lines Matching +full:d +full:- +full:cache +full:- +full:block +full:- +full:size
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>`_
20 but works on files rather than block devices. On regular files on
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
32 constant time, regardless of the file size.
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
111 must be equal to the system page size, which is usually 4096 bytes.
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
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
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.
206 regardless of the size of the file.
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 -----
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 -----------
285 The file contents is divided into blocks, where the block size is
286 configurable but is usually 4096 bytes. The end of the last block is
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
291 proceeds up the tree until only a single block remains. The hash of
292 this block is the "Merkle tree root hash".
294 If the file fits in one block and is nonempty, then the "Merkle tree
295 root hash" is simply the hash of the single data block. If the file
300 If a salt was specified, then it's zero-padded to the closest multiple
301 of the input size of the hash algorithm's compression function, e.g.
302 64 bytes for SHA-256 or 128 bytes for SHA-512. The padded salt is
303 prepended to every data or Merkle tree block that is hashed.
305 The purpose of the block padding is to cause every hash to be taken
311 Example: in the recommended configuration of SHA-256 and 4K blocks,
312 128 hash values fit in each block. Thus, each level of the Merkle
314 large files the Merkle tree's size converges to approximately 1/127 of
315 the original file size. However, for small files, the padding is
320 fs-verity descriptor
321 --------------------
325 is exactly the top-level hash block of the first file. Ambiguities
326 also arise from the convention of padding to the next block boundary.
330 Merkle tree root hash as well as other fields such as the file size::
335 __u8 log_blocksize; /* log2 of size of data and tree blocks */
336 __u8 salt_size; /* size of salt in bytes; 0 if none */
338 __le64 data_size; /* size of file the Merkle tree is built over */
340 __u8 salt[32]; /* salt prepended to each hashed block */
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
417 feature when its block size is equal to PAGE_SIZE (often 4096 bytes).
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
439 block size, filesystem block size, and page size are all the same. It
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.
458 which wouldn't be enough for even a single Merkle tree block.
460 Currently, f2fs verity only supports a Merkle tree block size of 4096.
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.
498 Merkle tree block size is equal to PAGE_SIZE (often 4096 bytes).
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
513 Block device based filesystems
516 Block device based filesystems (e.g. ext4 and f2fs) in Linux also use
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()``
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.
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
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
717 filesystem block, and (b) ext4 and f2fs encryption doesn't
731 - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's