Lines Matching +full:use +full:- +full:advanced +full:- +full:sector +full:- +full:protection
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
13 hook into to support transparent integrity and authenticity protection
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/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.
29 Userspace can use another ioctl to retrieve the root hash (actually
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
34 fs-verity is essentially a way to hash a file in constant time,
38 Use cases
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
47 (logging file hashes before use).
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
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
76 from a read-only partition that uses dm-verity) and that wants to
79 retrieving its fs-verity digest using `FS_IOC_MEASURE_VERITY`_, then
83 - Integrity Measurement Architecture (IMA). IMA supports fs-verity
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
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
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
150 - All reserved fields must be zeroed.
153 the file and persist it to a filesystem-specific location associated
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
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
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.
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
276 - ``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the
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
293 cast to a 64-bit integer. ``__reserved`` must be 0. On success, the
301 implement fs-verity compatible verification anyway (though absent a
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.
328 The verity flag is not settable via FS_IOC_SETFLAGS. You must use
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`_.
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
378 that support fs-verity.
381 compute fs-verity file digests itself, e.g. in order to sign files.
386 -----------
390 zero-padded if needed. Each block is then hashed, producing the first
392 into 'blocksize'-byte blocks (zero-padding the ends as needed) and
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
414 Example: in the recommended configuration of SHA-256 and 4K blocks,
423 fs-verity descriptor
424 --------------------
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
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.
470 in the ".fs-verity" keyring. This verification happens as long as the
474 that contain a verified built-in fsverity signature.
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
507 - Another approach is to utilize fs-verity builtin signature
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
536 including by some other kernel features (which is why the fs-verity
537 builtin signatures use them), and are very feature rich.
543 fs-verity users who do not need advanced features of X.509 and
547 fs-verity users who choose to use X.509 and PKCS#7 anyway should
552 it can even be necessary, since advanced X.509 and PKCS#7 features
556 Note: IMA appraisal, which supports fs-verity, does not use PKCS#7
558 here. IMA appraisal does use X.509.
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
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
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
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.
634 -----
636 btrfs supports fs-verity since Linux v5.15. Verity-enabled inodes are
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.
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
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
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
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
753 specifies a system-wide policy that specifies which files are
757 IMA supports the fs-verity hashing mechanism as an alternative
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
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
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.
810 SHA-256 and 4K blocks). For the exact same reason, by storing
818 wasn't a critical use case. Files are usually installed once and
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
857 :Q: Why does the API use ioctls instead of setxattr() and getxattr()?
860 An xattr should really just be an xattr on-disk, not an API to
863 :Q: Does fs-verity support remote filesystems?
864 :A: So far all filesystems that have implemented fs-verity support are
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
904 - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's