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 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
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
79 fs-verity optionally supports a simple signature verification
81 all fs-verity files be signed by a key loaded into a keyring;
86 IMA supports including fs-verity file digests and signatures in the
87 IMA measurement list and verifying fs-verity based file signatures
97 The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes
141 with the file, then mark the file as a verity file. This ioctl may
150 after verity is enabled, and to guarantee that the file's contents are
154 verity file. On failure (including the case of interruption by a
162 - ``EEXIST``: the file already has verity enabled
171 - ``ENOKEY``: the fs-verity keyring doesn't contain the certificate
173 - ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not
176 - ``ENOTTY``: this type of filesystem does not implement fs-verity
177 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
178 support; or the filesystem superblock has not had the 'verity'
179 feature enabled on it; or the filesystem does not support fs-verity
191 The FS_IOC_MEASURE_VERITY ioctl retrieves the digest of a verity file.
192 The fs-verity file digest is a cryptographic digest that identifies
223 - ``ENODATA``: the file is not a verity file
224 - ``ENOTTY``: this type of filesystem does not implement fs-verity
225 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
226 support, or the filesystem superblock has not had the 'verity'
234 The FS_IOC_READ_VERITY_METADATA ioctl reads verity metadata from a
235 verity file. This ioctl is available since Linux v5.12.
237 This ioctl allows writing a server program that takes a verity file
239 fs-verity compatible verification of the file. This only makes sense
243 This is a fairly specialized use case, and most fs-verity users won't
268 - ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity
269 descriptor. See `fs-verity descriptor`_.
287 implement fs-verity compatible verification anyway (though absent a
298 - ``ENODATA``: the file is not a verity file, or
301 - ``ENOTTY``: this type of filesystem does not implement fs-verity, or
303 - ``EOPNOTSUPP``: the kernel was not configured with fs-verity
304 support, or the filesystem superblock has not had the 'verity'
310 The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
311 can also be used to check whether a file has fs-verity enabled or not.
314 The verity flag is not settable via FS_IOC_SETFLAGS. You must use
321 the file has fs-verity enabled. This can perform better than
323 opening the file, and opening verity files can be expensive.
325 Accessing verity files
328 Applications can transparently access a verity file just like a
329 non-verity one, with the following exceptions:
335 allowed, since these are not measured by fs-verity. Verity files
338 - Direct I/O is not supported on verity files. Attempts to use direct
341 - DAX (Direct Access) is not supported on verity files, because this
344 - Reads of data that doesn't match the verity Merkle tree will fail
347 - If the sysctl "fs.verity.require_signatures" is set to 1 and the
348 file is not signed by a key in the fs-verity keyring, then opening
352 verity file is copied, or is backed up and restored, then it will lose
353 its "verity"-ness. fs-verity is primarily meant for files like
359 This section describes how fs-verity hashes the file contents using a
362 that support fs-verity.
365 compute fs-verity file digests itself, e.g. in order to sign files.
407 fs-verity descriptor
415 To solve this problem, the fs-verity file digest is actually computed
434 With CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y, fs-verity supports putting
438 1. At fs-verity module initialization time, a keyring ".fs-verity" is
445 detached signature in DER format of the file's fs-verity digest.
449 in the ".fs-verity" keyring.
451 3. A new sysctl "fs.verity.require_signatures" is made available.
452 When set to 1, the kernel requires that all verity files have a
455 fs-verity file digests must be signed in the following format, which
465 fs-verity's built-in signature verification support is meant as a
467 authenticity protection for verity files, as an alternative to doing
470 that the verity bit is set, and there is no protection against verity
476 fs-verity is supported by several filesystems, described below. The
477 CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on
481 ``fs/verity/`` support layer and filesystems. Briefly, filesystems
483 methods to read and write the verity metadata to a filesystem-specific
486 ``fs/verity/`` at certain times, such as when a file is opened or when
492 ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.
494 To create verity files on an ext4 filesystem, the filesystem must have
495 been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
496 it. "verity" is an RO_COMPAT filesystem feature, so once set, old
499 currently ext4 only supports mounting a filesystem with the "verity"
502 ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It
506 fs-verity. In this case, the plaintext data is verified rather than
507 the ciphertext. This is necessary in order to make the fs-verity file
510 ext4 stores the verity metadata (Merkle tree and fsverity_descriptor)
512 i_size. This approach works because (a) verity files are readonly,
518 encrypting xattrs. Note that the verity metadata *must* be encrypted
521 Currently, ext4 verity only supports the case where the Merkle tree
528 f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.
530 To create verity files on an f2fs filesystem, the filesystem must have
531 been formatted with ``-O verity``.
533 f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
537 Like ext4, f2fs stores the verity metadata (Merkle tree and
543 Currently, f2fs verity only supports a Merkle tree block size of 4096.
544 Also, f2fs doesn't support enabling verity on files that currently
550 btrfs supports fs-verity since Linux v5.15. Verity-enabled inodes are
551 marked with a RO_COMPAT inode flag, and the verity metadata is stored
560 fs-verity ensures that all reads of a verity file's data are verified,
574 Therefore, fs/verity/ provides a function fsverity_verify_page() which
575 verifies a page that has been read into the pagecache of a verity
597 This optimization, which is also used by dm-verity, results in
610 filesystems to support fs-verity, fs/verity/ also provides a function
613 ext4 and f2fs also support encryption. If a verity file is also
626 verity, or both is enabled. After the bio completes, for each needed
629 verification. Finally, pages where no decryption or verity error
635 fs-verity, these filesystems use fsverity_verify_page() to verify hole
638 Filesystems also disable direct I/O on verity files, since otherwise
639 direct I/O would bypass fs-verity.
645 fs-verity can be found at:
650 including examples of setting up fs-verity protected files.
655 To test fs-verity, use xfstests. For example, using `kvm-xfstests
658 kvm-xfstests -c ext4,f2fs,btrfs -g verity
663 This section answers frequently asked questions about fs-verity that
666 :Q: Why isn't fs-verity part of IMA?
667 :A: fs-verity and IMA (Integrity Measurement Architecture) have
668 different focuses. fs-verity is a filesystem-level mechanism for
674 IMA supports the fs-verity hashing mechanism as an alternative
677 doesn't make sense to force all uses of fs-verity to be through
678 IMA. fs-verity already meets many users' needs even as a
682 :Q: Isn't fs-verity useless because the attacker can just modify the
684 :A: To verify the authenticity of an fs-verity file you must verify
685 the authenticity of the "fs-verity file digest", which
688 :Q: Isn't fs-verity useless because the attacker can just replace a
689 verity file with a non-verity one?
691 userspace code that authenticates the files; fs-verity is just a
693 userspace code will consider non-verity files to be inauthentic.
739 :Q: Why doesn't fs-verity support writes?
742 fs-verity. Write support would require:
757 Compare it to dm-verity vs. dm-integrity. dm-verity is very
764 very different cases; the same applies to fs-verity.
766 :Q: Since verity files are immutable, why isn't the immutable bit set?
771 properties are unwanted for fs-verity, so reusing the immutable
780 :Q: Does fs-verity support remote filesystems?
781 :A: So far all filesystems that have implemented fs-verity support are
783 per-file verity metadata can support fs-verity, regardless of
785 options of where to store the verity metadata; one possibility is
788 by ``fs/verity/`` also assume that the filesystem uses the Linux
791 :Q: Why is anything filesystem-specific at all? Shouldn't fs-verity
804 the verity metadata. Extended attributes don't work for this
812 So the verity metadata would have to be stored in an actual
823 verity enabled, or no changes were made. Allowing intermediate