Lines Matching refs:verity
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
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
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 measurement of a verity
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
214 support, or the filesystem superblock has not had the 'verity'
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.
226 The verity flag is not settable via FS_IOC_SETFLAGS. You must use
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
240 Applications can transparently access a verity file just like a
241 non-verity one, with the following exceptions:
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
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
265 verity file is copied, or is backed up and restored, then it will lose
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.
320 fs-verity descriptor
328 To solve this problem, the verity file measurement is actually
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.
368 3. A new sysctl "fs.verity.require_signatures" is made available.
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
387 that the verity bit is set, and there is no protection against verity
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
398 ``fs/verity/`` support layer and filesystems. Briefly, filesystems
400 methods to read and write the verity metadata to a filesystem-specific
403 ``fs/verity/`` at certain times, such as when a file is opened or when
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
413 it. "verity" is an RO_COMPAT filesystem feature, so once set, old
416 currently ext4 only supports mounting a filesystem with the "verity"
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
427 ext4 stores the verity metadata (Merkle tree and fsverity_descriptor)
429 i_size. This approach works because (a) verity files are readonly,
435 encrypting xattrs. Note that the verity metadata *must* be encrypted
438 Currently, ext4 verity only supports the case where the Merkle tree
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.
454 Like ext4, f2fs stores the verity metadata (Merkle tree and
460 Currently, f2fs verity only supports a Merkle tree block size of 4096.
461 Also, f2fs doesn't support enabling verity on files that currently
470 fs-verity ensures that all reads of a verity file's data are verified,
484 Therefore, fs/verity/ provides a function fsverity_verify_page() which
485 verifies a page that has been read into the pagecache of a verity
507 This optimization, which is also used by dm-verity, results in
520 filesystems to support fs-verity, fs/verity/ also provides a function
523 ext4 and f2fs also support encryption. If a verity file is also
536 verity, or both is enabled. After the bio completes, for each needed
539 verification. Finally, pages where no decryption or verity error
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
555 fs-verity can be found at:
560 including examples of setting up fs-verity protected files.
565 To test fs-verity, use xfstests. For example, using `kvm-xfstests
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
584 IMA is planned to support the fs-verity hashing mechanism as an
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
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.
649 :Q: Why doesn't fs-verity support writes?
652 fs-verity. Write support would require:
667 Compare it to dm-verity vs. dm-integrity. dm-verity is very
674 very different cases; the same applies to fs-verity.
676 :Q: Since verity files are immutable, why isn't the immutable bit set?
681 properties are unwanted for fs-verity, so reusing the immutable
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.
695 verity metadata; one possibility is to store it past the end of
697 data verification functions provided by ``fs/verity/`` also assume
701 :Q: Why is anything filesystem-specific at all? Shouldn't fs-verity
714 the verity metadata. Extended attributes don't work for this
722 So the verity metadata would have to be stored in an actual
733 verity enabled, or no changes were made. Allowing intermediate