sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget(/translations/zh_CN/filesystems/fsveritymodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/filesystems/fsveritymodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/it_IT/filesystems/fsveritymodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/filesystems/fsveritymodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/filesystems/fsveritymodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/filesystems/fsveritymodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhB/var/lib/git/docbuild/linux/Documentation/filesystems/fsverity.rsthKubhtarget)}(h .. _fsverity:h]h}(h]h ]h"]h$]h&]refidfsverityuh1hhKhhhhhhubhsection)}(hhh](htitle)}(h7fs-verity: read-only file-based authenticity protectionh]h7fs-verity: read-only file-based authenticity protection}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh paragraph)}(hX8fs-verity (``fs/verity/``) is a support layer that filesystems can hook into to support transparent integrity and authenticity protection of read-only files. Currently, it is supported by the ext4, f2fs, and btrfs filesystems. Like fscrypt, not too much filesystem-specific code is needed to support fs-verity.h](h fs-verity (}(hhhhhNhNubhliteral)}(h``fs/verity/``h]h fs/verity/}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubhX) is a support layer that filesystems can hook into to support transparent integrity and authenticity protection of read-only files. Currently, it is supported by the ext4, f2fs, and btrfs filesystems. Like fscrypt, not too much filesystem-specific code is needed to support fs-verity.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hXfs-verity is similar to `dm-verity `_ but works on files rather than block devices. On regular files on filesystems supporting fs-verity, userspace can execute an ioctl that causes the filesystem to build a Merkle tree for the file and persist it to a filesystem-specific location associated with the file.h](hfs-verity is similar to }(hj hhhNhNubh reference)}(h\`dm-verity `_h]h dm-verity}(hjhhhNhNubah}(h]h ]h"]h$]h&]name dm-verityrefuriMhttps://www.kernel.org/doc/Documentation/admin-guide/device-mapper/verity.rstuh1jhj ubh)}(hP h]h}(h] dm-verityah ]h"] dm-verityah$]h&]refurij'uh1h referencedKhj ubhX but works on files rather than block devices. On regular files on filesystems supporting fs-verity, userspace can execute an ioctl that causes the filesystem to build a Merkle tree for the file and persist it to a filesystem-specific location associated with the file.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hAfter this, the file is made readonly, and all reads from the file are automatically verified against the file's Merkle tree. Reads of any corrupted data, including mmap reads, will fail.h]hAfter this, the file is made readonly, and all reads from the file are automatically verified against the file’s Merkle tree. Reads of any corrupted data, including mmap reads, will fail.}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXUserspace can use another ioctl to retrieve the root hash (actually the "fs-verity file digest", which is a hash that includes the Merkle tree root hash) that fs-verity is enforcing for the file. This ioctl executes in constant time, regardless of the file size.h]hX Userspace can use another ioctl to retrieve the root hash (actually the “fs-verity file digest”, which is a hash that includes the Merkle tree root hash) that fs-verity is enforcing for the file. This ioctl executes in constant time, regardless of the file size.}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hfs-verity is essentially a way to hash a file in constant time, subject to the caveat that reads which would violate the hash will fail at runtime.h]hfs-verity is essentially a way to hash a file in constant time, subject to the caveat that reads which would violate the hash will fail at runtime.}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(h Use casesh]h Use cases}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjrhhhhhK'ubh)}(hqBy itself, fs-verity only provides integrity protection, i.e. detection of accidental (non-malicious) corruption.h]hqBy itself, fs-verity only provides integrity protection, i.e. detection of accidental (non-malicious) corruption.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK)hjrhhubh)}(hHowever, because fs-verity makes retrieving the file hash extremely efficient, it's primarily meant to be used as a tool to support authentication (detection of malicious modifications) or auditing (logging file hashes before use).h]hHowever, because fs-verity makes retrieving the file hash extremely efficient, it’s primarily meant to be used as a tool to support authentication (detection of malicious modifications) or auditing (logging file hashes before use).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK,hjrhhubh)}(hXA standard file hash could be used instead of fs-verity. However, this is inefficient if the file is large and only a small portion may be accessed. This is often the case for Android application package (APK) files, for example. These typically contain many translations, classes, and other resources that are infrequently or even never accessed on a particular device. It would be slow and wasteful to read and hash the entire file before starting the application.h]hXA standard file hash could be used instead of fs-verity. However, this is inefficient if the file is large and only a small portion may be accessed. This is often the case for Android application package (APK) files, for example. These typically contain many translations, classes, and other resources that are infrequently or even never accessed on a particular device. It would be slow and wasteful to read and hash the entire file before starting the application.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjrhhubh)}(hUnlike an ahead-of-time hash, fs-verity also re-verifies data each time it's paged in. This ensures that malicious disk firmware can't undetectably change the contents of the file at runtime.h]hUnlike an ahead-of-time hash, fs-verity also re-verifies data each time it’s paged in. This ensures that malicious disk firmware can’t undetectably change the contents of the file at runtime.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hjrhhubh)}(hXfs-verity does not replace or obsolete dm-verity. dm-verity should still be used on read-only filesystems. fs-verity is for files that must live on a read-write filesystem because they are independently updated and potentially user-installed, so dm-verity cannot be used.h]hXfs-verity does not replace or obsolete dm-verity. dm-verity should still be used on read-only filesystems. fs-verity is for files that must live on a read-write filesystem because they are independently updated and potentially user-installed, so dm-verity cannot be used.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK=hjrhhubh)}(hfs-verity does not mandate a particular scheme for authenticating its file hashes. (Similarly, dm-verity does not mandate a particular scheme for authenticating its block device root hashes.) Options for authenticating fs-verity file hashes include:h]hfs-verity does not mandate a particular scheme for authenticating its file hashes. (Similarly, dm-verity does not mandate a particular scheme for authenticating its block device root hashes.) Options for authenticating fs-verity file hashes include:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhjrhhubh bullet_list)}(hhh](h list_item)}(hXTrusted userspace code. Often, the userspace code that accesses files can be trusted to authenticate them. Consider e.g. an application that wants to authenticate data files before using them, or an application loader that is part of the operating system (which is already authenticated in a different way, such as by being loaded from a read-only partition that uses dm-verity) and that wants to authenticate applications before loading them. In these cases, this trusted userspace code can authenticate a file's contents by retrieving its fs-verity digest using `FS_IOC_MEASURE_VERITY`_, then verifying a signature of it using any userspace cryptographic library that supports digital signatures. h]h)}(hXTrusted userspace code. Often, the userspace code that accesses files can be trusted to authenticate them. Consider e.g. an application that wants to authenticate data files before using them, or an application loader that is part of the operating system (which is already authenticated in a different way, such as by being loaded from a read-only partition that uses dm-verity) and that wants to authenticate applications before loading them. In these cases, this trusted userspace code can authenticate a file's contents by retrieving its fs-verity digest using `FS_IOC_MEASURE_VERITY`_, then verifying a signature of it using any userspace cryptographic library that supports digital signatures.h](hX9Trusted userspace code. Often, the userspace code that accesses files can be trusted to authenticate them. Consider e.g. an application that wants to authenticate data files before using them, or an application loader that is part of the operating system (which is already authenticated in a different way, such as by being loaded from a read-only partition that uses dm-verity) and that wants to authenticate applications before loading them. In these cases, this trusted userspace code can authenticate a file’s contents by retrieving its fs-verity digest using }(hjhhhNhNubj)}(h`FS_IOC_MEASURE_VERITY`_h]hFS_IOC_MEASURE_VERITY}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_MEASURE_VERITYhfs-ioc-measure-verityuh1jhjresolvedKubhn, then verifying a signature of it using any userspace cryptographic library that supports digital signatures.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKGhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXNIntegrity Measurement Architecture (IMA). IMA supports fs-verity file digests as an alternative to its traditional full file digests. "IMA appraisal" enforces that files contain a valid, matching signature in their "security.ima" extended attribute, as controlled by the IMA policy. For more information, see the IMA documentation. h]h)}(hXMIntegrity Measurement Architecture (IMA). IMA supports fs-verity file digests as an alternative to its traditional full file digests. "IMA appraisal" enforces that files contain a valid, matching signature in their "security.ima" extended attribute, as controlled by the IMA policy. For more information, see the IMA documentation.h]hXUIntegrity Measurement Architecture (IMA). IMA supports fs-verity file digests as an alternative to its traditional full file digests. “IMA appraisal” enforces that files contain a valid, matching signature in their “security.ima” extended attribute, as controlled by the IMA policy. For more information, see the IMA documentation.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXOIntegrity Policy Enforcement (IPE). IPE supports enforcing access control decisions based on immutable security properties of files, including those protected by fs-verity's built-in signatures. "IPE policy" specifically allows for the authorization of fs-verity files using properties ``fsverity_digest`` for identifying files by their verity digest, and ``fsverity_signature`` to authorize files with a verified fs-verity's built-in signature. For details on configuring IPE policies and understanding its operational modes, please refer to :doc:`IPE admin guide `. h]h)}(hXNIntegrity Policy Enforcement (IPE). IPE supports enforcing access control decisions based on immutable security properties of files, including those protected by fs-verity's built-in signatures. "IPE policy" specifically allows for the authorization of fs-verity files using properties ``fsverity_digest`` for identifying files by their verity digest, and ``fsverity_signature`` to authorize files with a verified fs-verity's built-in signature. For details on configuring IPE policies and understanding its operational modes, please refer to :doc:`IPE admin guide `.h](hX%Integrity Policy Enforcement (IPE). IPE supports enforcing access control decisions based on immutable security properties of files, including those protected by fs-verity’s built-in signatures. “IPE policy” specifically allows for the authorization of fs-verity files using properties }(hj(hhhNhNubh)}(h``fsverity_digest``h]hfsverity_digest}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj(ubh3 for identifying files by their verity digest, and }(hj(hhhNhNubh)}(h``fsverity_signature``h]hfsverity_signature}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj(ubh to authorize files with a verified fs-verity’s built-in signature. For details on configuring IPE policies and understanding its operational modes, please refer to }(hj(hhhNhNubh)}(h-:doc:`IPE admin guide `h]hinline)}(hjVh]hIPE admin guide}(hjZhhhNhNubah}(h]h ](xrefstdstd-doceh"]h$]h&]uh1jXhjTubah}(h]h ]h"]h$]h&]refdocfilesystems/fsverity refdomainjereftypedoc refexplicitrefwarn reftarget/admin-guide/LSM/ipeuh1hhhhKYhj(ubh.}(hj(hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKYhj$ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hTrusted userspace code in combination with `Built-in signature verification`_. This approach should be used only with great care. h]h)}(hTrusted userspace code in combination with `Built-in signature verification`_. This approach should be used only with great care.h](h+Trusted userspace code in combination with }(hjhhhNhNubj)}(h"`Built-in signature verification`_h]hBuilt-in signature verification}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameBuilt-in signature verificationhbuilt-in-signature-verificationuh1jhjjKubh5. This approach should be used only with great care.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKchjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKGhjrhhubeh}(h] use-casesah ]h"] use casesah$]h&]uh1hhhhhhhhK'j5Kubh)}(hhh](h)}(hUser APIh]hUser API}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKgubh)}(hhh](h)}(hFS_IOC_ENABLE_VERITYh]hFS_IOC_ENABLE_VERITY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKjubh)}(hThe FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes in a pointer to a struct fsverity_enable_arg, defined as follows::h]hThe FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes in a pointer to a struct fsverity_enable_arg, defined as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKlhjhhubh literal_block)}(hXstruct fsverity_enable_arg { __u32 version; __u32 hash_algorithm; __u32 block_size; __u32 salt_size; __u64 salt_ptr; __u32 sig_size; __u32 __reserved1; __u64 sig_ptr; __u64 __reserved2[11]; };h]hXstruct fsverity_enable_arg { __u32 version; __u32 hash_algorithm; __u32 block_size; __u32 salt_size; __u64 salt_ptr; __u32 sig_size; __u32 __reserved1; __u64 sig_ptr; __u64 __reserved2[11]; };}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKphjhhubh)}(htThis structure contains the parameters of the Merkle tree to build for the file. It must be initialized as follows:h]htThis structure contains the parameters of the Merkle tree to build for the file. It must be initialized as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK|hjhhubj)}(hhh](j)}(h``version`` must be 1.h]h)}(hjh](h)}(h ``version``h]hversion}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh must be 1.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``hash_algorithm`` must be the identifier for the hash algorithm to use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256. See ``include/uapi/linux/fsverity.h`` for the list of possible values.h]h)}(h``hash_algorithm`` must be the identifier for the hash algorithm to use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256. See ``include/uapi/linux/fsverity.h`` for the list of possible values.h](h)}(h``hash_algorithm``h]hhash_algorithm}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj@ubhs must be the identifier for the hash algorithm to use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256. See }(hj@hhhNhNubh)}(h!``include/uapi/linux/fsverity.h``h]hinclude/uapi/linux/fsverity.h}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj@ubh! for the list of possible values.}(hj@hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj<ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX``block_size`` is the Merkle tree block size, in bytes. In Linux v6.3 and later, this can be any power of 2 between (inclusively) 1024 and the minimum of the system page size and the filesystem block size. In earlier versions, the page size was the only allowed value.h]h)}(hX``block_size`` is the Merkle tree block size, in bytes. In Linux v6.3 and later, this can be any power of 2 between (inclusively) 1024 and the minimum of the system page size and the filesystem block size. In earlier versions, the page size was the only allowed value.h](h)}(h``block_size``h]h block_size}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjxubhX is the Merkle tree block size, in bytes. In Linux v6.3 and later, this can be any power of 2 between (inclusively) 1024 and the minimum of the system page size and the filesystem block size. In earlier versions, the page size was the only allowed value.}(hjxhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjtubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX``salt_size`` is the size of the salt in bytes, or 0 if no salt is provided. The salt is a value that is prepended to every hashed block; it can be used to personalize the hashing for a particular file or device. Currently the maximum salt size is 32 bytes.h]h)}(hX``salt_size`` is the size of the salt in bytes, or 0 if no salt is provided. The salt is a value that is prepended to every hashed block; it can be used to personalize the hashing for a particular file or device. Currently the maximum salt size is 32 bytes.h](h)}(h ``salt_size``h]h salt_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh is the size of the salt in bytes, or 0 if no salt is provided. The salt is a value that is prepended to every hashed block; it can be used to personalize the hashing for a particular file or device. Currently the maximum salt size is 32 bytes.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hH``salt_ptr`` is the pointer to the salt, or NULL if no salt is provided.h]h)}(hH``salt_ptr`` is the pointer to the salt, or NULL if no salt is provided.h](h)}(h ``salt_ptr``h]hsalt_ptr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh< is the pointer to the salt, or NULL if no salt is provided.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``sig_size`` is the size of the builtin signature in bytes, or 0 if no builtin signature is provided. Currently the builtin signature is (somewhat arbitrarily) limited to 16128 bytes.h]h)}(h``sig_size`` is the size of the builtin signature in bytes, or 0 if no builtin signature is provided. Currently the builtin signature is (somewhat arbitrarily) limited to 16128 bytes.h](h)}(h ``sig_size``h]hsig_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh is the size of the builtin signature in bytes, or 0 if no builtin signature is provided. Currently the builtin signature is (somewhat arbitrarily) limited to 16128 bytes.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX?``sig_ptr`` is the pointer to the builtin signature, or NULL if no builtin signature is provided. A builtin signature is only needed if the `Built-in signature verification`_ feature is being used. It is not needed for IMA appraisal, and it is not needed if the file signature is being handled entirely in userspace.h]h)}(hX?``sig_ptr`` is the pointer to the builtin signature, or NULL if no builtin signature is provided. A builtin signature is only needed if the `Built-in signature verification`_ feature is being used. It is not needed for IMA appraisal, and it is not needed if the file signature is being handled entirely in userspace.h](h)}(h ``sig_ptr``h]hsig_ptr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh is the pointer to the builtin signature, or NULL if no builtin signature is provided. A builtin signature is only needed if the }(hjhhhNhNubj)}(h"`Built-in signature verification`_h]hBuilt-in signature verification}(hj&hhhNhNubah}(h]h ]h"]h$]h&]nameBuilt-in signature verificationhjuh1jhjjKubh feature is being used. It is not needed for IMA appraisal, and it is not needed if the file signature is being handled entirely in userspace.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h$All reserved fields must be zeroed. h]h)}(h#All reserved fields must be zeroed.h]h#All reserved fields must be zeroed.}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjFubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hX$FS_IOC_ENABLE_VERITY causes the filesystem to build a Merkle tree for the file and persist it to a filesystem-specific location associated with the file, then mark the file as a verity file. This ioctl may take a long time to execute on large files, and it is interruptible by fatal signals.h]hX$FS_IOC_ENABLE_VERITY causes the filesystem to build a Merkle tree for the file and persist it to a filesystem-specific location associated with the file, then mark the file as a verity file. This ioctl may take a long time to execute on large files, and it is interruptible by fatal signals.}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXFS_IOC_ENABLE_VERITY checks for write access to the inode. However, it must be executed on an O_RDONLY file descriptor and no processes can have the file open for writing. Attempts to open the file for writing while this ioctl is executing will fail with ETXTBSY. (This is necessary to guarantee that no writable file descriptors will exist after verity is enabled, and to guarantee that the file's contents are stable while the Merkle tree is being built over it.)h]hXFS_IOC_ENABLE_VERITY checks for write access to the inode. However, it must be executed on an O_RDONLY file descriptor and no processes can have the file open for writing. Attempts to open the file for writing while this ioctl is executing will fail with ETXTBSY. (This is necessary to guarantee that no writable file descriptors will exist after verity is enabled, and to guarantee that the file’s contents are stable while the Merkle tree is being built over it.)}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hOn success, FS_IOC_ENABLE_VERITY returns 0, and the file becomes a verity file. On failure (including the case of interruption by a fatal signal), no changes are made to the file.h]hOn success, FS_IOC_ENABLE_VERITY returns 0, and the file becomes a verity file. On failure (including the case of interruption by a fatal signal), no changes are made to the file.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h8FS_IOC_ENABLE_VERITY can fail with the following errors:h]h8FS_IOC_ENABLE_VERITY can fail with the following errors:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh](j)}(h>``EACCES``: the process does not have write access to the fileh]h)}(hjh](h)}(h ``EACCES``h]hEACCES}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh4: the process does not have write access to the file}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h/``EBADMSG``: the builtin signature is malformedh]h)}(hjh](h)}(h ``EBADMSG``h]hEBADMSG}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh$: the builtin signature is malformed}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h4``EBUSY``: this ioctl is already running on the fileh]h)}(hjh](h)}(h ``EBUSY``h]hEBUSY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh+: this ioctl is already running on the file}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h/``EEXIST``: the file already has verity enabledh]h)}(hjh](h)}(h ``EEXIST``h]hEEXIST}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh%: the file already has verity enabled}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h3``EFAULT``: the caller provided inaccessible memoryh]h)}(hj5h](h)}(h ``EFAULT``h]hEFAULT}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj7ubh): the caller provided inaccessible memory}(hj7hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj3ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h4``EFBIG``: the file is too large to enable verity onh]h)}(hjZh](h)}(h ``EFBIG``h]hEFBIG}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj\ubh+: the file is too large to enable verity on}(hj\hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjXubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h:``EINTR``: the operation was interrupted by a fatal signalh]h)}(hjh](h)}(h ``EINTR``h]hEINTR}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh1: the operation was interrupted by a fatal signal}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj}ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``EINVAL``: unsupported version, hash algorithm, or block size; or reserved bits are set; or the file descriptor refers to neither a regular file nor a directory.h]h)}(h``EINVAL``: unsupported version, hash algorithm, or block size; or reserved bits are set; or the file descriptor refers to neither a regular file nor a directory.h](h)}(h ``EINVAL``h]hEINVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: unsupported version, hash algorithm, or block size; or reserved bits are set; or the file descriptor refers to neither a regular file nor a directory.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h5``EISDIR``: the file descriptor refers to a directoryh]h)}(hjh](h)}(h ``EISDIR``h]hEISDIR}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh+: the file descriptor refers to a directory}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h>``EKEYREJECTED``: the builtin signature doesn't match the fileh]h)}(hjh](h)}(h``EKEYREJECTED``h]h EKEYREJECTED}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh0: the builtin signature doesn’t match the file}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h7``EMSGSIZE``: the salt or builtin signature is too longh]h)}(hjh](h)}(h ``EMSGSIZE``h]hEMSGSIZE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh+: the salt or builtin signature is too long}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hk``ENOKEY``: the ".fs-verity" keyring doesn't contain the certificate needed to verify the builtin signatureh]h)}(hk``ENOKEY``: the ".fs-verity" keyring doesn't contain the certificate needed to verify the builtin signatureh](h)}(h ``ENOKEY``h]hENOKEY}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;ubhg: the “.fs-verity” keyring doesn’t contain the certificate needed to verify the builtin signature}(hj;hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj7ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not available in the kernel's crypto API as currently configured (e.g. for SHA-512, missing CONFIG_CRYPTO_SHA512).h]h)}(h``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not available in the kernel's crypto API as currently configured (e.g. for SHA-512, missing CONFIG_CRYPTO_SHA512).h](h)}(h ``ENOPKG``h]hENOPKG}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhjaubh: fs-verity recognizes the hash algorithm, but it’s not available in the kernel’s crypto API as currently configured (e.g. for SHA-512, missing CONFIG_CRYPTO_SHA512).}(hjahhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj]ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h@``ENOTTY``: this type of filesystem does not implement fs-verityh]h)}(hjh](h)}(h ``ENOTTY``h]hENOTTY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh6: this type of filesystem does not implement fs-verity}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``EOPNOTSUPP``: the kernel was not configured with fs-verity support; or the filesystem superblock has not had the 'verity' feature enabled on it; or the filesystem does not support fs-verity on this file. (See `Filesystem support`_.)h]h)}(h``EOPNOTSUPP``: the kernel was not configured with fs-verity support; or the filesystem superblock has not had the 'verity' feature enabled on it; or the filesystem does not support fs-verity on this file. (See `Filesystem support`_.)h](h)}(h``EOPNOTSUPP``h]h EOPNOTSUPP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: the kernel was not configured with fs-verity support; or the filesystem superblock has not had the ‘verity’ feature enabled on it; or the filesystem does not support fs-verity on this file. (See }(hjhhhNhNubj)}(h`Filesystem support`_h]hFilesystem support}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFilesystem supporthfilesystem-supportuh1jhjjKubh.)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(ha``EPERM``: the file is append-only; or, a builtin signature is required and one was not provided.h]h)}(ha``EPERM``: the file is append-only; or, a builtin signature is required and one was not provided.h](h)}(h ``EPERM``h]hEPERM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhX: the file is append-only; or, a builtin signature is required and one was not provided.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h&``EROFS``: the filesystem is read-onlyh]h)}(hj h](h)}(h ``EROFS``h]hEROFS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh: the filesystem is read-only}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``ETXTBSY``: someone has the file open for writing. This can be the caller's file descriptor, another open file descriptor, or the file reference held by a writable memory map. h]h)}(h``ETXTBSY``: someone has the file open for writing. This can be the caller's file descriptor, another open file descriptor, or the file reference held by a writable memory map.h](h)}(h ``ETXTBSY``h]hETXTBSY}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj2ubh: someone has the file open for writing. This can be the caller’s file descriptor, another open file descriptor, or the file reference held by a writable memory map.}(hj2hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj.ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubeh}(h]fs-ioc-enable-verityah ]h"]fs_ioc_enable_verityah$]h&]uh1hhjhhhhhKjj5Kubh)}(hhh](h)}(hFS_IOC_MEASURE_VERITYh]hFS_IOC_MEASURE_VERITY}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhjbhhhhhKubh)}(hXThe FS_IOC_MEASURE_VERITY ioctl retrieves the digest of a verity file. The fs-verity file digest is a cryptographic digest that identifies the file contents that are being enforced on reads; it is computed via a Merkle tree and is different from a traditional full-file digest.h]hXThe FS_IOC_MEASURE_VERITY ioctl retrieves the digest of a verity file. The fs-verity file digest is a cryptographic digest that identifies the file contents that are being enforced on reads; it is computed via a Merkle tree and is different from a traditional full-file digest.}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubh)}(h>This ioctl takes in a pointer to a variable-length structure::h]h=This ioctl takes in a pointer to a variable-length structure:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubj)}(hstruct fsverity_digest { __u16 digest_algorithm; __u16 digest_size; /* input/output */ __u8 digest[]; };h]hstruct fsverity_digest { __u16 digest_algorithm; __u16 digest_size; /* input/output */ __u8 digest[]; };}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjbhhubh)}(h``digest_size`` is an input/output field. On input, it must be initialized to the number of bytes allocated for the variable-length ``digest`` field.h](h)}(h``digest_size``h]h digest_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhv is an input/output field. On input, it must be initialized to the number of bytes allocated for the variable-length }(hjhhhNhNubh)}(h ``digest``h]hdigest}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh field.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubh)}(hKOn success, 0 is returned and the kernel fills in the structure as follows:h]hKOn success, 0 is returned and the kernel fills in the structure as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubj)}(hhh](j)}(h``digest_algorithm`` will be the hash algorithm used for the file digest. It will match ``fsverity_enable_arg::hash_algorithm``.h]h)}(h``digest_algorithm`` will be the hash algorithm used for the file digest. It will match ``fsverity_enable_arg::hash_algorithm``.h](h)}(h``digest_algorithm``h]hdigest_algorithm}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhE will be the hash algorithm used for the file digest. It will match }(hjhhhNhNubh)}(h'``fsverity_enable_arg::hash_algorithm``h]h#fsverity_enable_arg::hash_algorithm}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``digest_size`` will be the size of the digest in bytes, e.g. 32 for SHA-256. (This can be redundant with ``digest_algorithm``.)h]h)}(h``digest_size`` will be the size of the digest in bytes, e.g. 32 for SHA-256. (This can be redundant with ``digest_algorithm``.)h](h)}(h``digest_size``h]h digest_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh\ will be the size of the digest in bytes, e.g. 32 for SHA-256. (This can be redundant with }(hjhhhNhNubh)}(h``digest_algorithm``h]hdigest_algorithm}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh.)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h3``digest`` will be the actual bytes of the digest. h]h)}(h2``digest`` will be the actual bytes of the digest.h](h)}(h ``digest``h]hdigest}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjPubh( will be the actual bytes of the digest.}(hjPhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjLubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjbhhubh)}(hdFS_IOC_MEASURE_VERITY is guaranteed to execute in constant time, regardless of the size of the file.h]hdFS_IOC_MEASURE_VERITY is guaranteed to execute in constant time, regardless of the size of the file.}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubh)}(h9FS_IOC_MEASURE_VERITY can fail with the following errors:h]h9FS_IOC_MEASURE_VERITY can fail with the following errors:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubj)}(hhh](j)}(h3``EFAULT``: the caller provided inaccessible memoryh]h)}(hjh](h)}(h ``EFAULT``h]hEFAULT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh): the caller provided inaccessible memory}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h*``ENODATA``: the file is not a verity fileh]h)}(hjh](h)}(h ``ENODATA``h]hENODATA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: the file is not a verity file}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h@``ENOTTY``: this type of filesystem does not implement fs-verityh]h)}(hjh](h)}(h ``ENOTTY``h]hENOTTY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh6: this type of filesystem does not implement fs-verity}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``EOPNOTSUPP``: the kernel was not configured with fs-verity support, or the filesystem superblock has not had the 'verity' feature enabled on it. (See `Filesystem support`_.)h]h)}(h``EOPNOTSUPP``: the kernel was not configured with fs-verity support, or the filesystem superblock has not had the 'verity' feature enabled on it. (See `Filesystem support`_.)h](h)}(h``EOPNOTSUPP``h]h EOPNOTSUPP}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh: the kernel was not configured with fs-verity support, or the filesystem superblock has not had the ‘verity’ feature enabled on it. (See }(hj hhhNhNubj)}(h`Filesystem support`_h]hFilesystem support}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameFilesystem supporthjuh1jhj jKubh.)}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hn``EOVERFLOW``: the digest is longer than the specified ``digest_size`` bytes. Try providing a larger buffer. h]h)}(hm``EOVERFLOW``: the digest is longer than the specified ``digest_size`` bytes. Try providing a larger buffer.h](h)}(h ``EOVERFLOW``h]h EOVERFLOW}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjD ubh*: the digest is longer than the specified }(hjD hhhNhNubh)}(h``digest_size``h]h digest_size}(hjZ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjD ubh' bytes. Try providing a larger buffer.}(hjD hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj@ ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjbhhubeh}(h]jah ]h"]fs_ioc_measure_verityah$]h&]uh1hhjhhhhhKj5Kubh)}(hhh](h)}(hFS_IOC_READ_VERITY_METADATAh]hFS_IOC_READ_VERITY_METADATA}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(h{The FS_IOC_READ_VERITY_METADATA ioctl reads verity metadata from a verity file. This ioctl is available since Linux v5.12.h]h{The FS_IOC_READ_VERITY_METADATA ioctl reads verity metadata from a verity file. This ioctl is available since Linux v5.12.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hThis ioctl is useful for cases where the verity verification should be performed somewhere other than the currently running kernel.h]hThis ioctl is useful for cases where the verity verification should be performed somewhere other than the currently running kernel.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hX+One example is a server program that takes a verity file and serves it to a client program, such that the client can do its own fs-verity compatible verification of the file. This only makes sense if the client doesn't trust the server and if the server needs to provide the storage for the client.h]hX-One example is a server program that takes a verity file and serves it to a client program, such that the client can do its own fs-verity compatible verification of the file. This only makes sense if the client doesn’t trust the server and if the server needs to provide the storage for the client.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hxAnother example is copying verity metadata when creating filesystem images in userspace (such as with ``mkfs.ext4 -d``).h](hfAnother example is copying verity metadata when creating filesystem images in userspace (such as with }(hj hhhNhNubh)}(h``mkfs.ext4 -d``h]h mkfs.ext4 -d}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hVThis is a fairly specialized use case, and most fs-verity users won't need this ioctl.h]hXThis is a fairly specialized use case, and most fs-verity users won’t need this ioctl.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h:This ioctl takes in a pointer to the following structure::h]h9This ioctl takes in a pointer to the following structure:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj hhubj)}(hX7#define FS_VERITY_METADATA_TYPE_MERKLE_TREE 1 #define FS_VERITY_METADATA_TYPE_DESCRIPTOR 2 #define FS_VERITY_METADATA_TYPE_SIGNATURE 3 struct fsverity_read_metadata_arg { __u64 metadata_type; __u64 offset; __u64 length; __u64 buf_ptr; __u64 __reserved; };h]hX7#define FS_VERITY_METADATA_TYPE_MERKLE_TREE 1 #define FS_VERITY_METADATA_TYPE_DESCRIPTOR 2 #define FS_VERITY_METADATA_TYPE_SIGNATURE 3 struct fsverity_read_metadata_arg { __u64 metadata_type; __u64 offset; __u64 length; __u64 buf_ptr; __u64 __reserved; };}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhM hj hhubh)}(h9``metadata_type`` specifies the type of metadata to read:h](h)}(h``metadata_type``h]h metadata_type}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh( specifies the type of metadata to read:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hhh](j)}(hX&``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the Merkle tree. The blocks are returned in order from the root level to the leaf level. Within each level, the blocks are returned in the same order that their hashes are themselves hashed. See `Merkle tree`_ for more information. h]h)}(hX%``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the Merkle tree. The blocks are returned in order from the root level to the leaf level. Within each level, the blocks are returned in the same order that their hashes are themselves hashed. See `Merkle tree`_ for more information.h](h)}(h'``FS_VERITY_METADATA_TYPE_MERKLE_TREE``h]h#FS_VERITY_METADATA_TYPE_MERKLE_TREE}(hj1 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj- ubh reads the blocks of the Merkle tree. The blocks are returned in order from the root level to the leaf level. Within each level, the blocks are returned in the same order that their hashes are themselves hashed. See }(hj- hhhNhNubj)}(h`Merkle tree`_h]h Merkle tree}(hjC hhhNhNubah}(h]h ]h"]h$]h&]name Merkle treeh merkle-treeuh1jhj- jKubh for more information.}(hj- hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj) ubah}(h]h ]h"]h$]h&]uh1jhj& hhhhhNubj)}(he``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity descriptor. See `fs-verity descriptor`_. h]h)}(hd``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity descriptor. See `fs-verity descriptor`_.h](h)}(h&``FS_VERITY_METADATA_TYPE_DESCRIPTOR``h]h"FS_VERITY_METADATA_TYPE_DESCRIPTOR}(hjl hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjh ubh& reads the fs-verity descriptor. See }(hjh hhhNhNubj)}(h`fs-verity descriptor`_h]hfs-verity descriptor}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]namefs-verity descriptorhfs-verity-descriptoruh1jhjh jKubh.}(hjh hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjd ubah}(h]h ]h"]h$]h&]uh1jhj& hhhhhNubj)}(h``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the builtin signature which was passed to FS_IOC_ENABLE_VERITY, if any. See `Built-in signature verification`_. h]h)}(h``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the builtin signature which was passed to FS_IOC_ENABLE_VERITY, if any. See `Built-in signature verification`_.h](h)}(h%``FS_VERITY_METADATA_TYPE_SIGNATURE``h]h!FS_VERITY_METADATA_TYPE_SIGNATURE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhT reads the builtin signature which was passed to FS_IOC_ENABLE_VERITY, if any. See }(hj hhhNhNubj)}(h"`Built-in signature verification`_h]hBuilt-in signature verification}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameBuilt-in signature verificationhjuh1jhj jKubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM#hj ubah}(h]h ]h"]h$]h&]uh1jhj& hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhj hhubh)}(hXThe semantics are similar to those of ``pread()``. ``offset`` specifies the offset in bytes into the metadata item to read from, and ``length`` specifies the maximum number of bytes to read from the metadata item. ``buf_ptr`` is the pointer to the buffer to read into, cast to a 64-bit integer. ``__reserved`` must be 0. On success, the number of bytes read is returned. 0 is returned at the end of the metadata item. The returned length may be less than ``length``, for example if the ioctl is interrupted.h](h&The semantics are similar to those of }(hj hhhNhNubh)}(h ``pread()``h]hpread()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh. }(hj hhhNhNubh)}(h ``offset``h]hoffset}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhH specifies the offset in bytes into the metadata item to read from, and }(hj hhhNhNubh)}(h ``length``h]hlength}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhH specifies the maximum number of bytes to read from the metadata item. }(hj hhhNhNubh)}(h ``buf_ptr``h]hbuf_ptr}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhG is the pointer to the buffer to read into, cast to a 64-bit integer. }(hj hhhNhNubh)}(h``__reserved``h]h __reserved}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh must be 0. On success, the number of bytes read is returned. 0 is returned at the end of the metadata item. The returned length may be less than }(hj hhhNhNubh)}(h ``length``h]hlength}(hjA hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh*, for example if the ioctl is interrupted.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM'hj hhubh)}(hXThe metadata returned by FS_IOC_READ_VERITY_METADATA isn't guaranteed to be authenticated against the file digest that would be returned by `FS_IOC_MEASURE_VERITY`_, as the metadata is expected to be used to implement fs-verity compatible verification anyway (though absent a malicious disk, the metadata will indeed match). E.g. to implement this ioctl, the filesystem is allowed to just read the Merkle tree blocks from disk without actually verifying the path to the root node.h](hThe metadata returned by FS_IOC_READ_VERITY_METADATA isn’t guaranteed to be authenticated against the file digest that would be returned by }(hjY hhhNhNubj)}(h`FS_IOC_MEASURE_VERITY`_h]hFS_IOC_MEASURE_VERITY}(hja hhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_MEASURE_VERITYhjuh1jhjY jKubhX=, as the metadata is expected to be used to implement fs-verity compatible verification anyway (though absent a malicious disk, the metadata will indeed match). E.g. to implement this ioctl, the filesystem is allowed to just read the Merkle tree blocks from disk without actually verifying the path to the root node.}(hjY hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM0hj hhubh)}(h?FS_IOC_READ_VERITY_METADATA can fail with the following errors:h]h?FS_IOC_READ_VERITY_METADATA can fail with the following errors:}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM8hj hhubj)}(hhh](j)}(h3``EFAULT``: the caller provided inaccessible memoryh]h)}(hj h](h)}(h ``EFAULT``h]hEFAULT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh): the caller provided inaccessible memory}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM:hj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(h=``EINTR``: the ioctl was interrupted before any data was readh]h)}(hj h](h)}(h ``EINTR``h]hEINTR}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh4: the ioctl was interrupted before any data was read}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM;hj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hG``EINVAL``: reserved fields were set, or ``offset + length`` overflowedh]h)}(hG``EINVAL``: reserved fields were set, or ``offset + length`` overflowedh](h)}(h ``EINVAL``h]hEINVAL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh: reserved fields were set, or }(hj hhhNhNubh)}(h``offset + length``h]hoffset + length}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh overflowed}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM<hj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(h``ENODATA``: the file is not a verity file, or FS_VERITY_METADATA_TYPE_SIGNATURE was requested but the file doesn't have a builtin signatureh]h)}(h``ENODATA``: the file is not a verity file, or FS_VERITY_METADATA_TYPE_SIGNATURE was requested but the file doesn't have a builtin signatureh](h)}(h ``ENODATA``h]hENODATA}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh: the file is not a verity file, or FS_VERITY_METADATA_TYPE_SIGNATURE was requested but the file doesn’t have a builtin signature}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM>hj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hl``ENOTTY``: this type of filesystem does not implement fs-verity, or this ioctl is not yet implemented on ith]h)}(hl``ENOTTY``: this type of filesystem does not implement fs-verity, or this ioctl is not yet implemented on ith](h)}(h ``ENOTTY``h]hENOTTY}(hj< hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj8 ubhb: this type of filesystem does not implement fs-verity, or this ioctl is not yet implemented on it}(hj8 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMAhj4 ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(h``EOPNOTSUPP``: the kernel was not configured with fs-verity support, or the filesystem superblock has not had the 'verity' feature enabled on it. (See `Filesystem support`_.) h]h)}(h``EOPNOTSUPP``: the kernel was not configured with fs-verity support, or the filesystem superblock has not had the 'verity' feature enabled on it. (See `Filesystem support`_.)h](h)}(h``EOPNOTSUPP``h]h EOPNOTSUPP}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^ ubh: the kernel was not configured with fs-verity support, or the filesystem superblock has not had the ‘verity’ feature enabled on it. (See }(hj^ hhhNhNubj)}(h`Filesystem support`_h]hFilesystem support}(hjt hhhNhNubah}(h]h ]h"]h$]h&]nameFilesystem supporthjuh1jhj^ jKubh.)}(hj^ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMChjZ ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhM:hj hhubeh}(h]fs-ioc-read-verity-metadataah ]h"]fs_ioc_read_verity_metadataah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hFS_IOC_GETFLAGSh]hFS_IOC_GETFLAGS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMHubh)}(hThe existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity) can also be used to check whether a file has fs-verity enabled or not. To do so, check for FS_VERITY_FL (0x00100000) in the returned flags.h]hThe existing ioctl FS_IOC_GETFLAGS (which isn’t specific to fs-verity) can also be used to check whether a file has fs-verity enabled or not. To do so, check for FS_VERITY_FL (0x00100000) in the returned flags.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhj hhubh)}(hThe verity flag is not settable via FS_IOC_SETFLAGS. You must use FS_IOC_ENABLE_VERITY instead, since parameters must be provided.h]hThe verity flag is not settable via FS_IOC_SETFLAGS. You must use FS_IOC_ENABLE_VERITY instead, since parameters must be provided.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhj hhubeh}(h]fs-ioc-getflagsah ]h"]fs_ioc_getflagsah$]h&]uh1hhjhhhhhMHubh)}(hhh](h)}(hstatxh]hstatx}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMRubh)}(hXSince Linux v5.5, the statx() system call sets STATX_ATTR_VERITY if the file has fs-verity enabled. This can perform better than FS_IOC_GETFLAGS and FS_IOC_MEASURE_VERITY because it doesn't require opening the file, and opening verity files can be expensive.h]hXSince Linux v5.5, the statx() system call sets STATX_ATTR_VERITY if the file has fs-verity enabled. This can perform better than FS_IOC_GETFLAGS and FS_IOC_MEASURE_VERITY because it doesn’t require opening the file, and opening verity files can be expensive.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMThj hhubh)}(h.. _accessing_verity_files:h]h}(h]h ]h"]h$]h&]haccessing-verity-filesuh1hhMYhj hhhhubeh}(h]statxah ]h"]statxah$]h&]uh1hhjhhhhhMRubeh}(h]user-apiah ]h"]user apiah$]h&]uh1hhhhhhhhKgubh)}(hhh](h)}(hAccessing verity filesh]hAccessing verity files}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM\ubh)}(hnApplications can transparently access a verity file just like a non-verity one, with the following exceptions:h]hnApplications can transparently access a verity file just like a non-verity one, with the following exceptions:}(hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hj hhubj)}(hhh](j)}(hXvVerity files are readonly. They cannot be opened for writing or truncate()d, even if the file mode bits allow it. Attempts to do one of these things will fail with EPERM. However, changes to metadata such as owner, mode, timestamps, and xattrs are still allowed, since these are not measured by fs-verity. Verity files can also still be renamed, deleted, and linked to. h]h)}(hXuVerity files are readonly. They cannot be opened for writing or truncate()d, even if the file mode bits allow it. Attempts to do one of these things will fail with EPERM. However, changes to metadata such as owner, mode, timestamps, and xattrs are still allowed, since these are not measured by fs-verity. Verity files can also still be renamed, deleted, and linked to.h]hXuVerity files are readonly. They cannot be opened for writing or truncate()d, even if the file mode bits allow it. Attempts to do one of these things will fail with EPERM. However, changes to metadata such as owner, mode, timestamps, and xattrs are still allowed, since these are not measured by fs-verity. Verity files can also still be renamed, deleted, and linked to.}(hj7 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMahj3 ubah}(h]h ]h"]h$]h&]uh1jhj0 hhhhhNubj)}(hwDirect I/O is not supported on verity files. Attempts to use direct I/O on such files will fall back to buffered I/O. h]h)}(hvDirect I/O is not supported on verity files. Attempts to use direct I/O on such files will fall back to buffered I/O.h]hvDirect I/O is not supported on verity files. Attempts to use direct I/O on such files will fall back to buffered I/O.}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhhjK ubah}(h]h ]h"]h$]h&]uh1jhj0 hhhhhNubj)}(hkDAX (Direct Access) is not supported on verity files, because this would circumvent the data verification. h]h)}(hjDAX (Direct Access) is not supported on verity files, because this would circumvent the data verification.h]hjDAX (Direct Access) is not supported on verity files, because this would circumvent the data verification.}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMkhjc ubah}(h]h ]h"]h$]h&]uh1jhj0 hhhhhNubj)}(hvReads of data that doesn't match the verity Merkle tree will fail with EIO (for read()) or SIGBUS (for mmap() reads). h]h)}(huReads of data that doesn't match the verity Merkle tree will fail with EIO (for read()) or SIGBUS (for mmap() reads).h]hwReads of data that doesn’t match the verity Merkle tree will fail with EIO (for read()) or SIGBUS (for mmap() reads).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMnhj{ ubah}(h]h ]h"]h$]h&]uh1jhj0 hhhhhNubj)}(hIf the sysctl "fs.verity.require_signatures" is set to 1 and the file is not signed by a key in the ".fs-verity" keyring, then opening the file will fail. See `Built-in signature verification`_. h]h)}(hIf the sysctl "fs.verity.require_signatures" is set to 1 and the file is not signed by a key in the ".fs-verity" keyring, then opening the file will fail. See `Built-in signature verification`_.h](hIf the sysctl “fs.verity.require_signatures” is set to 1 and the file is not signed by a key in the “.fs-verity” keyring, then opening the file will fail. See }(hj hhhNhNubj)}(h"`Built-in signature verification`_h]hBuilt-in signature verification}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameBuilt-in signature verificationhjuh1jhj jKubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMqhj ubah}(h]h ]h"]h$]h&]uh1jhj0 hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhMahj hhubh)}(hDirect access to the Merkle tree is not supported. Therefore, if a verity file is copied, or is backed up and restored, then it will lose its "verity"-ness. fs-verity is primarily meant for files like executables that are managed by a package manager.h]hXDirect access to the Merkle tree is not supported. Therefore, if a verity file is copied, or is backed up and restored, then it will lose its “verity”-ness. fs-verity is primarily meant for files like executables that are managed by a package manager.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMuhj hhubeh}(h](j id1eh ]h"](accessing verity filesaccessing_verity_fileseh$]h&]uh1hhhhhhhhM\expect_referenced_by_name}j j sexpect_referenced_by_id}j j subh)}(hhh](h)}(hFile digest computationh]hFile digest computation}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM{ubh)}(hThis section describes how fs-verity hashes the file contents using a Merkle tree to produce the digest which cryptographically identifies the file contents. This algorithm is the same for all filesystems that support fs-verity.h]hThis section describes how fs-verity hashes the file contents using a Merkle tree to produce the digest which cryptographically identifies the file contents. This algorithm is the same for all filesystems that support fs-verity.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM}hj hhubh)}(hUserspace only needs to be aware of this algorithm if it needs to compute fs-verity file digests itself, e.g. in order to sign files.h]hUserspace only needs to be aware of this algorithm if it needs to compute fs-verity file digests itself, e.g. in order to sign files.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h.. _fsverity_merkle_tree:h]h}(h]h ]h"]h$]h&]hfsverity-merkle-treeuh1hhMhj hhhhubh)}(hhh](h)}(h Merkle treeh]h Merkle tree}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hX The file contents is divided into blocks, where the block size is configurable but is usually 4096 bytes. The end of the last block is zero-padded if needed. Each block is then hashed, producing the first level of hashes. Then, the hashes in this first level are grouped into 'blocksize'-byte blocks (zero-padding the ends as needed) and these blocks are hashed, producing the second level of hashes. This proceeds up the tree until only a single block remains. The hash of this block is the "Merkle tree root hash".h]hXThe file contents is divided into blocks, where the block size is configurable but is usually 4096 bytes. The end of the last block is zero-padded if needed. Each block is then hashed, producing the first level of hashes. Then, the hashes in this first level are grouped into ‘blocksize’-byte blocks (zero-padding the ends as needed) and these blocks are hashed, producing the second level of hashes. This proceeds up the tree until only a single block remains. The hash of this block is the “Merkle tree root hash”.}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hIf the file fits in one block and is nonempty, then the "Merkle tree root hash" is simply the hash of the single data block. If the file is empty, then the "Merkle tree root hash" is all zeroes.h]hIf the file fits in one block and is nonempty, then the “Merkle tree root hash” is simply the hash of the single data block. If the file is empty, then the “Merkle tree root hash” is all zeroes.}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hFThe "blocks" here are not necessarily the same as "filesystem blocks".h]hNThe “blocks” here are not necessarily the same as “filesystem blocks”.}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX If a salt was specified, then it's zero-padded to the closest multiple of the input size of the hash algorithm's compression function, e.g. 64 bytes for SHA-256 or 128 bytes for SHA-512. The padded salt is prepended to every data or Merkle tree block that is hashed.h]hXIf a salt was specified, then it’s zero-padded to the closest multiple of the input size of the hash algorithm’s compression function, e.g. 64 bytes for SHA-256 or 128 bytes for SHA-512. The padded salt is prepended to every data or Merkle tree block that is hashed.}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXIThe purpose of the block padding is to cause every hash to be taken over the same amount of data, which simplifies the implementation and keeps open more possibilities for hardware acceleration. The purpose of the salt padding is to make the salting "free" when the salted hash state is precomputed, then imported for each hash.h]hXMThe purpose of the block padding is to cause every hash to be taken over the same amount of data, which simplifies the implementation and keeps open more possibilities for hardware acceleration. The purpose of the salt padding is to make the salting “free” when the salted hash state is precomputed, then imported for each hash.}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXExample: in the recommended configuration of SHA-256 and 4K blocks, 128 hash values fit in each block. Thus, each level of the Merkle tree is approximately 128 times smaller than the previous, and for large files the Merkle tree's size converges to approximately 1/127 of the original file size. However, for small files, the padding is significant, making the space overhead proportionally more.h]hXExample: in the recommended configuration of SHA-256 and 4K blocks, 128 hash values fit in each block. Thus, each level of the Merkle tree is approximately 128 times smaller than the previous, and for large files the Merkle tree’s size converges to approximately 1/127 of the original file size. However, for small files, the padding is significant, making the space overhead proportionally more.}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h.. _fsverity_descriptor:h]h}(h]h ]h"]h$]h&]hfsverity-descriptoruh1hhMhjhhhhubeh}(h](jS jeh ]h"]( merkle treefsverity_merkle_treeeh$]h&]uh1hhj hhhhhMj }jj sj }jj sj5Kubh)}(hhh](h)}(hfs-verity descriptorh]hfs-verity descriptor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXBy itself, the Merkle tree root hash is ambiguous. For example, it can't a distinguish a large file from a small second file whose data is exactly the top-level hash block of the first file. Ambiguities also arise from the convention of padding to the next block boundary.h]hXBy itself, the Merkle tree root hash is ambiguous. For example, it can’t a distinguish a large file from a small second file whose data is exactly the top-level hash block of the first file. Ambiguities also arise from the convention of padding to the next block boundary.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hTo solve this problem, the fs-verity file digest is actually computed as a hash of the following structure, which contains the Merkle tree root hash as well as other fields such as the file size::h]hTo solve this problem, the fs-verity file digest is actually computed as a hash of the following structure, which contains the Merkle tree root hash as well as other fields such as the file size:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hX[struct fsverity_descriptor { __u8 version; /* must be 1 */ __u8 hash_algorithm; /* Merkle tree hash algorithm */ __u8 log_blocksize; /* log2 of size of data and tree blocks */ __u8 salt_size; /* size of salt in bytes; 0 if none */ __le32 __reserved_0x04; /* must be 0 */ __le64 data_size; /* size of file the Merkle tree is built over */ __u8 root_hash[64]; /* Merkle tree root hash */ __u8 salt[32]; /* salt prepended to each hashed block */ __u8 __reserved[144]; /* must be 0's */ };h]hX[struct fsverity_descriptor { __u8 version; /* must be 1 */ __u8 hash_algorithm; /* Merkle tree hash algorithm */ __u8 log_blocksize; /* log2 of size of data and tree blocks */ __u8 salt_size; /* size of salt in bytes; 0 if none */ __le32 __reserved_0x04; /* must be 0 */ __le64 data_size; /* size of file the Merkle tree is built over */ __u8 root_hash[64]; /* Merkle tree root hash */ __u8 salt[32]; /* salt prepended to each hashed block */ __u8 __reserved[144]; /* must be 0's */ };}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubeh}(h](j jeh ]h"](fs-verity descriptorfsverity_descriptoreh$]h&]uh1hhj hhhhhMj }jj}sj }jj}sj5Kubeh}(h]file-digest-computationah ]h"]file digest computationah$]h&]uh1hhhhhhhhM{ubh)}(hhh](h)}(hBuilt-in signature verificationh]hBuilt-in signature verification}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hoCONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds supports for in-kernel verification of fs-verity builtin signatures.h]hoCONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds supports for in-kernel verification of fs-verity builtin signatures.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXI**IMPORTANT**! Please take great care before using this feature. It is not the only way to do signatures with fs-verity, and the alternatives (such as userspace signature verification, and IMA appraisal) can be much better. It's also easy to fall into a trap of thinking this feature solves more problems than it actually does.h](hstrong)}(h **IMPORTANT**h]h IMPORTANT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX>! Please take great care before using this feature. It is not the only way to do signatures with fs-verity, and the alternatives (such as userspace signature verification, and IMA appraisal) can be much better. It’s also easy to fall into a trap of thinking this feature solves more problems than it actually does.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h(Enabling this option adds the following:h]h(Enabling this option adds the following:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubhenumerated_list)}(hhh](j)}(hAt boot time, the kernel creates a keyring named ".fs-verity". The root user can add trusted X.509 certificates to this keyring using the add_key() system call. h]h)}(hAt boot time, the kernel creates a keyring named ".fs-verity". The root user can add trusted X.509 certificates to this keyring using the add_key() system call.h]hAt boot time, the kernel creates a keyring named “.fs-verity”. The root user can add trusted X.509 certificates to this keyring using the add_key() system call.}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj/ubah}(h]h ]h"]h$]h&]uh1jhj,hhhhhNubj)}(hX`FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted detached signature in DER format of the file's fs-verity digest. On success, the ioctl persists the signature alongside the Merkle tree. Then, any time the file is opened, the kernel verifies the file's actual digest against this signature, using the certificates in the ".fs-verity" keyring. This verification happens as long as the file's signature exists, regardless of the state of the sysctl variable "fs.verity.require_signatures" described in the next item. The IPE LSM relies on this behavior to recognize and label fsverity files that contain a verified built-in fsverity signature. h]h)}(hX`FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted detached signature in DER format of the file's fs-verity digest. On success, the ioctl persists the signature alongside the Merkle tree. Then, any time the file is opened, the kernel verifies the file's actual digest against this signature, using the certificates in the ".fs-verity" keyring. This verification happens as long as the file's signature exists, regardless of the state of the sysctl variable "fs.verity.require_signatures" described in the next item. The IPE LSM relies on this behavior to recognize and label fsverity files that contain a verified built-in fsverity signature.h](j)}(h`FS_IOC_ENABLE_VERITY`_h]hFS_IOC_ENABLE_VERITY}(hjOhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_ENABLE_VERITYhj\uh1jhjKjKubhX accepts a pointer to a PKCS#7 formatted detached signature in DER format of the file’s fs-verity digest. On success, the ioctl persists the signature alongside the Merkle tree. Then, any time the file is opened, the kernel verifies the file’s actual digest against this signature, using the certificates in the “.fs-verity” keyring. This verification happens as long as the file’s signature exists, regardless of the state of the sysctl variable “fs.verity.require_signatures” described in the next item. The IPE LSM relies on this behavior to recognize and label fsverity files that contain a verified built-in fsverity signature.}(hjKhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGubah}(h]h ]h"]h$]h&]uh1jhj,hhhhhNubj)}(hA new sysctl "fs.verity.require_signatures" is made available. When set to 1, the kernel requires that all verity files have a correctly signed digest as described in (2). h]h)}(hA new sysctl "fs.verity.require_signatures" is made available. When set to 1, the kernel requires that all verity files have a correctly signed digest as described in (2).h]hA new sysctl “fs.verity.require_signatures” is made available. When set to 1, the kernel requires that all verity files have a correctly signed digest as described in (2).}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjoubah}(h]h ]h"]h$]h&]uh1jhj,hhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1j*hjhhhhhMubh)}(h}The data that the signature as described in (2) must be a signature of is the fs-verity file digest in the following format::h]h|The data that the signature as described in (2) must be a signature of is the fs-verity file digest in the following format:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hstruct fsverity_formatted_digest { char magic[8]; /* must be "FSVerity" */ __le16 digest_algorithm; __le16 digest_size; __u8 digest[]; };h]hstruct fsverity_formatted_digest { char magic[8]; /* must be "FSVerity" */ __le16 digest_algorithm; __le16 digest_size; __u8 digest[]; };}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubh)}(hX;That's it. It should be emphasized again that fs-verity builtin signatures are not the only way to do signatures with fs-verity. See `Use cases`_ for an overview of ways in which fs-verity can be used. fs-verity builtin signatures have some major limitations that should be carefully considered before using them:h](hThat’s it. It should be emphasized again that fs-verity builtin signatures are not the only way to do signatures with fs-verity. See }(hjhhhNhNubj)}(h `Use cases`_h]h Use cases}(hjhhhNhNubah}(h]h ]h"]h$]h&]name Use caseshjuh1jhjjKubh for an overview of ways in which fs-verity can be used. fs-verity builtin signatures have some major limitations that should be carefully considered before using them:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hhh](j)}(hXBuiltin signature verification does *not* make the kernel enforce that any files actually have fs-verity enabled. Thus, it is not a complete authentication policy. Currently, if it is used, one way to complete the authentication policy is for trusted userspace code to explicitly check whether files have fs-verity enabled with a signature before they are accessed. (With fs.verity.require_signatures=1, just checking whether fs-verity is enabled suffices.) But, in this case the trusted userspace code could just store the signature alongside the file and verify it itself using a cryptographic library, instead of using this feature. h]h)}(hXBuiltin signature verification does *not* make the kernel enforce that any files actually have fs-verity enabled. Thus, it is not a complete authentication policy. Currently, if it is used, one way to complete the authentication policy is for trusted userspace code to explicitly check whether files have fs-verity enabled with a signature before they are accessed. (With fs.verity.require_signatures=1, just checking whether fs-verity is enabled suffices.) But, in this case the trusted userspace code could just store the signature alongside the file and verify it itself using a cryptographic library, instead of using this feature.h](h$Builtin signature verification does }(hjhhhNhNubhemphasis)}(h*not*h]hnot}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhXV make the kernel enforce that any files actually have fs-verity enabled. Thus, it is not a complete authentication policy. Currently, if it is used, one way to complete the authentication policy is for trusted userspace code to explicitly check whether files have fs-verity enabled with a signature before they are accessed. (With fs.verity.require_signatures=1, just checking whether fs-verity is enabled suffices.) But, in this case the trusted userspace code could just store the signature alongside the file and verify it itself using a cryptographic library, instead of using this feature.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXAnother approach is to utilize fs-verity builtin signature verification in conjunction with the IPE LSM, which supports defining a kernel-enforced, system-wide authentication policy that allows only files with a verified fs-verity builtin signature to perform certain operations, such as execution. Note that IPE doesn't require fs.verity.require_signatures=1. Please refer to :doc:`IPE admin guide ` for more details. h]h)}(hXAnother approach is to utilize fs-verity builtin signature verification in conjunction with the IPE LSM, which supports defining a kernel-enforced, system-wide authentication policy that allows only files with a verified fs-verity builtin signature to perform certain operations, such as execution. Note that IPE doesn't require fs.verity.require_signatures=1. Please refer to :doc:`IPE admin guide ` for more details.h](hX{Another approach is to utilize fs-verity builtin signature verification in conjunction with the IPE LSM, which supports defining a kernel-enforced, system-wide authentication policy that allows only files with a verified fs-verity builtin signature to perform certain operations, such as execution. Note that IPE doesn’t require fs.verity.require_signatures=1. Please refer to }(hjhhhNhNubh)}(h-:doc:`IPE admin guide `h]jY)}(hj h]hIPE admin guide}(hjhhhNhNubah}(h]h ](jdstdstd-doceh"]h$]h&]uh1jXhj ubah}(h]h ]h"]h$]h&]refdocjq refdomainjreftypedoc refexplicitrefwarnjw/admin-guide/LSM/ipeuh1hhhhMhjubh for more details.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hA file's builtin signature can only be set at the same time that fs-verity is being enabled on the file. Changing or deleting the builtin signature later requires re-creating the file. h]h)}(hA file's builtin signature can only be set at the same time that fs-verity is being enabled on the file. Changing or deleting the builtin signature later requires re-creating the file.h]hA file’s builtin signature can only be set at the same time that fs-verity is being enabled on the file. Changing or deleting the builtin signature later requires re-creating the file.}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj;ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hBuiltin signature verification uses the same set of public keys for all fs-verity enabled files on the system. Different keys cannot be trusted for different files; each key is all or nothing. h]h)}(hBuiltin signature verification uses the same set of public keys for all fs-verity enabled files on the system. Different keys cannot be trusted for different files; each key is all or nothing.h]hBuiltin signature verification uses the same set of public keys for all fs-verity enabled files on the system. Different keys cannot be trusted for different files; each key is all or nothing.}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjSubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hThe sysctl fs.verity.require_signatures applies system-wide. Setting it to 1 only works when all users of fs-verity on the system agree that it should be set to 1. This limitation can prevent fs-verity from being used in cases where it would be helpful. h]h)}(hThe sysctl fs.verity.require_signatures applies system-wide. Setting it to 1 only works when all users of fs-verity on the system agree that it should be set to 1. This limitation can prevent fs-verity from being used in cases where it would be helpful.h]hThe sysctl fs.verity.require_signatures applies system-wide. Setting it to 1 only works when all users of fs-verity on the system agree that it should be set to 1. This limitation can prevent fs-verity from being used in cases where it would be helpful.}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjkubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hBuiltin signature verification can only use signature algorithms that are supported by the kernel. For example, the kernel does not yet support Ed25519, even though this is often the signature algorithm that is recommended for new cryptographic designs. h]h)}(hBuiltin signature verification can only use signature algorithms that are supported by the kernel. For example, the kernel does not yet support Ed25519, even though this is often the signature algorithm that is recommended for new cryptographic designs.h]hBuiltin signature verification can only use signature algorithms that are supported by the kernel. For example, the kernel does not yet support Ed25519, even though this is often the signature algorithm that is recommended for new cryptographic designs.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXvfs-verity builtin signatures are in PKCS#7 format, and the public keys are in X.509 format. These formats are commonly used, including by some other kernel features (which is why the fs-verity builtin signatures use them), and are very feature rich. Unfortunately, history has shown that code that parses and handles these formats (which are from the 1990s and are based on ASN.1) often has vulnerabilities as a result of their complexity. This complexity is not inherent to the cryptography itself. fs-verity users who do not need advanced features of X.509 and PKCS#7 should strongly consider using simpler formats, such as plain Ed25519 keys and signatures, and verifying signatures in userspace. fs-verity users who choose to use X.509 and PKCS#7 anyway should still consider that verifying those signatures in userspace is more flexible (for other reasons mentioned earlier in this document) and eliminates the need to enable CONFIG_FS_VERITY_BUILTIN_SIGNATURES and its associated increase in kernel attack surface. In some cases it can even be necessary, since advanced X.509 and PKCS#7 features do not always work as intended with the kernel. For example, the kernel does not check X.509 certificate validity times. Note: IMA appraisal, which supports fs-verity, does not use PKCS#7 for its signatures, so it partially avoids the issues discussed here. IMA appraisal does use X.509. h](h)}(hXfs-verity builtin signatures are in PKCS#7 format, and the public keys are in X.509 format. These formats are commonly used, including by some other kernel features (which is why the fs-verity builtin signatures use them), and are very feature rich. Unfortunately, history has shown that code that parses and handles these formats (which are from the 1990s and are based on ASN.1) often has vulnerabilities as a result of their complexity. This complexity is not inherent to the cryptography itself.h]hXfs-verity builtin signatures are in PKCS#7 format, and the public keys are in X.509 format. These formats are commonly used, including by some other kernel features (which is why the fs-verity builtin signatures use them), and are very feature rich. Unfortunately, history has shown that code that parses and handles these formats (which are from the 1990s and are based on ASN.1) often has vulnerabilities as a result of their complexity. This complexity is not inherent to the cryptography itself.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(hfs-verity users who do not need advanced features of X.509 and PKCS#7 should strongly consider using simpler formats, such as plain Ed25519 keys and signatures, and verifying signatures in userspace.h]hfs-verity users who do not need advanced features of X.509 and PKCS#7 should strongly consider using simpler formats, such as plain Ed25519 keys and signatures, and verifying signatures in userspace.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM%hjubh)}(hX fs-verity users who choose to use X.509 and PKCS#7 anyway should still consider that verifying those signatures in userspace is more flexible (for other reasons mentioned earlier in this document) and eliminates the need to enable CONFIG_FS_VERITY_BUILTIN_SIGNATURES and its associated increase in kernel attack surface. In some cases it can even be necessary, since advanced X.509 and PKCS#7 features do not always work as intended with the kernel. For example, the kernel does not check X.509 certificate validity times.h]hX fs-verity users who choose to use X.509 and PKCS#7 anyway should still consider that verifying those signatures in userspace is more flexible (for other reasons mentioned earlier in this document) and eliminates the need to enable CONFIG_FS_VERITY_BUILTIN_SIGNATURES and its associated increase in kernel attack surface. In some cases it can even be necessary, since advanced X.509 and PKCS#7 features do not always work as intended with the kernel. For example, the kernel does not check X.509 certificate validity times.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM)hjubh)}(hNote: IMA appraisal, which supports fs-verity, does not use PKCS#7 for its signatures, so it partially avoids the issues discussed here. IMA appraisal does use X.509.h]hNote: IMA appraisal, which supports fs-verity, does not use PKCS#7 for its signatures, so it partially avoids the issues discussed here. IMA appraisal does use X.509.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hjubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubeh}(h]jah ]h"]built-in signature verificationah$]h&]uh1hhhhhhhhMj5Kubh)}(hhh](h)}(hFilesystem supporth]hFilesystem support}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM7ubh)}(hfs-verity is supported by several filesystems, described below. The CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on any of these filesystems.h]hfs-verity is supported by several filesystems, described below. The CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on any of these filesystems.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM9hjhhubh)}(hX``include/linux/fsverity.h`` declares the interface between the ``fs/verity/`` support layer and filesystems. Briefly, filesystems must provide an ``fsverity_operations`` structure that provides methods to read and write the verity metadata to a filesystem-specific location, including the Merkle tree blocks and ``fsverity_descriptor``. Filesystems must also call functions in ``fs/verity/`` at certain times, such as when a file is opened or when pages have been read into the pagecache. (See `Verifying data`_.)h](h)}(h``include/linux/fsverity.h``h]hinclude/linux/fsverity.h}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh$ declares the interface between the }(hj hhhNhNubh)}(h``fs/verity/``h]h fs/verity/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhF support layer and filesystems. Briefly, filesystems must provide an }(hj hhhNhNubh)}(h``fsverity_operations``h]hfsverity_operations}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh structure that provides methods to read and write the verity metadata to a filesystem-specific location, including the Merkle tree blocks and }(hj hhhNhNubh)}(h``fsverity_descriptor``h]hfsverity_descriptor}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh+. Filesystems must also call functions in }(hj hhhNhNubh)}(h``fs/verity/``h]h fs/verity/}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhh at certain times, such as when a file is opened or when pages have been read into the pagecache. (See }(hj hhhNhNubj)}(h`Verifying data`_h]hVerifying data}(hjghhhNhNubah}(h]h ]h"]h$]h&]nameVerifying datahverifying-datauh1jhj jKubh.)}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM=hjhhubh)}(hhh](h)}(hext4h]hext4}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMGubh)}(h?ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.h]h?ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhjhhubh)}(hXNTo create verity files on an ext4 filesystem, the filesystem must have been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on it. "verity" is an RO_COMPAT filesystem feature, so once set, old kernels will only be able to mount the filesystem readonly, and old versions of e2fsck will be unable to check the filesystem.h](h[To create verity files on an ext4 filesystem, the filesystem must have been formatted with }(hjhhhNhNubh)}(h ``-O verity``h]h -O verity}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh or had }(hjhhhNhNubh)}(h``tune2fs -O verity``h]htune2fs -O verity}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh run on it. “verity” is an RO_COMPAT filesystem feature, so once set, old kernels will only be able to mount the filesystem readonly, and old versions of e2fsck will be unable to check the filesystem.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMKhjhhubh)}(hOriginally, an ext4 filesystem with the "verity" feature could only be mounted when its block size was equal to the system page size (typically 4096 bytes). In Linux v6.3, this limitation was removed.h]hOriginally, an ext4 filesystem with the “verity” feature could only be mounted when its block size was equal to the system page size (typically 4096 bytes). In Linux v6.3, this limitation was removed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMQhjhhubh)}(hext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared.h](hXext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It can only be set by }(hjhhhNhNubj)}(h`FS_IOC_ENABLE_VERITY`_h]hFS_IOC_ENABLE_VERITY}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_ENABLE_VERITYhj\uh1jhjjKubh, and it cannot be cleared.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMUhjhhubh)}(hXext4 also supports encryption, which can be used simultaneously with fs-verity. In this case, the plaintext data is verified rather than the ciphertext. This is necessary in order to make the fs-verity file digest meaningful, since every file is encrypted differently.h]hXext4 also supports encryption, which can be used simultaneously with fs-verity. In this case, the plaintext data is verified rather than the ciphertext. This is necessary in order to make the fs-verity file digest meaningful, since every file is encrypted differently.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjhhubh)}(hXext4 stores the verity metadata (Merkle tree and fsverity_descriptor) past the end of the file, starting at the first 64K boundary beyond i_size. This approach works because (a) verity files are readonly, and (b) pages fully beyond i_size aren't visible to userspace but can be read/written internally by ext4 with only some relatively small changes to ext4. This approach avoids having to depend on the EA_INODE feature and on rearchitecturing ext4's xattr support to support paging multi-gigabyte xattrs into memory, and to support encrypting xattrs. Note that the verity metadata *must* be encrypted when the file is, since it contains hashes of the plaintext data.h](hXNext4 stores the verity metadata (Merkle tree and fsverity_descriptor) past the end of the file, starting at the first 64K boundary beyond i_size. This approach works because (a) verity files are readonly, and (b) pages fully beyond i_size aren’t visible to userspace but can be read/written internally by ext4 with only some relatively small changes to ext4. This approach avoids having to depend on the EA_INODE feature and on rearchitecturing ext4’s xattr support to support paging multi-gigabyte xattrs into memory, and to support encrypting xattrs. Note that the verity metadata }(hjhhhNhNubj)}(h*must*h]hmust}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhO be encrypted when the file is, since it contains hashes of the plaintext data.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM]hjhhubh)}(h.ext4 only allows verity on extent-based files.h]h.ext4 only allows verity on extent-based files.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhhjhhubeh}(h]ext4ah ]h"]ext4ah$]h&]uh1hhjhhhhhMGubh)}(hhh](h)}(hf2fsh]hf2fs}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGhhhhhMkubh)}(h@f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.h]h@f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMmhjGhhubh)}(hiTo create verity files on an f2fs filesystem, the filesystem must have been formatted with ``-O verity``.h](h[To create verity files on an f2fs filesystem, the filesystem must have been formatted with }(hjfhhhNhNubh)}(h ``-O verity``h]h -O verity}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjfubh.}(hjfhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMohjGhhubh)}(hf2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files. It can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared.h](h[f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files. It can only be set by }(hjhhhNhNubj)}(h`FS_IOC_ENABLE_VERITY`_h]hFS_IOC_ENABLE_VERITY}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_ENABLE_VERITYhj\uh1jhjjKubh, and it cannot be cleared.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMrhjGhhubh)}(hXILike ext4, f2fs stores the verity metadata (Merkle tree and fsverity_descriptor) past the end of the file, starting at the first 64K boundary beyond i_size. See explanation for ext4 above. Moreover, f2fs supports at most 4096 bytes of xattr entries per inode which usually wouldn't be enough for even a single Merkle tree block.h]hXKLike ext4, f2fs stores the verity metadata (Merkle tree and fsverity_descriptor) past the end of the file, starting at the first 64K boundary beyond i_size. See explanation for ext4 above. Moreover, f2fs supports at most 4096 bytes of xattr entries per inode which usually wouldn’t be enough for even a single Merkle tree block.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMvhjGhhubh)}(hdf2fs doesn't support enabling verity on files that currently have atomic or volatile writes pending.h]hff2fs doesn’t support enabling verity on files that currently have atomic or volatile writes pending.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM|hjGhhubeh}(h]f2fsah ]h"]f2fsah$]h&]uh1hhjhhhhhMkubh)}(hhh](h)}(hbtrfsh]hbtrfs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hbtrfs supports fs-verity since Linux v5.15. Verity-enabled inodes are marked with a RO_COMPAT inode flag, and the verity metadata is stored in separate btree items.h]hbtrfs supports fs-verity since Linux v5.15. Verity-enabled inodes are marked with a RO_COMPAT inode flag, and the verity metadata is stored in separate btree items.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]btrfsah ]h"]btrfsah$]h&]uh1hhjhhhhhMubeh}(h]jah ]h"]filesystem supportah$]h&]uh1hhhhhhhhM7j5Kubh)}(hhh](h)}(hImplementation detailsh]hImplementation details}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hVerifying datah]hVerifying data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hXTfs-verity ensures that all reads of a verity file's data are verified, regardless of which syscall is used to do the read (e.g. mmap(), read(), pread()) and regardless of whether it's the first read or a later read (unless the later read can return cached data that was already verified). Below, we describe how filesystems implement this.h]hXXfs-verity ensures that all reads of a verity file’s data are verified, regardless of which syscall is used to do the read (e.g. mmap(), read(), pread()) and regardless of whether it’s the first read or a later read (unless the later read can return cached data that was already verified). Below, we describe how filesystems implement this.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hhh](h)}(h Pagecacheh]h Pagecache}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj*hhhhhMubh)}(hXFor filesystems using Linux's pagecache, the ``->read_folio()`` and ``->readahead()`` methods must be modified to verify folios before they are marked Uptodate. Merely hooking ``->read_iter()`` would be insufficient, since ``->read_iter()`` is not used for memory maps.h](h/For filesystems using Linux’s pagecache, the }(hj;hhhNhNubh)}(h``->read_folio()``h]h->read_folio()}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;ubh and }(hj;hhhNhNubh)}(h``->readahead()``h]h ->readahead()}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;ubh\ methods must be modified to verify folios before they are marked Uptodate. Merely hooking }(hj;hhhNhNubh)}(h``->read_iter()``h]h ->read_iter()}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;ubh would be insufficient, since }(hj;hhhNhNubh)}(h``->read_iter()``h]h ->read_iter()}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;ubh is not used for memory maps.}(hj;hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hXTherefore, fs/verity/ provides the function fsverity_verify_blocks() which verifies data that has been read into the pagecache of a verity inode. The containing folio must still be locked and not Uptodate, so it's not yet readable by userspace. As needed to do the verification, fsverity_verify_blocks() will call back into the filesystem to read hash blocks via fsverity_operations::read_merkle_tree_page().h]hXTherefore, fs/verity/ provides the function fsverity_verify_blocks() which verifies data that has been read into the pagecache of a verity inode. The containing folio must still be locked and not Uptodate, so it’s not yet readable by userspace. As needed to do the verification, fsverity_verify_blocks() will call back into the filesystem to read hash blocks via fsverity_operations::read_merkle_tree_page().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hX\fsverity_verify_blocks() returns false if verification failed; in this case, the filesystem must not set the folio Uptodate. Following this, as per the usual Linux pagecache behavior, attempts by userspace to read() from the part of the file containing the folio will fail with EIO, and accesses to the folio within a memory map will raise SIGBUS.h]hX\fsverity_verify_blocks() returns false if verification failed; in this case, the filesystem must not set the folio Uptodate. Following this, as per the usual Linux pagecache behavior, attempts by userspace to read() from the part of the file containing the folio will fail with EIO, and accesses to the folio within a memory map will raise SIGBUS.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hXhIn principle, verifying a data block requires verifying the entire path in the Merkle tree from the data block to the root hash. However, for efficiency the filesystem may cache the hash blocks. Therefore, fsverity_verify_blocks() only ascends the tree reading hash blocks until an already-verified hash block is seen. It then verifies the path to that block.h]hXhIn principle, verifying a data block requires verifying the entire path in the Merkle tree from the data block to the root hash. However, for efficiency the filesystem may cache the hash blocks. Therefore, fsverity_verify_blocks() only ascends the tree reading hash blocks until an already-verified hash block is seen. It then verifies the path to that block.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hXNThis optimization, which is also used by dm-verity, results in excellent sequential read performance. This is because usually (e.g. 127 in 128 times for 4K blocks and SHA-256) the hash block from the bottom level of the tree will already be cached and checked from reading a previous data block. However, random reads perform worse.h]hXNThis optimization, which is also used by dm-verity, results in excellent sequential read performance. This is because usually (e.g. 127 in 128 times for 4K blocks and SHA-256) the hash block from the bottom level of the tree will already be cached and checked from reading a previous data block. However, random reads perform worse.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubeh}(h] pagecacheah ]h"] pagecacheah$]h&]uh1hhj hhhhhMubh)}(hhh](h)}(hBlock device based filesystemsh]hBlock device based filesystems}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXBlock device based filesystems (e.g. ext4 and f2fs) in Linux also use the pagecache, so the above subsection applies too. However, they also usually read many data blocks from a file at once, grouped into a structure called a "bio". To make it easier for these types of filesystems to support fs-verity, fs/verity/ also provides a function fsverity_verify_bio() which verifies all data blocks in a bio.h]hXBlock device based filesystems (e.g. ext4 and f2fs) in Linux also use the pagecache, so the above subsection applies too. However, they also usually read many data blocks from a file at once, grouped into a structure called a “bio”. To make it easier for these types of filesystems to support fs-verity, fs/verity/ also provides a function fsverity_verify_bio() which verifies all data blocks in a bio.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hext4 and f2fs also support encryption. If a verity file is also encrypted, the data must be decrypted before being verified. To support this, these filesystems allocate a "post-read context" for each bio and store it in ``->bi_private``::h](hext4 and f2fs also support encryption. If a verity file is also encrypted, the data must be decrypted before being verified. To support this, these filesystems allocate a “post-read context” for each bio and store it in }(hjhhhNhNubh)}(h``->bi_private``h]h ->bi_private}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hstruct bio_post_read_ctx { struct bio *bio; struct work_struct work; unsigned int cur_step; unsigned int enabled_steps; };h]hstruct bio_post_read_ctx { struct bio *bio; struct work_struct work; unsigned int cur_step; unsigned int enabled_steps; };}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubh)}(hX``enabled_steps`` is a bitmask that specifies whether decryption, verity, or both is enabled. After the bio completes, for each needed postprocessing step the filesystem enqueues the bio_post_read_ctx on a workqueue, and then the workqueue work does the decryption or verification. Finally, folios where no decryption or verity error occurred are marked Uptodate, and the folios are unlocked.h](h)}(h``enabled_steps``h]h enabled_steps}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhXy is a bitmask that specifies whether decryption, verity, or both is enabled. After the bio completes, for each needed postprocessing step the filesystem enqueues the bio_post_read_ctx on a workqueue, and then the workqueue work does the decryption or verification. Finally, folios where no decryption or verity error occurred are marked Uptodate, and the folios are unlocked.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXOn many filesystems, files can contain holes. Normally, ``->readahead()`` simply zeroes hole blocks and considers the corresponding data to be up-to-date; no bios are issued. To prevent this case from bypassing fs-verity, filesystems use fsverity_verify_blocks() to verify hole blocks.h](h9On many filesystems, files can contain holes. Normally, }(hj:hhhNhNubh)}(h``->readahead()``h]h ->readahead()}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj:ubh simply zeroes hole blocks and considers the corresponding data to be up-to-date; no bios are issued. To prevent this case from bypassing fs-verity, filesystems use fsverity_verify_blocks() to verify hole blocks.}(hj:hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hgFilesystems also disable direct I/O on verity files, since otherwise direct I/O would bypass fs-verity.h]hgFilesystems also disable direct I/O on verity files, since otherwise direct I/O would bypass fs-verity.}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]block-device-based-filesystemsah ]h"]block device based filesystemsah$]h&]uh1hhj hhhhhMubeh}(h]jwah ]h"]verifying dataah$]h&]uh1hhjhhhhhMj5Kubeh}(h]implementation-detailsah ]h"]implementation detailsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hUserspace utilityh]hUserspace utility}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(h[This document focuses on the kernel, but a userspace utility for fs-verity can be found at:h]h[This document focuses on the kernel, but a userspace utility for fs-verity can be found at:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh block_quote)}(h>https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git h]h)}(h=https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.gith]j)}(hjh]h=https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhhhMhjhhubh)}(hSee the README.md file in the fsverity-utils source tree for details, including examples of setting up fs-verity protected files.h]hSee the README.md file in the fsverity-utils source tree for details, including examples of setting up fs-verity protected files.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]userspace-utilityah ]h"]userspace utilityah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hTestsh]hTests}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hTo test fs-verity, use xfstests. For example, using `kvm-xfstests `_::h](h5To test fs-verity, use xfstests. For example, using }(hjhhhNhNubj)}(hc`kvm-xfstests `_h]h kvm-xfstests}(hjhhhNhNubah}(h]h ]h"]h$]h&]name kvm-xfstestsj&Qhttps://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.mduh1jhjubh)}(hT h]h}(h] kvm-xfstestsah ]h"] kvm-xfstestsah$]h&]refurijuh1hj5Khjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h)kvm-xfstests -c ext4,f2fs,btrfs -g verityh]h)kvm-xfstests -c ext4,f2fs,btrfs -g verity}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubeh}(h]testsah ]h"]testsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hFAQh]hFAQ}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj/hhhhhMubh)}(hThis section answers frequently asked questions about fs-verity that weren't already directly answered in other parts of this document.h]hThis section answers frequently asked questions about fs-verity that weren’t already directly answered in other parts of this document.}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj/hhubh field_list)}(hhh](hfield)}(hhh](h field_name)}(hQh]hQ}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjUhhhKubh field_body)}(h Why isn't fs-verity part of IMA?h]h)}(hjlh]h"Why isn’t fs-verity part of IMA?}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjjubah}(h]h ]h"]h$]h&]uh1jhhjUubeh}(h]h ]h"]h$]h&]uh1jShhhMhjPhhubjT)}(hhh](jY)}(hAh]hA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hXfs-verity and IMA (Integrity Measurement Architecture) have different focuses. fs-verity is a filesystem-level mechanism for hashing individual files using a Merkle tree. In contrast, IMA specifies a system-wide policy that specifies which files are hashed and what to do with those hashes, such as log them, authenticate them, or add them to a measurement list. IMA supports the fs-verity hashing mechanism as an alternative to full file hashes, for those who want the performance and security benefits of the Merkle tree based hash. However, it doesn't make sense to force all uses of fs-verity to be through IMA. fs-verity already meets many users' needs even as a standalone filesystem feature, and it's testable like other filesystem features e.g. with xfstests. h](h)}(hXlfs-verity and IMA (Integrity Measurement Architecture) have different focuses. fs-verity is a filesystem-level mechanism for hashing individual files using a Merkle tree. In contrast, IMA specifies a system-wide policy that specifies which files are hashed and what to do with those hashes, such as log them, authenticate them, or add them to a measurement list.h]hXlfs-verity and IMA (Integrity Measurement Architecture) have different focuses. fs-verity is a filesystem-level mechanism for hashing individual files using a Merkle tree. In contrast, IMA specifies a system-wide policy that specifies which files are hashed and what to do with those hashes, such as log them, authenticate them, or add them to a measurement list.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(hXIMA supports the fs-verity hashing mechanism as an alternative to full file hashes, for those who want the performance and security benefits of the Merkle tree based hash. However, it doesn't make sense to force all uses of fs-verity to be through IMA. fs-verity already meets many users' needs even as a standalone filesystem feature, and it's testable like other filesystem features e.g. with xfstests.h]hXIMA supports the fs-verity hashing mechanism as an alternative to full file hashes, for those who want the performance and security benefits of the Merkle tree based hash. However, it doesn’t make sense to force all uses of fs-verity to be through IMA. fs-verity already meets many users’ needs even as a standalone filesystem feature, and it’s testable like other filesystem features e.g. with xfstests.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubeh}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhMhjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(htIsn't fs-verity useless because the attacker can just modify the hashes in the Merkle tree, which is stored on-disk?h]h)}(htIsn't fs-verity useless because the attacker can just modify the hashes in the Merkle tree, which is stored on-disk?h]hvIsn’t fs-verity useless because the attacker can just modify the hashes in the Merkle tree, which is stored on-disk?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhMhjPhhubjT)}(hhh](jY)}(hjh]hA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hTo verify the authenticity of an fs-verity file you must verify the authenticity of the "fs-verity file digest", which incorporates the root hash of the Merkle tree. See `Use cases`_. h]h)}(hTo verify the authenticity of an fs-verity file you must verify the authenticity of the "fs-verity file digest", which incorporates the root hash of the Merkle tree. See `Use cases`_.h](hTo verify the authenticity of an fs-verity file you must verify the authenticity of the “fs-verity file digest”, which incorporates the root hash of the Merkle tree. See }(hjhhhNhNubj)}(h `Use cases`_h]h Use cases}(hjhhhNhNubah}(h]h ]h"]h$]h&]name Use caseshjuh1jhjjKubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhMhjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1jXhj4hhhKubji)}(hbIsn't fs-verity useless because the attacker can just replace a verity file with a non-verity one?h]h)}(hbIsn't fs-verity useless because the attacker can just replace a verity file with a non-verity one?h]hdIsn’t fs-verity useless because the attacker can just replace a verity file with a non-verity one?}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjDubah}(h]h ]h"]h$]h&]uh1jhhj4ubeh}(h]h ]h"]h$]h&]uh1jShhhM hjPhhubjT)}(hhh](jY)}(hjh]hA}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjbhhhKubji)}(hSee `Use cases`_. In the initial use case, it's really trusted userspace code that authenticates the files; fs-verity is just a tool to do this job efficiently and securely. The trusted userspace code will consider non-verity files to be inauthentic. h]h)}(hSee `Use cases`_. In the initial use case, it's really trusted userspace code that authenticates the files; fs-verity is just a tool to do this job efficiently and securely. The trusted userspace code will consider non-verity files to be inauthentic.h](hSee }(hjvhhhNhNubj)}(h `Use cases`_h]h Use cases}(hj~hhhNhNubah}(h]h ]h"]h$]h&]name Use caseshjuh1jhjvjKubh. In the initial use case, it’s really trusted userspace code that authenticates the files; fs-verity is just a tool to do this job efficiently and securely. The trusted userspace code will consider non-verity files to be inauthentic.}(hjvhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjrubah}(h]h ]h"]h$]h&]uh1jhhjbubeh}(h]h ]h"]h$]h&]uh1jShhhM hjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(h[Why does the Merkle tree need to be stored on-disk? Couldn't you store just the root hash?h]h)}(h[Why does the Merkle tree need to be stored on-disk? Couldn't you store just the root hash?h]h]Why does the Merkle tree need to be stored on-disk? Couldn’t you store just the root hash?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhMhjPhhubjT)}(hhh](jY)}(hjh]hA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hXIf the Merkle tree wasn't stored on-disk, then you'd have to compute the entire tree when the file is first accessed, even if just one byte is being read. This is a fundamental consequence of how Merkle tree hashing works. To verify a leaf node, you need to verify the whole path to the root hash, including the root node (the thing which the root hash is a hash of). But if the root node isn't stored on-disk, you have to compute it by hashing its children, and so on until you've actually hashed the entire file. That defeats most of the point of doing a Merkle tree-based hash, since if you have to hash the whole file ahead of time anyway, then you could simply do sha256(file) instead. That would be much simpler, and a bit faster too. It's true that an in-memory Merkle tree could still provide the advantage of verification on every read rather than just on the first read. However, it would be inefficient because every time a hash page gets evicted (you can't pin the entire Merkle tree into memory, since it may be very large), in order to restore it you again need to hash everything below it in the tree. This again defeats most of the point of doing a Merkle tree-based hash, since a single block read could trigger re-hashing gigabytes of data. h](h)}(hXIf the Merkle tree wasn't stored on-disk, then you'd have to compute the entire tree when the file is first accessed, even if just one byte is being read. This is a fundamental consequence of how Merkle tree hashing works. To verify a leaf node, you need to verify the whole path to the root hash, including the root node (the thing which the root hash is a hash of). But if the root node isn't stored on-disk, you have to compute it by hashing its children, and so on until you've actually hashed the entire file.h]hX If the Merkle tree wasn’t stored on-disk, then you’d have to compute the entire tree when the file is first accessed, even if just one byte is being read. This is a fundamental consequence of how Merkle tree hashing works. To verify a leaf node, you need to verify the whole path to the root hash, including the root node (the thing which the root hash is a hash of). But if the root node isn’t stored on-disk, you have to compute it by hashing its children, and so on until you’ve actually hashed the entire file.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(hThat defeats most of the point of doing a Merkle tree-based hash, since if you have to hash the whole file ahead of time anyway, then you could simply do sha256(file) instead. That would be much simpler, and a bit faster too.h]hThat defeats most of the point of doing a Merkle tree-based hash, since if you have to hash the whole file ahead of time anyway, then you could simply do sha256(file) instead. That would be much simpler, and a bit faster too.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(hXIt's true that an in-memory Merkle tree could still provide the advantage of verification on every read rather than just on the first read. However, it would be inefficient because every time a hash page gets evicted (you can't pin the entire Merkle tree into memory, since it may be very large), in order to restore it you again need to hash everything below it in the tree. This again defeats most of the point of doing a Merkle tree-based hash, since a single block read could trigger re-hashing gigabytes of data.h]hX It’s true that an in-memory Merkle tree could still provide the advantage of verification on every read rather than just on the first read. However, it would be inefficient because every time a hash page gets evicted (you can’t pin the entire Merkle tree into memory, since it may be very large), in order to restore it you again need to hash everything below it in the tree. This again defeats most of the point of doing a Merkle tree-based hash, since a single block read could trigger re-hashing gigabytes of data.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubeh}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhMhjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(h@But couldn't you store just the leaf nodes and compute the rest?h]h)}(hj.h]hBBut couldn’t you store just the leaf nodes and compute the rest?}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM)hj,ubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhM)hjPhhubjT)}(hhhp](jY)}(hjh]hA}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjIhhhKubji)}(hX5See previous answer; this really just moves up one level, since one could alternatively interpret the data blocks as being the leaf nodes of the Merkle tree. It's true that the tree can be computed much faster if the leaf level is stored rather than just the data, but that's only because each level is less than 1% the size of the level below (assuming the recommended settings of SHA-256 and 4K blocks). For the exact same reason, by storing "just the leaf nodes" you'd already be storing over 99% of the tree, so you might as well simply store the whole tree. h]h)}(hX4See previous answer; this really just moves up one level, since one could alternatively interpret the data blocks as being the leaf nodes of the Merkle tree. It's true that the tree can be computed much faster if the leaf level is stored rather than just the data, but that's only because each level is less than 1% the size of the level below (assuming the recommended settings of SHA-256 and 4K blocks). For the exact same reason, by storing "just the leaf nodes" you'd already be storing over 99% of the tree, so you might as well simply store the whole tree.h]hX>See previous answer; this really just moves up one level, since one could alternatively interpret the data blocks as being the leaf nodes of the Merkle tree. It’s true that the tree can be computed much faster if the leaf level is stored rather than just the data, but that’s only because each level is less than 1% the size of the level below (assuming the recommended settings of SHA-256 and 4K blocks). For the exact same reason, by storing “just the leaf nodes” you’d already be storing over 99% of the tree, so you might as well simply store the whole tree.}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hjYubah}(h]h ]h"]h$]h&]uh1jhhjIubeh}(h]h ]h"]h$]h&]uh1jShhhM*hjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjwhhhKubji)}(hvCan the Merkle tree be built ahead of time, e.g. distributed as part of a package that is installed to many computers?h]h)}(hvCan the Merkle tree be built ahead of time, e.g. distributed as part of a package that is installed to many computers?h]hvCan the Merkle tree be built ahead of time, e.g. distributed as part of a package that is installed to many computers?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hjubah}(h]h ]h"]h$]h&]uh1jhhjwubeh}(h]h ]h"]h$]h&]uh1jShhhM4hjPhhubjT)}(hhh](jY)}(hjh]hA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hXThis isn't currently supported. It was part of the original design, but was removed to simplify the kernel UAPI and because it wasn't a critical use case. Files are usually installed once and used many times, and cryptographic hashing is somewhat fast on most modern processors. h]h)}(hXThis isn't currently supported. It was part of the original design, but was removed to simplify the kernel UAPI and because it wasn't a critical use case. Files are usually installed once and used many times, and cryptographic hashing is somewhat fast on most modern processors.h]hXThis isn’t currently supported. It was part of the original design, but was removed to simplify the kernel UAPI and because it wasn’t a critical use case. Files are usually installed once and used many times, and cryptographic hashing is somewhat fast on most modern processors.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hjubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhM6hjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(h%Why doesn't fs-verity support writes?h]h)}(hjh]h'Why doesn’t fs-verity support writes?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM<hjubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhM<hjPhhubjT)}(hhh](jY)}(hjh]hA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hXBWrite support would be very difficult and would require a completely different design, so it's well outside the scope of fs-verity. Write support would require: - A way to maintain consistency between the data and hashes, including all levels of hashes, since corruption after a crash (especially of potentially the entire file!) is unacceptable. The main options for solving this are data journalling, copy-on-write, and log-structured volume. But it's very hard to retrofit existing filesystems with new consistency mechanisms. Data journalling is available on ext4, but is very slow. - Rebuilding the Merkle tree after every write, which would be extremely inefficient. Alternatively, a different authenticated dictionary structure such as an "authenticated skiplist" could be used. However, this would be far more complex. Compare it to dm-verity vs. dm-integrity. dm-verity is very simple: the kernel just verifies read-only data against a read-only Merkle tree. In contrast, dm-integrity supports writes but is slow, is much more complex, and doesn't actually support full-device authentication since it authenticates each sector independently, i.e. there is no "root hash". It doesn't really make sense for the same device-mapper target to support these two very different cases; the same applies to fs-verity. h](h)}(hWrite support would be very difficult and would require a completely different design, so it's well outside the scope of fs-verity. Write support would require:h]hWrite support would be very difficult and would require a completely different design, so it’s well outside the scope of fs-verity. Write support would require:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM=hjubj)}(hhh](j)}(hXA way to maintain consistency between the data and hashes, including all levels of hashes, since corruption after a crash (especially of potentially the entire file!) is unacceptable. The main options for solving this are data journalling, copy-on-write, and log-structured volume. But it's very hard to retrofit existing filesystems with new consistency mechanisms. Data journalling is available on ext4, but is very slow. h]h)}(hXA way to maintain consistency between the data and hashes, including all levels of hashes, since corruption after a crash (especially of potentially the entire file!) is unacceptable. The main options for solving this are data journalling, copy-on-write, and log-structured volume. But it's very hard to retrofit existing filesystems with new consistency mechanisms. Data journalling is available on ext4, but is very slow.h]hXA way to maintain consistency between the data and hashes, including all levels of hashes, since corruption after a crash (especially of potentially the entire file!) is unacceptable. The main options for solving this are data journalling, copy-on-write, and log-structured volume. But it’s very hard to retrofit existing filesystems with new consistency mechanisms. Data journalling is available on ext4, but is very slow.}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj%ubah}(h]h ]h"]h$]h&]uh1jhj"ubj)}(hRebuilding the Merkle tree after every write, which would be extremely inefficient. Alternatively, a different authenticated dictionary structure such as an "authenticated skiplist" could be used. However, this would be far more complex. h]h)}(hRebuilding the Merkle tree after every write, which would be extremely inefficient. Alternatively, a different authenticated dictionary structure such as an "authenticated skiplist" could be used. However, this would be far more complex.h]hRebuilding the Merkle tree after every write, which would be extremely inefficient. Alternatively, a different authenticated dictionary structure such as an “authenticated skiplist” could be used. However, this would be far more complex.}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhj=ubah}(h]h ]h"]h$]h&]uh1jhj"ubeh}(h]h ]h"]h$]h&]jjuh1jhhhMAhjubh)}(hXCompare it to dm-verity vs. dm-integrity. dm-verity is very simple: the kernel just verifies read-only data against a read-only Merkle tree. In contrast, dm-integrity supports writes but is slow, is much more complex, and doesn't actually support full-device authentication since it authenticates each sector independently, i.e. there is no "root hash". It doesn't really make sense for the same device-mapper target to support these two very different cases; the same applies to fs-verity.h]hXCompare it to dm-verity vs. dm-integrity. dm-verity is very simple: the kernel just verifies read-only data against a read-only Merkle tree. In contrast, dm-integrity supports writes but is slow, is much more complex, and doesn’t actually support full-device authentication since it authenticates each sector independently, i.e. there is no “root hash”. It doesn’t really make sense for the same device-mapper target to support these two very different cases; the same applies to fs-verity.}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhjubeh}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhM=hjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjuhhhKubji)}(hBSince verity files are immutable, why isn't the immutable bit set?h]h)}(hjh]hDSince verity files are immutable, why isn’t the immutable bit set?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMWhjubah}(h]h ]h"]h$]h&]uh1jhhjuubeh}(h]h ]h"]h$]h&]uh1jShhhMWhjPhhubjT)}(hhh](jY)}(hjh]hA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hXSThe existing "immutable" bit (FS_IMMUTABLE_FL) already has a specific set of semantics which not only make the file contents read-only, but also prevent the file from being deleted, renamed, linked to, or having its owner or mode changed. These extra properties are unwanted for fs-verity, so reusing the immutable bit isn't appropriate. h]h)}(hXRThe existing "immutable" bit (FS_IMMUTABLE_FL) already has a specific set of semantics which not only make the file contents read-only, but also prevent the file from being deleted, renamed, linked to, or having its owner or mode changed. These extra properties are unwanted for fs-verity, so reusing the immutable bit isn't appropriate.h]hXXThe existing “immutable” bit (FS_IMMUTABLE_FL) already has a specific set of semantics which not only make the file contents read-only, but also prevent the file from being deleted, renamed, linked to, or having its owner or mode changed. These extra properties are unwanted for fs-verity, so reusing the immutable bit isn’t appropriate.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhMXhjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hAWhy does the API use ioctls instead of setxattr() and getxattr()?h]h)}(hjh]hAWhy does the API use ioctls instead of setxattr() and getxattr()?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM_hjubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhM_hjPhhubjT)}(hhh](jY)}(hjh]hA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hAbusing the xattr interface for basically arbitrary syscalls is heavily frowned upon by most of the Linux filesystem developers. An xattr should really just be an xattr on-disk, not an API to e.g. magically trigger construction of a Merkle tree. h]h)}(hAbusing the xattr interface for basically arbitrary syscalls is heavily frowned upon by most of the Linux filesystem developers. An xattr should really just be an xattr on-disk, not an API to e.g. magically trigger construction of a Merkle tree.h]hAbusing the xattr interface for basically arbitrary syscalls is heavily frowned upon by most of the Linux filesystem developers. An xattr should really just be an xattr on-disk, not an API to e.g. magically trigger construction of a Merkle tree.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM`hj ubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhM`hjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1jXhj+hhhKubji)}(h*Does fs-verity support remote filesystems?h]h)}(hj=h]h*Does fs-verity support remote filesystems?}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMehj;ubah}(h]h ]h"]h$]h&]uh1jhhj+ubeh}(h]h ]h"]h$]h&]uh1jShhhMehjPhhubjT)}(hhh](jY)}(hjh]hA}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjXhhhKubji)}(hXJSo far all filesystems that have implemented fs-verity support are local filesystems, but in principle any filesystem that can store per-file verity metadata can support fs-verity, regardless of whether it's local or remote. Some filesystems may have fewer options of where to store the verity metadata; one possibility is to store it past the end of the file and "hide" it from userspace by manipulating i_size. The data verification functions provided by ``fs/verity/`` also assume that the filesystem uses the Linux pagecache, but both local and remote filesystems normally do so. h]h)}(hXISo far all filesystems that have implemented fs-verity support are local filesystems, but in principle any filesystem that can store per-file verity metadata can support fs-verity, regardless of whether it's local or remote. Some filesystems may have fewer options of where to store the verity metadata; one possibility is to store it past the end of the file and "hide" it from userspace by manipulating i_size. The data verification functions provided by ``fs/verity/`` also assume that the filesystem uses the Linux pagecache, but both local and remote filesystems normally do so.h](hXSo far all filesystems that have implemented fs-verity support are local filesystems, but in principle any filesystem that can store per-file verity metadata can support fs-verity, regardless of whether it’s local or remote. Some filesystems may have fewer options of where to store the verity metadata; one possibility is to store it past the end of the file and “hide” it from userspace by manipulating i_size. The data verification functions provided by }(hjlhhhNhNubh)}(h``fs/verity/``h]h fs/verity/}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhjlubhp also assume that the filesystem uses the Linux pagecache, but both local and remote filesystems normally do so.}(hjlhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMfhjhubah}(h]h ]h"]h$]h&]uh1jhhjXubeh}(h]h ]h"]h$]h&]uh1jShhhMfhjPhhubjT)}(hhh](jY)}(hj\h]hQ}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hjWhy is anything filesystem-specific at all? Shouldn't fs-verity be implemented entirely at the VFS level?h]h)}(hjWhy is anything filesystem-specific at all? Shouldn't fs-verity be implemented entirely at the VFS level?h]hlWhy is anything filesystem-specific at all? Shouldn’t fs-verity be implemented entirely at the VFS level?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMphjubah}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhMphjPhhubjT)}(hhh](jY)}(hjh]hA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jXhjhhhKubji)}(hXThere are many reasons why this is not possible or would be very difficult, including the following: - To prevent bypassing verification, folios must not be marked Uptodate until they've been verified. Currently, each filesystem is responsible for marking folios Uptodate via ``->readahead()``. Therefore, currently it's not possible for the VFS to do the verification on its own. Changing this would require significant changes to the VFS and all filesystems. - It would require defining a filesystem-independent way to store the verity metadata. Extended attributes don't work for this because (a) the Merkle tree may be gigabytes, but many filesystems assume that all xattrs fit into a single 4K filesystem block, and (b) ext4 and f2fs encryption doesn't encrypt xattrs, yet the Merkle tree *must* be encrypted when the file contents are, because it stores hashes of the plaintext file contents. So the verity metadata would have to be stored in an actual file. Using a separate file would be very ugly, since the metadata is fundamentally part of the file to be protected, and it could cause problems where users could delete the real file but not the metadata file or vice versa. On the other hand, having it be in the same file would break applications unless filesystems' notion of i_size were divorced from the VFS's, which would be complex and require changes to all filesystems. - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's transaction mechanism so that either the file ends up with verity enabled, or no changes were made. Allowing intermediate states to occur after a crash may cause problems.h](h)}(hdThere are many reasons why this is not possible or would be very difficult, including the following:h]hdThere are many reasons why this is not possible or would be very difficult, including the following:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMrhjubj)}(hhh](j)}(hXiTo prevent bypassing verification, folios must not be marked Uptodate until they've been verified. Currently, each filesystem is responsible for marking folios Uptodate via ``->readahead()``. Therefore, currently it's not possible for the VFS to do the verification on its own. Changing this would require significant changes to the VFS and all filesystems. h]h)}(hXhTo prevent bypassing verification, folios must not be marked Uptodate until they've been verified. Currently, each filesystem is responsible for marking folios Uptodate via ``->readahead()``. Therefore, currently it's not possible for the VFS to do the verification on its own. Changing this would require significant changes to the VFS and all filesystems.h](hTo prevent bypassing verification, folios must not be marked Uptodate until they’ve been verified. Currently, each filesystem is responsible for marking folios Uptodate via }(hjhhhNhNubh)}(h``->readahead()``h]h ->readahead()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh. Therefore, currently it’s not possible for the VFS to do the verification on its own. Changing this would require significant changes to the VFS and all filesystems.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMuhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hXIt would require defining a filesystem-independent way to store the verity metadata. Extended attributes don't work for this because (a) the Merkle tree may be gigabytes, but many filesystems assume that all xattrs fit into a single 4K filesystem block, and (b) ext4 and f2fs encryption doesn't encrypt xattrs, yet the Merkle tree *must* be encrypted when the file contents are, because it stores hashes of the plaintext file contents. So the verity metadata would have to be stored in an actual file. Using a separate file would be very ugly, since the metadata is fundamentally part of the file to be protected, and it could cause problems where users could delete the real file but not the metadata file or vice versa. On the other hand, having it be in the same file would break applications unless filesystems' notion of i_size were divorced from the VFS's, which would be complex and require changes to all filesystems. h](h)}(hXIt would require defining a filesystem-independent way to store the verity metadata. Extended attributes don't work for this because (a) the Merkle tree may be gigabytes, but many filesystems assume that all xattrs fit into a single 4K filesystem block, and (b) ext4 and f2fs encryption doesn't encrypt xattrs, yet the Merkle tree *must* be encrypted when the file contents are, because it stores hashes of the plaintext file contents.h](hXPIt would require defining a filesystem-independent way to store the verity metadata. Extended attributes don’t work for this because (a) the Merkle tree may be gigabytes, but many filesystems assume that all xattrs fit into a single 4K filesystem block, and (b) ext4 and f2fs encryption doesn’t encrypt xattrs, yet the Merkle tree }(hjhhhNhNubj)}(h*must*h]hmust}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhb be encrypted when the file contents are, because it stores hashes of the plaintext file contents.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM|hjubh)}(hXSo the verity metadata would have to be stored in an actual file. Using a separate file would be very ugly, since the metadata is fundamentally part of the file to be protected, and it could cause problems where users could delete the real file but not the metadata file or vice versa. On the other hand, having it be in the same file would break applications unless filesystems' notion of i_size were divorced from the VFS's, which would be complex and require changes to all filesystems.h]hXSo the verity metadata would have to be stored in an actual file. Using a separate file would be very ugly, since the metadata is fundamentally part of the file to be protected, and it could cause problems where users could delete the real file but not the metadata file or vice versa. On the other hand, having it be in the same file would break applications unless filesystems’ notion of i_size were divorced from the VFS’s, which would be complex and require changes to all filesystems.}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hIt's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's transaction mechanism so that either the file ends up with verity enabled, or no changes were made. Allowing intermediate states to occur after a crash may cause problems.h]h)}(hIt's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's transaction mechanism so that either the file ends up with verity enabled, or no changes were made. Allowing intermediate states to occur after a crash may cause problems.h]hIt’s desirable that FS_IOC_ENABLE_VERITY uses the filesystem’s transaction mechanism so that either the file ends up with verity enabled, or no changes were made. Allowing intermediate states to occur after a crash may cause problems.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjMubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jjuh1jhhhMuhjubeh}(h]h ]h"]h$]h&]uh1jhhjubeh}(h]h ]h"]h$]h&]uh1jShhhMrhjPhhubeh}(h]h ]h"]h$]h&]uh1jNhj/hhhhhMubeh}(h]faqah ]h"]faqah$]h&]uh1hhhhhhhhMubeh}(h](6fs-verity-read-only-file-based-authenticity-protectionheh ]h"](7fs-verity: read-only file-based authenticity protectionfsverityeh$]h&]uh1hhhhhhhhKj }jhsj }hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}(fs_ioc_measure_verity](jja ebuilt-in signature verification](jj&j j efilesystem support](jj jt e merkle tree]jC afs-verity descriptor]j~ afs_ioc_enable_verity](jOjje use cases](jjj~everifying data]jgaurefids}(h]haj ]j aj]j aj]j}aunameids}(jhjjjojlj1j.jjj j j_j\j jj j j j j j j j j j jjjjjjS jjjj jjjjjDjAjjjjj|jyjtjwjjjmjjjjj,j)j jjju nametypes}(jjjoj1jj j_j j j j j j jjjjjjjjDjjj|jtjjmjj,j juh}(hhjhjlhj.j(jjrj jj\jjjbj j j j j j j j j j jj jjjS jjjj jjjjjjAjjjGjjjyjjwj jj*jjjjjj)jjjjj/u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jKsRparse_messages]transform_messages](hsystem_message)}(hhh]h)}(hhh]h.Hyperlink target "fsverity" is not referenced.}hj0sbah}(h]h ]h"]h$]h&]uh1hhj-ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKuh1j+ubj,)}(hhh]h)}(hhh]h