Lines Matching +full:boot +full:- +full:page +full:- +full:step
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/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.
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,
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
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
131 - ``block_size`` is the Merkle tree block size, in bytes. In Linux
133 1024 and the minimum of the system page size and the filesystem
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
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.
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
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
556 Note: IMA appraisal, which supports fs-verity, does not use PKCS#7
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
588 mounted when its block size was equal to the system page size
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
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``::
710 postprocessing step the filesystem enqueues the bio_post_read_ctx on a
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
771 :Q: Isn't fs-verity useless because the attacker can just replace a
772 verity file with a non-verity one?
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
797 hash page gets evicted (you can't pin the entire Merkle tree into
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
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
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