Lines Matching +full:files +full:- +full:based
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
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,
58 (APK) files, for example. These typically contain many translations,
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
73 authenticating the files is up to userspace. However, to meet some
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
131 take a long time to execute on large files, and it is interruptible by
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 -----
233 the file has fs-verity enabled. This can perform better than
235 opening the file, and opening verity files can be expensive.
237 Accessing verity files
241 non-verity one, with the following exceptions:
243 - Verity files are readonly. They cannot be opened for writing or
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
251 I/O on such files will fall back to buffered I/O.
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,
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
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.
369 When set to 1, the kernel requires that all verity files have a
382 fs-verity's built-in signature verification support is meant as a
384 authenticity protection for verity files, as an alternative to doing
385 the signature verification in userspace or using IMA-appraisal.
388 files being swapped around.
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.
411 To create verity files on an ext4 filesystem, the filesystem must have
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
429 i_size. This approach works because (a) verity files are readonly,
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.
447 To create verity files on an f2fs filesystem, the filesystem must have
448 been formatted with ``-O verity``.
450 f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
461 Also, f2fs doesn't support enabling verity on files that currently
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.
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
547 ext4 and f2fs disable direct I/O on verity files, since otherwise
548 direct I/O would bypass fs-verity. (They also do the same for
549 encrypted files.)
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
579 hashing individual files using a Merkle tree. In contrast, IMA
580 specifies a system-wide policy that specifies which files are
584 IMA is planned to support the fs-verity hashing mechanism as an
586 performance and security benefits of the Merkle tree based hash.
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
645 wasn't a critical use case. Files are usually installed once and
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 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.
676 :Q: Since verity files are immutable, why isn't the immutable bit set?
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