Documentation/filesystems/fsverity.rst

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 - Trusted userspace code in combination with `Built-in signature
96 --------------------
98 The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file.  It takes
117 - ``version`` must be 1.
118 - ``hash_algorithm`` must be the identifier for the hash algorithm to
119   use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256.  See
121 - ``block_size`` is the Merkle tree block size, in bytes.  In Linux
126 - ``salt_size`` is the size of the salt in bytes, or 0 if no salt is
130 - ``salt_ptr`` is the pointer to the salt, or NULL if no salt is
132 - ``sig_size`` is the size of the builtin signature in bytes, or 0 if no
135 - ``sig_ptr``  is the pointer to the builtin signature, or NULL if no
137   if the `Built-in signature verification`_ feature is being used.  It
140 - All reserved fields must be zeroed.
143 the file and persist it to a filesystem-specific location associated
162 - ``EACCES``: the process does not have write access to the file
163 - ``EBADMSG``: the builtin signature is malformed
164 - ``EBUSY``: this ioctl is already running on the file
165 - ``EEXIST``: the file already has verity enabled
166 - ``EFAULT``: the caller provided inaccessible memory
167 - ``EFBIG``: the file is too large to enable verity on
168 - ``EINTR``: the operation was interrupted by a fatal signal
169 - ``EINVAL``: unsupported version, hash algorithm, or block size; or
172 - ``EISDIR``: the file descriptor refers to a directory
173 - ``EKEYREJECTED``: the builtin signature doesn't match the file
174 - ``EMSGSIZE``: the salt or builtin signature is too long
175 - ``ENOKEY``: the ".fs-verity" keyring doesn't contain the certificate
177 - ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not
179   for SHA-512, missing CONFIG_CRYPTO_SHA512).
180 - ``ENOTTY``: this type of filesystem does not implement fs-verity
181 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
183   feature enabled on it; or the filesystem does not support fs-verity
185 - ``EPERM``: the file is append-only; or, a builtin signature is
187 - ``EROFS``: the filesystem is read-only
188 - ``ETXTBSY``: someone has the file open for writing.  This can be the
193 ---------------------
196 The fs-verity file digest is a cryptographic digest that identifies
198 a Merkle tree and is different from a traditional full-file digest.
200 This ioctl takes in a pointer to a variable-length structure::
209 initialized to the number of bytes allocated for the variable-length
215 - ``digest_algorithm`` will be the hash algorithm used for the file
217 - ``digest_size`` will be the size of the digest in bytes, e.g. 32
218   for SHA-256.  (This can be redundant with ``digest_algorithm``.)
219 - ``digest`` will be the actual bytes of the digest.
226 - ``EFAULT``: the caller provided inaccessible memory
227 - ``ENODATA``: the file is not a verity file
228 - ``ENOTTY``: this type of filesystem does not implement fs-verity
229 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
232 - ``EOVERFLOW``: the digest is longer than the specified
236 ---------------------------
243 fs-verity compatible verification of the file.  This only makes sense
247 This is a fairly specialized use case, and most fs-verity users won't
266 - ``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the
272 - ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity
273   descriptor.  See `fs-verity descriptor`_.
275 - ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the builtin signature
276   which was passed to FS_IOC_ENABLE_VERITY, if any.  See `Built-in
283 cast to a 64-bit integer.  ``__reserved`` must be 0.  On success, the
291 implement fs-verity compatible verification anyway (though absent a
298 - ``EFAULT``: the caller provided inaccessible memory
299 - ``EINTR``: the ioctl was interrupted before any data was read
300 - ``EINVAL``: reserved fields were set, or ``offset + length``
302 - ``ENODATA``: the file is not a verity file, or
305 - ``ENOTTY``: this type of filesystem does not implement fs-verity, or
307 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
312 ---------------
314 The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
315 can also be used to check whether a file has fs-verity enabled or not.
318 The verity flag is not settable via FS_IOC_SETFLAGS.  You must use
322 -----
325 the file has fs-verity enabled.  This can perform better than
335 non-verity one, with the following exceptions:
337 - Verity files are readonly.  They cannot be opened for writing or
341   allowed, since these are not measured by fs-verity.  Verity files
344 - Direct I/O is not supported on verity files.  Attempts to use direct
347 - DAX (Direct Access) is not supported on verity files, because this
350 - Reads of data that doesn't match the verity Merkle tree will fail
353 - If the sysctl "fs.verity.require_signatures" is set to 1 and the
354   file is not signed by a key in the ".fs-verity" keyring, then
355   opening the file will fail.  See `Built-in signature verification`_.
359 its "verity"-ness.  fs-verity is primarily meant for files like
365 This section describes how fs-verity hashes the file contents using a
368 that support fs-verity.
371 compute fs-verity file digests itself, e.g. in order to sign files.
376 -----------
380 zero-padded if needed.  Each block is then hashed, producing the first
382 into 'blocksize'-byte blocks (zero-padding the ends as needed) and
393 If a salt was specified, then it's zero-padded to the closest multiple
395 64 bytes for SHA-256 or 128 bytes for SHA-512.  The padded salt is
404 Example: in the recommended configuration of SHA-256 and 4K blocks,
413 fs-verity descriptor
414 --------------------
418 is exactly the top-level hash block of the first file.  Ambiguities
421 To solve this problem, the fs-verity file digest is actually computed
437 Built-in signature verification
440 CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds supports for in-kernel
441 verification of fs-verity builtin signatures.
444 It is not the only way to do signatures with fs-verity, and the
451 1. At boot time, the kernel creates a keyring named ".fs-verity".  The
456    detached signature in DER format of the file's fs-verity digest.
460    in the ".fs-verity" keyring.
467 is the fs-verity file digest in the following format::
476 That's it.  It should be emphasized again that fs-verity builtin
477 signatures are not the only way to do signatures with fs-verity.  See
478 `Use cases`_ for an overview of ways in which fs-verity can be used.
479 fs-verity builtin signatures have some major limitations that should
482 - Builtin signature verification does *not* make the kernel enforce
483   that any files actually have fs-verity enabled.  Thus, it is not a
486   code to explicitly check whether files have fs-verity enabled with a
488   fs.verity.require_signatures=1, just checking whether fs-verity is
493 - A file's builtin signature can only be set at the same time that
494   fs-verity is being enabled on the file.  Changing or deleting the
495   builtin signature later requires re-creating the file.
497 - Builtin signature verification uses the same set of public keys for
498   all fs-verity enabled files on the system.  Different keys cannot be
501 - The sysctl fs.verity.require_signatures applies system-wide.
502   Setting it to 1 only works when all users of fs-verity on the system
504   fs-verity from being used in cases where it would be helpful.
506 - Builtin signature verification can only use signature algorithms
511 - fs-verity builtin signatures are in PKCS#7 format, and the public
513   including by some other kernel features (which is why the fs-verity
514   builtin signatures use them), and are very feature rich.
520   fs-verity users who do not need advanced features of X.509 and
524   fs-verity users who choose to use X.509 and PKCS#7 anyway should
529   it can even be necessary, since advanced X.509 and PKCS#7 features
533   Note: IMA appraisal, which supports fs-verity, does not use PKCS#7
535   here.  IMA appraisal does use X.509.
540 fs-verity is supported by several filesystems, described below.  The
541 CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on
547 methods to read and write the verity metadata to a filesystem-specific
554 ----
556 ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.
559 been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
568 ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files.  It
572 fs-verity.  In this case, the plaintext data is verified rather than
573 the ciphertext.  This is necessary in order to make the fs-verity file
583 support paging multi-gigabyte xattrs into memory, and to support
587 ext4 only allows verity on extent-based files.
590 ----
592 f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.
595 been formatted with ``-O verity``.
597 f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
611 -----
613 btrfs supports fs-verity since Linux v5.15.  Verity-enabled inodes are
621 --------------
623 fs-verity ensures that all reads of a verity file's data are verified,
632 For filesystems using Linux's pagecache, the ``->read_folio()`` and
633 ``->readahead()`` methods must be modified to verify folios before
634 they are marked Uptodate.  Merely hooking ``->read_iter()`` would be
635 insufficient, since ``->read_iter()`` is not used for memory maps.
654 blocks until an already-verified hash block is seen.  It then verifies
657 This optimization, which is also used by dm-verity, results in
659 127 in 128 times for 4K blocks and SHA-256) the hash block from the
666 Block device based filesystems (e.g. ext4 and f2fs) in Linux also use
670 filesystems to support fs-verity, fs/verity/ also provides a function
675 support this, these filesystems allocate a "post-read context" for
676 each bio and store it in ``->bi_private``::
693 ``->readahead()`` simply zeroes hole blocks and considers the
694 corresponding data to be up-to-date; no bios are issued.  To prevent
695 this case from bypassing fs-verity, filesystems use
699 direct I/O would bypass fs-verity.
705 fs-verity can be found at:
707 	https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git
709 See the README.md file in the fsverity-utils source tree for details,
710 including examples of setting up fs-verity protected files.
715 To test fs-verity, use xfstests.  For example, using `kvm-xfstests
716 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
718     kvm-xfstests -c ext4,f2fs,btrfs -g verity
723 This section answers frequently asked questions about fs-verity that
726 :Q: Why isn't fs-verity part of IMA?
727 :A: fs-verity and IMA (Integrity Measurement Architecture) have
728     different focuses.  fs-verity is a filesystem-level mechanism for
730     specifies a system-wide policy that specifies which files are
734     IMA supports the fs-verity hashing mechanism as an alternative
737     doesn't make sense to force all uses of fs-verity to be through
738     IMA.  fs-verity already meets many users' needs even as a
742 :Q: Isn't fs-verity useless because the attacker can just modify the
743     hashes in the Merkle tree, which is stored on-disk?
744 :A: To verify the authenticity of an fs-verity file you must verify
745     the authenticity of the "fs-verity file digest", which
746     incorporates the root hash of the Merkle tree.  See `Use cases`_.
748 :Q: Isn't fs-verity useless because the attacker can just replace a
749     verity file with a non-verity one?
750 :A: See `Use cases`_.  In the initial use case, it's really trusted
751     userspace code that authenticates the files; fs-verity is just a
753     userspace code will consider non-verity files to be inauthentic.
755 :Q: Why does the Merkle tree need to be stored on-disk?  Couldn't you
757 :A: If the Merkle tree wasn't stored on-disk, then you'd have to
763     node isn't stored on-disk, you have to compute it by hashing its
766     That defeats most of the point of doing a Merkle tree-based hash,
771     It's true that an in-memory Merkle tree could still provide the
777     defeats most of the point of doing a Merkle tree-based hash, since
778     a single block read could trigger re-hashing gigabytes of data.
787     SHA-256 and 4K blocks).  For the exact same reason, by storing
795     wasn't a critical use case.  Files are usually installed once and
799 :Q: Why doesn't fs-verity support writes?
802     fs-verity.  Write support would require:
804     - A way to maintain consistency between the data and hashes,
808       copy-on-write, and log-structured volume.  But it's very hard to
812     - Rebuilding the Merkle tree after every write, which would be
817     Compare it to dm-verity vs. dm-integrity.  dm-verity is very
818     simple: the kernel just verifies read-only data against a
819     read-only Merkle tree.  In contrast, dm-integrity supports writes
821     full-device authentication since it authenticates each sector
823     make sense for the same device-mapper target to support these two
824     very different cases; the same applies to fs-verity.
829     read-only, but also prevent the file from being deleted, renamed,
831     properties are unwanted for fs-verity, so reusing the immutable
834 :Q: Why does the API use ioctls instead of setxattr() and getxattr()?
837     An xattr should really just be an xattr on-disk, not an API to
840 :Q: Does fs-verity support remote filesystems?
841 :A: So far all filesystems that have implemented fs-verity support are
843     per-file verity metadata can support fs-verity, regardless of
851 :Q: Why is anything filesystem-specific at all?  Shouldn't fs-verity
856     - To prevent bypassing verification, folios must not be marked
859       ``->readahead()``.  Therefore, currently it's not possible for
863     - It would require defining a filesystem-independent way to store
881     - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's