Documentation/filesystems/fsverity.rst

6 fs-verity: read-only file-based authenticity protection
12 fs-verity (``fs/verity/``) is a support layer that filesystems can
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>`_
21 filesystems supporting fs-verity, userspace can execute an ioctl that
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, the base fs-verity feature only provides integrity
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
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
86 The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file.  It takes
130 with the file, then mark the file as a verity file.  This ioctl may
139 after verity is enabled, and to guarantee that the file's contents are
143 verity file.  On failure (including the case of interruption by a
151 - ``EEXIST``: the file already has verity enabled
160 - ``ENOKEY``: the fs-verity keyring doesn't contain the certificate
162 - ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not
165 - ``ENOTTY``: this type of filesystem does not implement fs-verity
166 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
167   support; or the filesystem superblock has not had the 'verity'
168   feature enabled on it; or the filesystem does not support fs-verity
180 The FS_IOC_MEASURE_VERITY ioctl retrieves the digest of a verity file.
181 The fs-verity file digest is a cryptographic digest that identifies
212 - ``ENODATA``: the file is not a verity file
213 - ``ENOTTY``: this type of filesystem does not implement fs-verity
214 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
215   support, or the filesystem superblock has not had the 'verity'
223 The FS_IOC_READ_VERITY_METADATA ioctl reads verity metadata from a
224 verity file.  This ioctl is available since Linux v5.12.
226 This ioctl allows writing a server program that takes a verity file
228 fs-verity compatible verification of the file.  This only makes sense
232 This is a fairly specialized use case, and most fs-verity users won't
257 - ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity
258   descriptor.  See `fs-verity descriptor`_.
276 implement fs-verity compatible verification anyway (though absent a
287 - ``ENODATA``: the file is not a verity file, or
290 - ``ENOTTY``: this type of filesystem does not implement fs-verity, or
292 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
293   support, or the filesystem superblock has not had the 'verity'
299 The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
300 can also be used to check whether a file has fs-verity enabled or not.
303 The verity flag is not settable via FS_IOC_SETFLAGS.  You must use
310 the file has fs-verity enabled.  This can perform better than
312 opening the file, and opening verity files can be expensive.
314 Accessing verity files
317 Applications can transparently access a verity file just like a
318 non-verity one, with the following exceptions:
324   allowed, since these are not measured by fs-verity.  Verity files
327 - Direct I/O is not supported on verity files.  Attempts to use direct
330 - DAX (Direct Access) is not supported on verity files, because this
333 - Reads of data that doesn't match the verity Merkle tree will fail
336 - If the sysctl "fs.verity.require_signatures" is set to 1 and the
337   file is not signed by a key in the fs-verity keyring, then opening
341 verity file is copied, or is backed up and restored, then it will lose
342 its "verity"-ness.  fs-verity is primarily meant for files like
348 This section describes how fs-verity hashes the file contents using a
351 that support fs-verity.
354 compute fs-verity file digests itself, e.g. in order to sign files.
396 fs-verity descriptor
404 To solve this problem, the fs-verity file digest is actually computed
423 With CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y, fs-verity supports putting
427 1. At fs-verity module initialization time, a keyring ".fs-verity" is
434    detached signature in DER format of the file's fs-verity digest.
438    in the ".fs-verity" keyring.
440 3. A new sysctl "fs.verity.require_signatures" is made available.
441    When set to 1, the kernel requires that all verity files have a
444 fs-verity file digests must be signed in the following format, which
454 fs-verity's built-in signature verification support is meant as a
456 authenticity protection for verity files, as an alternative to doing
459 that the verity bit is set, and there is no protection against verity
465 fs-verity is currently supported by the ext4 and f2fs filesystems.
466 The CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity
470 ``fs/verity/`` support layer and filesystems.  Briefly, filesystems
472 methods to read and write the verity metadata to a filesystem-specific
475 ``fs/verity/`` at certain times, such as when a file is opened or when
481 ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.
483 To create verity files on an ext4 filesystem, the filesystem must have
484 been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
485 it.  "verity" is an RO_COMPAT filesystem feature, so once set, old
488 currently ext4 only supports mounting a filesystem with the "verity"
491 ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files.  It
495 fs-verity.  In this case, the plaintext data is verified rather than
496 the ciphertext.  This is necessary in order to make the fs-verity file
499 ext4 stores the verity metadata (Merkle tree and fsverity_descriptor)
501 i_size.  This approach works because (a) verity files are readonly,
507 encrypting xattrs.  Note that the verity metadata *must* be encrypted
510 Currently, ext4 verity only supports the case where the Merkle tree
517 f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.
519 To create verity files on an f2fs filesystem, the filesystem must have
520 been formatted with ``-O verity``.
522 f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
526 Like ext4, f2fs stores the verity metadata (Merkle tree and
532 Currently, f2fs verity only supports a Merkle tree block size of 4096.
533 Also, f2fs doesn't support enabling verity on files that currently
542 fs-verity ensures that all reads of a verity file's data are verified,
556 Therefore, fs/verity/ provides a function fsverity_verify_page() which
557 verifies a page that has been read into the pagecache of a verity
579 This optimization, which is also used by dm-verity, results in
592 filesystems to support fs-verity, fs/verity/ also provides a function
595 ext4 and f2fs also support encryption.  If a verity file is also
608 verity, or both is enabled.  After the bio completes, for each needed
611 verification.  Finally, pages where no decryption or verity error
616 are issued.  To prevent this case from bypassing fs-verity, these
619 ext4 and f2fs disable direct I/O on verity files, since otherwise
620 direct I/O would bypass fs-verity.  (They also do the same for
627 fs-verity can be found at:
632 including examples of setting up fs-verity protected files.
637 To test fs-verity, use xfstests.  For example, using `kvm-xfstests
640     kvm-xfstests -c ext4,f2fs -g verity
645 This section answers frequently asked questions about fs-verity that
648 :Q: Why isn't fs-verity part of IMA?
649 :A: fs-verity and IMA (Integrity Measurement Architecture) have
650     different focuses.  fs-verity is a filesystem-level mechanism for
656     IMA is planned to support the fs-verity hashing mechanism as an
659     But it doesn't make sense to force all uses of fs-verity to be
660     through IMA.  As a standalone filesystem feature, fs-verity
664 :Q: Isn't fs-verity useless because the attacker can just modify the
666 :A: To verify the authenticity of an fs-verity file you must verify
667     the authenticity of the "fs-verity file digest", which
670 :Q: Isn't fs-verity useless because the attacker can just replace a
671     verity file with a non-verity one?
673     userspace code that authenticates the files; fs-verity is just a
675     userspace code will consider non-verity files to be inauthentic.
721 :Q: Why doesn't fs-verity support writes?
724     fs-verity.  Write support would require:
739     Compare it to dm-verity vs. dm-integrity.  dm-verity is very
746     very different cases; the same applies to fs-verity.
748 :Q: Since verity files are immutable, why isn't the immutable bit set?
753     properties are unwanted for fs-verity, so reusing the immutable
762 :Q: Does fs-verity support remote filesystems?
764     principle any filesystem that can store per-file verity metadata
765     can support fs-verity, regardless of whether it's local or remote.
767     verity metadata; one possibility is to store it past the end of
769     data verification functions provided by ``fs/verity/`` also assume
773 :Q: Why is anything filesystem-specific at all?  Shouldn't fs-verity
786       the verity metadata.  Extended attributes don't work for this
794       So the verity metadata would have to be stored in an actual
805       verity enabled, or no changes were made.  Allowing intermediate