1.. SPDX-License-Identifier: GPL-2.0
2
3.. _fsverity:
4
5=======================================================
6fs-verity: read-only file-based authenticity protection
7=======================================================
8
9Introduction
10============
11
12fs-verity (``fs/verity/``) is a support layer that filesystems can
13hook into to support transparent integrity and authenticity protection
14of read-only files.  Currently, it is supported by the ext4, f2fs, and
15btrfs filesystems.  Like fscrypt, not too much filesystem-specific
16code is needed to support fs-verity.
17
18fs-verity is similar to `dm-verity
19<https://www.kernel.org/doc/Documentation/admin-guide/device-mapper/verity.rst>`_
20but works on files rather than block devices.  On regular files on
21filesystems supporting fs-verity, userspace can execute an ioctl that
22causes the filesystem to build a Merkle tree for the file and persist
23it to a filesystem-specific location associated with the file.
24
25After this, the file is made readonly, and all reads from the file are
26automatically verified against the file's Merkle tree.  Reads of any
27corrupted data, including mmap reads, will fail.
28
29Userspace can use another ioctl to retrieve the root hash (actually
30the "fs-verity file digest", which is a hash that includes the Merkle
31tree root hash) that fs-verity is enforcing for the file.  This ioctl
32executes in constant time, regardless of the file size.
33
34fs-verity is essentially a way to hash a file in constant time,
35subject to the caveat that reads which would violate the hash will
36fail at runtime.
37
38Use cases
39=========
40
41By itself, fs-verity only provides integrity protection, i.e.
42detection of accidental (non-malicious) corruption.
43
44However, because fs-verity makes retrieving the file hash extremely
45efficient, it's primarily meant to be used as a tool to support
46authentication (detection of malicious modifications) or auditing
47(logging file hashes before use).
48
49A standard file hash could be used instead of fs-verity.  However,
50this is inefficient if the file is large and only a small portion may
51be accessed.  This is often the case for Android application package
52(APK) files, for example.  These typically contain many translations,
53classes, and other resources that are infrequently or even never
54accessed on a particular device.  It would be slow and wasteful to
55read and hash the entire file before starting the application.
56
57Unlike an ahead-of-time hash, fs-verity also re-verifies data each
58time it's paged in.  This ensures that malicious disk firmware can't
59undetectably change the contents of the file at runtime.
60
61fs-verity does not replace or obsolete dm-verity.  dm-verity should
62still be used on read-only filesystems.  fs-verity is for files that
63must live on a read-write filesystem because they are independently
64updated and potentially user-installed, so dm-verity cannot be used.
65
66fs-verity does not mandate a particular scheme for authenticating its
67file hashes.  (Similarly, dm-verity does not mandate a particular
68scheme for authenticating its block device root hashes.)  Options for
69authenticating fs-verity file hashes include:
70
71- Trusted userspace code.  Often, the userspace code that accesses
72  files can be trusted to authenticate them.  Consider e.g. an
73  application that wants to authenticate data files before using them,
74  or an application loader that is part of the operating system (which
75  is already authenticated in a different way, such as by being loaded
76  from a read-only partition that uses dm-verity) and that wants to
77  authenticate applications before loading them.  In these cases, this
78  trusted userspace code can authenticate a file's contents by
79  retrieving its fs-verity digest using `FS_IOC_MEASURE_VERITY`_, then
80  verifying a signature of it using any userspace cryptographic
81  library that supports digital signatures.
82
83- Integrity Measurement Architecture (IMA).  IMA supports fs-verity
84  file digests as an alternative to its traditional full file digests.
85  "IMA appraisal" enforces that files contain a valid, matching
86  signature in their "security.ima" extended attribute, as controlled
87  by the IMA policy.  For more information, see the IMA documentation.
88
89- Integrity Policy Enforcement (IPE).  IPE supports enforcing access
90  control decisions based on immutable security properties of files,
91  including those protected by fs-verity's built-in signatures.
92  "IPE policy" specifically allows for the authorization of fs-verity
93  files using properties ``fsverity_digest`` for identifying
94  files by their verity digest, and ``fsverity_signature`` to authorize
95  files with a verified fs-verity's built-in signature. For
96  details on configuring IPE policies and understanding its operational
97  modes, please refer to :doc:`IPE admin guide </admin-guide/LSM/ipe>`.
98
99- Trusted userspace code in combination with `Built-in signature
100  verification`_.  This approach should be used only with great care.
101
102User API
103========
104
105FS_IOC_ENABLE_VERITY
106--------------------
107
108The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file.  It takes
109in a pointer to a struct fsverity_enable_arg, defined as
110follows::
111
112    struct fsverity_enable_arg {
113            __u32 version;
114            __u32 hash_algorithm;
115            __u32 block_size;
116            __u32 salt_size;
117            __u64 salt_ptr;
118            __u32 sig_size;
119            __u32 __reserved1;
120            __u64 sig_ptr;
121            __u64 __reserved2[11];
122    };
123
124This structure contains the parameters of the Merkle tree to build for
125the file.  It must be initialized as follows:
126
127- ``version`` must be 1.
128- ``hash_algorithm`` must be the identifier for the hash algorithm to
129  use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256.  See
130  ``include/uapi/linux/fsverity.h`` for the list of possible values.
131- ``block_size`` is the Merkle tree block size, in bytes.  In Linux
132  v6.3 and later, this can be any power of 2 between (inclusively)
133  1024 and the minimum of the system page size and the filesystem
134  block size.  In earlier versions, the page size was the only allowed
135  value.
136- ``salt_size`` is the size of the salt in bytes, or 0 if no salt is
137  provided.  The salt is a value that is prepended to every hashed
138  block; it can be used to personalize the hashing for a particular
139  file or device.  Currently the maximum salt size is 32 bytes.
140- ``salt_ptr`` is the pointer to the salt, or NULL if no salt is
141  provided.
142- ``sig_size`` is the size of the builtin signature in bytes, or 0 if no
143  builtin signature is provided.  Currently the builtin signature is
144  (somewhat arbitrarily) limited to 16128 bytes.
145- ``sig_ptr``  is the pointer to the builtin signature, or NULL if no
146  builtin signature is provided.  A builtin signature is only needed
147  if the `Built-in signature verification`_ feature is being used.  It
148  is not needed for IMA appraisal, and it is not needed if the file
149  signature is being handled entirely in userspace.
150- All reserved fields must be zeroed.
151
152FS_IOC_ENABLE_VERITY causes the filesystem to build a Merkle tree for
153the file and persist it to a filesystem-specific location associated
154with the file, then mark the file as a verity file.  This ioctl may
155take a long time to execute on large files, and it is interruptible by
156fatal signals.
157
158FS_IOC_ENABLE_VERITY checks for write access to the inode.  However,
159it must be executed on an O_RDONLY file descriptor and no processes
160can have the file open for writing.  Attempts to open the file for
161writing while this ioctl is executing will fail with ETXTBSY.  (This
162is necessary to guarantee that no writable file descriptors will exist
163after verity is enabled, and to guarantee that the file's contents are
164stable while the Merkle tree is being built over it.)
165
166On success, FS_IOC_ENABLE_VERITY returns 0, and the file becomes a
167verity file.  On failure (including the case of interruption by a
168fatal signal), no changes are made to the file.
169
170FS_IOC_ENABLE_VERITY can fail with the following errors:
171
172- ``EACCES``: the process does not have write access to the file
173- ``EBADMSG``: the builtin signature is malformed
174- ``EBUSY``: this ioctl is already running on the file
175- ``EEXIST``: the file already has verity enabled
176- ``EFAULT``: the caller provided inaccessible memory
177- ``EFBIG``: the file is too large to enable verity on
178- ``EINTR``: the operation was interrupted by a fatal signal
179- ``EINVAL``: unsupported version, hash algorithm, or block size; or
180  reserved bits are set; or the file descriptor refers to neither a
181  regular file nor a directory.
182- ``EISDIR``: the file descriptor refers to a directory
183- ``EKEYREJECTED``: the builtin signature doesn't match the file
184- ``EMSGSIZE``: the salt or builtin signature is too long
185- ``ENOKEY``: the ".fs-verity" keyring doesn't contain the certificate
186  needed to verify the builtin signature
187- ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not
188  available in the kernel's crypto API as currently configured (e.g.
189  for SHA-512, missing CONFIG_CRYPTO_SHA512).
190- ``ENOTTY``: this type of filesystem does not implement fs-verity
191- ``EOPNOTSUPP``: the kernel was not configured with fs-verity
192  support; or the filesystem superblock has not had the 'verity'
193  feature enabled on it; or the filesystem does not support fs-verity
194  on this file.  (See `Filesystem support`_.)
195- ``EPERM``: the file is append-only; or, a builtin signature is
196  required and one was not provided.
197- ``EROFS``: the filesystem is read-only
198- ``ETXTBSY``: someone has the file open for writing.  This can be the
199  caller's file descriptor, another open file descriptor, or the file
200  reference held by a writable memory map.
201
202FS_IOC_MEASURE_VERITY
203---------------------
204
205The FS_IOC_MEASURE_VERITY ioctl retrieves the digest of a verity file.
206The fs-verity file digest is a cryptographic digest that identifies
207the file contents that are being enforced on reads; it is computed via
208a Merkle tree and is different from a traditional full-file digest.
209
210This ioctl takes in a pointer to a variable-length structure::
211
212    struct fsverity_digest {
213            __u16 digest_algorithm;
214            __u16 digest_size; /* input/output */
215            __u8 digest[];
216    };
217
218``digest_size`` is an input/output field.  On input, it must be
219initialized to the number of bytes allocated for the variable-length
220``digest`` field.
221
222On success, 0 is returned and the kernel fills in the structure as
223follows:
224
225- ``digest_algorithm`` will be the hash algorithm used for the file
226  digest.  It will match ``fsverity_enable_arg::hash_algorithm``.
227- ``digest_size`` will be the size of the digest in bytes, e.g. 32
228  for SHA-256.  (This can be redundant with ``digest_algorithm``.)
229- ``digest`` will be the actual bytes of the digest.
230
231FS_IOC_MEASURE_VERITY is guaranteed to execute in constant time,
232regardless of the size of the file.
233
234FS_IOC_MEASURE_VERITY can fail with the following errors:
235
236- ``EFAULT``: the caller provided inaccessible memory
237- ``ENODATA``: the file is not a verity file
238- ``ENOTTY``: this type of filesystem does not implement fs-verity
239- ``EOPNOTSUPP``: the kernel was not configured with fs-verity
240  support, or the filesystem superblock has not had the 'verity'
241  feature enabled on it.  (See `Filesystem support`_.)
242- ``EOVERFLOW``: the digest is longer than the specified
243  ``digest_size`` bytes.  Try providing a larger buffer.
244
245FS_IOC_READ_VERITY_METADATA
246---------------------------
247
248The FS_IOC_READ_VERITY_METADATA ioctl reads verity metadata from a
249verity file.  This ioctl is available since Linux v5.12.
250
251This ioctl is useful for cases where the verity verification should be
252performed somewhere other than the currently running kernel.
253
254One example is a server program that takes a verity file and serves it
255to a client program, such that the client can do its own fs-verity
256compatible verification of the file.  This only makes sense if the
257client doesn't trust the server and if the server needs to provide the
258storage for the client.
259
260Another example is copying verity metadata when creating filesystem
261images in userspace (such as with ``mkfs.ext4 -d``).
262
263This is a fairly specialized use case, and most fs-verity users won't
264need this ioctl.
265
266This ioctl takes in a pointer to the following structure::
267
268   #define FS_VERITY_METADATA_TYPE_MERKLE_TREE     1
269   #define FS_VERITY_METADATA_TYPE_DESCRIPTOR      2
270   #define FS_VERITY_METADATA_TYPE_SIGNATURE       3
271
272   struct fsverity_read_metadata_arg {
273           __u64 metadata_type;
274           __u64 offset;
275           __u64 length;
276           __u64 buf_ptr;
277           __u64 __reserved;
278   };
279
280``metadata_type`` specifies the type of metadata to read:
281
282- ``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the
283  Merkle tree.  The blocks are returned in order from the root level
284  to the leaf level.  Within each level, the blocks are returned in
285  the same order that their hashes are themselves hashed.
286  See `Merkle tree`_ for more information.
287
288- ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity
289  descriptor.  See `fs-verity descriptor`_.
290
291- ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the builtin signature
292  which was passed to FS_IOC_ENABLE_VERITY, if any.  See `Built-in
293  signature verification`_.
294
295The semantics are similar to those of ``pread()``.  ``offset``
296specifies the offset in bytes into the metadata item to read from, and
297``length`` specifies the maximum number of bytes to read from the
298metadata item.  ``buf_ptr`` is the pointer to the buffer to read into,
299cast to a 64-bit integer.  ``__reserved`` must be 0.  On success, the
300number of bytes read is returned.  0 is returned at the end of the
301metadata item.  The returned length may be less than ``length``, for
302example if the ioctl is interrupted.
303
304The metadata returned by FS_IOC_READ_VERITY_METADATA isn't guaranteed
305to be authenticated against the file digest that would be returned by
306`FS_IOC_MEASURE_VERITY`_, as the metadata is expected to be used to
307implement fs-verity compatible verification anyway (though absent a
308malicious disk, the metadata will indeed match).  E.g. to implement
309this ioctl, the filesystem is allowed to just read the Merkle tree
310blocks from disk without actually verifying the path to the root node.
311
312FS_IOC_READ_VERITY_METADATA can fail with the following errors:
313
314- ``EFAULT``: the caller provided inaccessible memory
315- ``EINTR``: the ioctl was interrupted before any data was read
316- ``EINVAL``: reserved fields were set, or ``offset + length``
317  overflowed
318- ``ENODATA``: the file is not a verity file, or
319  FS_VERITY_METADATA_TYPE_SIGNATURE was requested but the file doesn't
320  have a builtin signature
321- ``ENOTTY``: this type of filesystem does not implement fs-verity, or
322  this ioctl is not yet implemented on it
323- ``EOPNOTSUPP``: the kernel was not configured with fs-verity
324  support, or the filesystem superblock has not had the 'verity'
325  feature enabled on it.  (See `Filesystem support`_.)
326
327FS_IOC_GETFLAGS
328---------------
329
330The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
331can also be used to check whether a file has fs-verity enabled or not.
332To do so, check for FS_VERITY_FL (0x00100000) in the returned flags.
333
334The verity flag is not settable via FS_IOC_SETFLAGS.  You must use
335FS_IOC_ENABLE_VERITY instead, since parameters must be provided.
336
337statx
338-----
339
340Since Linux v5.5, the statx() system call sets STATX_ATTR_VERITY if
341the file has fs-verity enabled.  This can perform better than
342FS_IOC_GETFLAGS and FS_IOC_MEASURE_VERITY because it doesn't require
343opening the file, and opening verity files can be expensive.
344
345.. _accessing_verity_files:
346
347Accessing verity files
348======================
349
350Applications can transparently access a verity file just like a
351non-verity one, with the following exceptions:
352
353- Verity files are readonly.  They cannot be opened for writing or
354  truncate()d, even if the file mode bits allow it.  Attempts to do
355  one of these things will fail with EPERM.  However, changes to
356  metadata such as owner, mode, timestamps, and xattrs are still
357  allowed, since these are not measured by fs-verity.  Verity files
358  can also still be renamed, deleted, and linked to.
359
360- Direct I/O is not supported on verity files.  Attempts to use direct
361  I/O on such files will fall back to buffered I/O.
362
363- DAX (Direct Access) is not supported on verity files, because this
364  would circumvent the data verification.
365
366- Reads of data that doesn't match the verity Merkle tree will fail
367  with EIO (for read()) or SIGBUS (for mmap() reads).
368
369- If the sysctl "fs.verity.require_signatures" is set to 1 and the
370  file is not signed by a key in the ".fs-verity" keyring, then
371  opening the file will fail.  See `Built-in signature verification`_.
372
373Direct access to the Merkle tree is not supported.  Therefore, if a
374verity file is copied, or is backed up and restored, then it will lose
375its "verity"-ness.  fs-verity is primarily meant for files like
376executables that are managed by a package manager.
377
378File digest computation
379=======================
380
381This section describes how fs-verity hashes the file contents using a
382Merkle tree to produce the digest which cryptographically identifies
383the file contents.  This algorithm is the same for all filesystems
384that support fs-verity.
385
386Userspace only needs to be aware of this algorithm if it needs to
387compute fs-verity file digests itself, e.g. in order to sign files.
388
389.. _fsverity_merkle_tree:
390
391Merkle tree
392-----------
393
394The file contents is divided into blocks, where the block size is
395configurable but is usually 4096 bytes.  The end of the last block is
396zero-padded if needed.  Each block is then hashed, producing the first
397level of hashes.  Then, the hashes in this first level are grouped
398into 'blocksize'-byte blocks (zero-padding the ends as needed) and
399these blocks are hashed, producing the second level of hashes.  This
400proceeds up the tree until only a single block remains.  The hash of
401this block is the "Merkle tree root hash".
402
403If the file fits in one block and is nonempty, then the "Merkle tree
404root hash" is simply the hash of the single data block.  If the file
405is empty, then the "Merkle tree root hash" is all zeroes.
406
407The "blocks" here are not necessarily the same as "filesystem blocks".
408
409If a salt was specified, then it's zero-padded to the closest multiple
410of the input size of the hash algorithm's compression function, e.g.
41164 bytes for SHA-256 or 128 bytes for SHA-512.  The padded salt is
412prepended to every data or Merkle tree block that is hashed.
413
414The purpose of the block padding is to cause every hash to be taken
415over the same amount of data, which simplifies the implementation and
416keeps open more possibilities for hardware acceleration.  The purpose
417of the salt padding is to make the salting "free" when the salted hash
418state is precomputed, then imported for each hash.
419
420Example: in the recommended configuration of SHA-256 and 4K blocks,
421128 hash values fit in each block.  Thus, each level of the Merkle
422tree is approximately 128 times smaller than the previous, and for
423large files the Merkle tree's size converges to approximately 1/127 of
424the original file size.  However, for small files, the padding is
425significant, making the space overhead proportionally more.
426
427.. _fsverity_descriptor:
428
429fs-verity descriptor
430--------------------
431
432By itself, the Merkle tree root hash is ambiguous.  For example, it
433can't a distinguish a large file from a small second file whose data
434is exactly the top-level hash block of the first file.  Ambiguities
435also arise from the convention of padding to the next block boundary.
436
437To solve this problem, the fs-verity file digest is actually computed
438as a hash of the following structure, which contains the Merkle tree
439root hash as well as other fields such as the file size::
440
441    struct fsverity_descriptor {
442            __u8 version;           /* must be 1 */
443            __u8 hash_algorithm;    /* Merkle tree hash algorithm */
444            __u8 log_blocksize;     /* log2 of size of data and tree blocks */
445            __u8 salt_size;         /* size of salt in bytes; 0 if none */
446            __le32 __reserved_0x04; /* must be 0 */
447            __le64 data_size;       /* size of file the Merkle tree is built over */
448            __u8 root_hash[64];     /* Merkle tree root hash */
449            __u8 salt[32];          /* salt prepended to each hashed block */
450            __u8 __reserved[144];   /* must be 0's */
451    };
452
453Built-in signature verification
454===============================
455
456CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds supports for in-kernel
457verification of fs-verity builtin signatures.
458
459**IMPORTANT**!  Please take great care before using this feature.
460It is not the only way to do signatures with fs-verity, and the
461alternatives (such as userspace signature verification, and IMA
462appraisal) can be much better.  It's also easy to fall into a trap
463of thinking this feature solves more problems than it actually does.
464
465Enabling this option adds the following:
466
4671. At boot time, the kernel creates a keyring named ".fs-verity".  The
468   root user can add trusted X.509 certificates to this keyring using
469   the add_key() system call.
470
4712. `FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted
472   detached signature in DER format of the file's fs-verity digest.
473   On success, the ioctl persists the signature alongside the Merkle
474   tree.  Then, any time the file is opened, the kernel verifies the
475   file's actual digest against this signature, using the certificates
476   in the ".fs-verity" keyring. This verification happens as long as the
477   file's signature exists, regardless of the state of the sysctl variable
478   "fs.verity.require_signatures" described in the next item. The IPE LSM
479   relies on this behavior to recognize and label fsverity files
480   that contain a verified built-in fsverity signature.
481
4823. A new sysctl "fs.verity.require_signatures" is made available.
483   When set to 1, the kernel requires that all verity files have a
484   correctly signed digest as described in (2).
485
486The data that the signature as described in (2) must be a signature of
487is the fs-verity file digest in the following format::
488
489    struct fsverity_formatted_digest {
490            char magic[8];                  /* must be "FSVerity" */
491            __le16 digest_algorithm;
492            __le16 digest_size;
493            __u8 digest[];
494    };
495
496That's it.  It should be emphasized again that fs-verity builtin
497signatures are not the only way to do signatures with fs-verity.  See
498`Use cases`_ for an overview of ways in which fs-verity can be used.
499fs-verity builtin signatures have some major limitations that should
500be carefully considered before using them:
501
502- Builtin signature verification does *not* make the kernel enforce
503  that any files actually have fs-verity enabled.  Thus, it is not a
504  complete authentication policy.  Currently, if it is used, one
505  way to complete the authentication policy is for trusted userspace
506  code to explicitly check whether files have fs-verity enabled with a
507  signature before they are accessed.  (With
508  fs.verity.require_signatures=1, just checking whether fs-verity is
509  enabled suffices.)  But, in this case the trusted userspace code
510  could just store the signature alongside the file and verify it
511  itself using a cryptographic library, instead of using this feature.
512
513- Another approach is to utilize fs-verity builtin signature
514  verification in conjunction with the IPE LSM, which supports defining
515  a kernel-enforced, system-wide authentication policy that allows only
516  files with a verified fs-verity builtin signature to perform certain
517  operations, such as execution. Note that IPE doesn't require
518  fs.verity.require_signatures=1.
519  Please refer to :doc:`IPE admin guide </admin-guide/LSM/ipe>` for
520  more details.
521
522- A file's builtin signature can only be set at the same time that
523  fs-verity is being enabled on the file.  Changing or deleting the
524  builtin signature later requires re-creating the file.
525
526- Builtin signature verification uses the same set of public keys for
527  all fs-verity enabled files on the system.  Different keys cannot be
528  trusted for different files; each key is all or nothing.
529
530- The sysctl fs.verity.require_signatures applies system-wide.
531  Setting it to 1 only works when all users of fs-verity on the system
532  agree that it should be set to 1.  This limitation can prevent
533  fs-verity from being used in cases where it would be helpful.
534
535- Builtin signature verification can only use signature algorithms
536  that are supported by the kernel.  For example, the kernel does not
537  yet support Ed25519, even though this is often the signature
538  algorithm that is recommended for new cryptographic designs.
539
540- fs-verity builtin signatures are in PKCS#7 format, and the public
541  keys are in X.509 format.  These formats are commonly used,
542  including by some other kernel features (which is why the fs-verity
543  builtin signatures use them), and are very feature rich.
544  Unfortunately, history has shown that code that parses and handles
545  these formats (which are from the 1990s and are based on ASN.1)
546  often has vulnerabilities as a result of their complexity.  This
547  complexity is not inherent to the cryptography itself.
548
549  fs-verity users who do not need advanced features of X.509 and
550  PKCS#7 should strongly consider using simpler formats, such as plain
551  Ed25519 keys and signatures, and verifying signatures in userspace.
552
553  fs-verity users who choose to use X.509 and PKCS#7 anyway should
554  still consider that verifying those signatures in userspace is more
555  flexible (for other reasons mentioned earlier in this document) and
556  eliminates the need to enable CONFIG_FS_VERITY_BUILTIN_SIGNATURES
557  and its associated increase in kernel attack surface.  In some cases
558  it can even be necessary, since advanced X.509 and PKCS#7 features
559  do not always work as intended with the kernel.  For example, the
560  kernel does not check X.509 certificate validity times.
561
562  Note: IMA appraisal, which supports fs-verity, does not use PKCS#7
563  for its signatures, so it partially avoids the issues discussed
564  here.  IMA appraisal does use X.509.
565
566Filesystem support
567==================
568
569fs-verity is supported by several filesystems, described below.  The
570CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on
571any of these filesystems.
572
573``include/linux/fsverity.h`` declares the interface between the
574``fs/verity/`` support layer and filesystems.  Briefly, filesystems
575must provide an ``fsverity_operations`` structure that provides
576methods to read and write the verity metadata to a filesystem-specific
577location, including the Merkle tree blocks and
578``fsverity_descriptor``.  Filesystems must also call functions in
579``fs/verity/`` at certain times, such as when a file is opened or when
580pages have been read into the pagecache.  (See `Verifying data`_.)
581
582ext4
583----
584
585ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.
586
587To create verity files on an ext4 filesystem, the filesystem must have
588been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
589it.  "verity" is an RO_COMPAT filesystem feature, so once set, old
590kernels will only be able to mount the filesystem readonly, and old
591versions of e2fsck will be unable to check the filesystem.
592
593Originally, an ext4 filesystem with the "verity" feature could only be
594mounted when its block size was equal to the system page size
595(typically 4096 bytes).  In Linux v6.3, this limitation was removed.
596
597ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files.  It
598can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared.
599
600ext4 also supports encryption, which can be used simultaneously with
601fs-verity.  In this case, the plaintext data is verified rather than
602the ciphertext.  This is necessary in order to make the fs-verity file
603digest meaningful, since every file is encrypted differently.
604
605ext4 stores the verity metadata (Merkle tree and fsverity_descriptor)
606past the end of the file, starting at the first 64K boundary beyond
607i_size.  This approach works because (a) verity files are readonly,
608and (b) pages fully beyond i_size aren't visible to userspace but can
609be read/written internally by ext4 with only some relatively small
610changes to ext4.  This approach avoids having to depend on the
611EA_INODE feature and on rearchitecturing ext4's xattr support to
612support paging multi-gigabyte xattrs into memory, and to support
613encrypting xattrs.  Note that the verity metadata *must* be encrypted
614when the file is, since it contains hashes of the plaintext data.
615
616ext4 only allows verity on extent-based files.
617
618f2fs
619----
620
621f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.
622
623To create verity files on an f2fs filesystem, the filesystem must have
624been formatted with ``-O verity``.
625
626f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
627It can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be
628cleared.
629
630Like ext4, f2fs stores the verity metadata (Merkle tree and
631fsverity_descriptor) past the end of the file, starting at the first
63264K boundary beyond i_size.  See explanation for ext4 above.
633Moreover, f2fs supports at most 4096 bytes of xattr entries per inode
634which usually wouldn't be enough for even a single Merkle tree block.
635
636f2fs doesn't support enabling verity on files that currently have
637atomic or volatile writes pending.
638
639btrfs
640-----
641
642btrfs supports fs-verity since Linux v5.15.  Verity-enabled inodes are
643marked with a RO_COMPAT inode flag, and the verity metadata is stored
644in separate btree items.
645
646Implementation details
647======================
648
649Verifying data
650--------------
651
652fs-verity ensures that all reads of a verity file's data are verified,
653regardless of which syscall is used to do the read (e.g. mmap(),
654read(), pread()) and regardless of whether it's the first read or a
655later read (unless the later read can return cached data that was
656already verified).  Below, we describe how filesystems implement this.
657
658Pagecache
659~~~~~~~~~
660
661For filesystems using Linux's pagecache, the ``->read_folio()`` and
662``->readahead()`` methods must be modified to verify folios before
663they are marked Uptodate.  Merely hooking ``->read_iter()`` would be
664insufficient, since ``->read_iter()`` is not used for memory maps.
665
666Therefore, fs/verity/ provides the function fsverity_verify_blocks()
667which verifies data that has been read into the pagecache of a verity
668inode.  The containing folio must still be locked and not Uptodate, so
669it's not yet readable by userspace.  As needed to do the verification,
670fsverity_verify_blocks() will call back into the filesystem to read
671hash blocks via fsverity_operations::read_merkle_tree_page().
672
673fsverity_verify_blocks() returns false if verification failed; in this
674case, the filesystem must not set the folio Uptodate.  Following this,
675as per the usual Linux pagecache behavior, attempts by userspace to
676read() from the part of the file containing the folio will fail with
677EIO, and accesses to the folio within a memory map will raise SIGBUS.
678
679In principle, verifying a data block requires verifying the entire
680path in the Merkle tree from the data block to the root hash.
681However, for efficiency the filesystem may cache the hash blocks.
682Therefore, fsverity_verify_blocks() only ascends the tree reading hash
683blocks until an already-verified hash block is seen.  It then verifies
684the path to that block.
685
686This optimization, which is also used by dm-verity, results in
687excellent sequential read performance.  This is because usually (e.g.
688127 in 128 times for 4K blocks and SHA-256) the hash block from the
689bottom level of the tree will already be cached and checked from
690reading a previous data block.  However, random reads perform worse.
691
692Block device based filesystems
693~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
694
695Block device based filesystems (e.g. ext4 and f2fs) in Linux also use
696the pagecache, so the above subsection applies too.  However, they
697also usually read many data blocks from a file at once, grouped into a
698structure called a "bio".  To make it easier for these types of
699filesystems to support fs-verity, fs/verity/ also provides a function
700fsverity_verify_bio() which verifies all data blocks in a bio.
701
702ext4 and f2fs also support encryption.  If a verity file is also
703encrypted, the data must be decrypted before being verified.  To
704support this, these filesystems allocate a "post-read context" for
705each bio and store it in ``->bi_private``::
706
707    struct bio_post_read_ctx {
708           struct bio *bio;
709           struct work_struct work;
710           unsigned int cur_step;
711           unsigned int enabled_steps;
712    };
713
714``enabled_steps`` is a bitmask that specifies whether decryption,
715verity, or both is enabled.  After the bio completes, for each needed
716postprocessing step the filesystem enqueues the bio_post_read_ctx on a
717workqueue, and then the workqueue work does the decryption or
718verification.  Finally, folios where no decryption or verity error
719occurred are marked Uptodate, and the folios are unlocked.
720
721On many filesystems, files can contain holes.  Normally,
722``->readahead()`` simply zeroes hole blocks and considers the
723corresponding data to be up-to-date; no bios are issued.  To prevent
724this case from bypassing fs-verity, filesystems use
725fsverity_verify_blocks() to verify hole blocks.
726
727Filesystems also disable direct I/O on verity files, since otherwise
728direct I/O would bypass fs-verity.
729
730Userspace utility
731=================
732
733This document focuses on the kernel, but a userspace utility for
734fs-verity can be found at:
735
736	https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git
737
738See the README.md file in the fsverity-utils source tree for details,
739including examples of setting up fs-verity protected files.
740
741Tests
742=====
743
744To test fs-verity, use xfstests.  For example, using `kvm-xfstests
745<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
746
747    kvm-xfstests -c ext4,f2fs,btrfs -g verity
748
749FAQ
750===
751
752This section answers frequently asked questions about fs-verity that
753weren't already directly answered in other parts of this document.
754
755:Q: Why isn't fs-verity part of IMA?
756:A: fs-verity and IMA (Integrity Measurement Architecture) have
757    different focuses.  fs-verity is a filesystem-level mechanism for
758    hashing individual files using a Merkle tree.  In contrast, IMA
759    specifies a system-wide policy that specifies which files are
760    hashed and what to do with those hashes, such as log them,
761    authenticate them, or add them to a measurement list.
762
763    IMA supports the fs-verity hashing mechanism as an alternative
764    to full file hashes, for those who want the performance and
765    security benefits of the Merkle tree based hash.  However, it
766    doesn't make sense to force all uses of fs-verity to be through
767    IMA.  fs-verity already meets many users' needs even as a
768    standalone filesystem feature, and it's testable like other
769    filesystem features e.g. with xfstests.
770
771:Q: Isn't fs-verity useless because the attacker can just modify the
772    hashes in the Merkle tree, which is stored on-disk?
773:A: To verify the authenticity of an fs-verity file you must verify
774    the authenticity of the "fs-verity file digest", which
775    incorporates the root hash of the Merkle tree.  See `Use cases`_.
776
777:Q: Isn't fs-verity useless because the attacker can just replace a
778    verity file with a non-verity one?
779:A: See `Use cases`_.  In the initial use case, it's really trusted
780    userspace code that authenticates the files; fs-verity is just a
781    tool to do this job efficiently and securely.  The trusted
782    userspace code will consider non-verity files to be inauthentic.
783
784:Q: Why does the Merkle tree need to be stored on-disk?  Couldn't you
785    store just the root hash?
786:A: If the Merkle tree wasn't stored on-disk, then you'd have to
787    compute the entire tree when the file is first accessed, even if
788    just one byte is being read.  This is a fundamental consequence of
789    how Merkle tree hashing works.  To verify a leaf node, you need to
790    verify the whole path to the root hash, including the root node
791    (the thing which the root hash is a hash of).  But if the root
792    node isn't stored on-disk, you have to compute it by hashing its
793    children, and so on until you've actually hashed the entire file.
794
795    That defeats most of the point of doing a Merkle tree-based hash,
796    since if you have to hash the whole file ahead of time anyway,
797    then you could simply do sha256(file) instead.  That would be much
798    simpler, and a bit faster too.
799
800    It's true that an in-memory Merkle tree could still provide the
801    advantage of verification on every read rather than just on the
802    first read.  However, it would be inefficient because every time a
803    hash page gets evicted (you can't pin the entire Merkle tree into
804    memory, since it may be very large), in order to restore it you
805    again need to hash everything below it in the tree.  This again
806    defeats most of the point of doing a Merkle tree-based hash, since
807    a single block read could trigger re-hashing gigabytes of data.
808
809:Q: But couldn't you store just the leaf nodes and compute the rest?
810:A: See previous answer; this really just moves up one level, since
811    one could alternatively interpret the data blocks as being the
812    leaf nodes of the Merkle tree.  It's true that the tree can be
813    computed much faster if the leaf level is stored rather than just
814    the data, but that's only because each level is less than 1% the
815    size of the level below (assuming the recommended settings of
816    SHA-256 and 4K blocks).  For the exact same reason, by storing
817    "just the leaf nodes" you'd already be storing over 99% of the
818    tree, so you might as well simply store the whole tree.
819
820:Q: Can the Merkle tree be built ahead of time, e.g. distributed as
821    part of a package that is installed to many computers?
822:A: This isn't currently supported.  It was part of the original
823    design, but was removed to simplify the kernel UAPI and because it
824    wasn't a critical use case.  Files are usually installed once and
825    used many times, and cryptographic hashing is somewhat fast on
826    most modern processors.
827
828:Q: Why doesn't fs-verity support writes?
829:A: Write support would be very difficult and would require a
830    completely different design, so it's well outside the scope of
831    fs-verity.  Write support would require:
832
833    - A way to maintain consistency between the data and hashes,
834      including all levels of hashes, since corruption after a crash
835      (especially of potentially the entire file!) is unacceptable.
836      The main options for solving this are data journalling,
837      copy-on-write, and log-structured volume.  But it's very hard to
838      retrofit existing filesystems with new consistency mechanisms.
839      Data journalling is available on ext4, but is very slow.
840
841    - Rebuilding the Merkle tree after every write, which would be
842      extremely inefficient.  Alternatively, a different authenticated
843      dictionary structure such as an "authenticated skiplist" could
844      be used.  However, this would be far more complex.
845
846    Compare it to dm-verity vs. dm-integrity.  dm-verity is very
847    simple: the kernel just verifies read-only data against a
848    read-only Merkle tree.  In contrast, dm-integrity supports writes
849    but is slow, is much more complex, and doesn't actually support
850    full-device authentication since it authenticates each sector
851    independently, i.e. there is no "root hash".  It doesn't really
852    make sense for the same device-mapper target to support these two
853    very different cases; the same applies to fs-verity.
854
855:Q: Since verity files are immutable, why isn't the immutable bit set?
856:A: The existing "immutable" bit (FS_IMMUTABLE_FL) already has a
857    specific set of semantics which not only make the file contents
858    read-only, but also prevent the file from being deleted, renamed,
859    linked to, or having its owner or mode changed.  These extra
860    properties are unwanted for fs-verity, so reusing the immutable
861    bit isn't appropriate.
862
863:Q: Why does the API use ioctls instead of setxattr() and getxattr()?
864:A: Abusing the xattr interface for basically arbitrary syscalls is
865    heavily frowned upon by most of the Linux filesystem developers.
866    An xattr should really just be an xattr on-disk, not an API to
867    e.g. magically trigger construction of a Merkle tree.
868
869:Q: Does fs-verity support remote filesystems?
870:A: So far all filesystems that have implemented fs-verity support are
871    local filesystems, but in principle any filesystem that can store
872    per-file verity metadata can support fs-verity, regardless of
873    whether it's local or remote.  Some filesystems may have fewer
874    options of where to store the verity metadata; one possibility is
875    to store it past the end of the file and "hide" it from userspace
876    by manipulating i_size.  The data verification functions provided
877    by ``fs/verity/`` also assume that the filesystem uses the Linux
878    pagecache, but both local and remote filesystems normally do so.
879
880:Q: Why is anything filesystem-specific at all?  Shouldn't fs-verity
881    be implemented entirely at the VFS level?
882:A: There are many reasons why this is not possible or would be very
883    difficult, including the following:
884
885    - To prevent bypassing verification, folios must not be marked
886      Uptodate until they've been verified.  Currently, each
887      filesystem is responsible for marking folios Uptodate via
888      ``->readahead()``.  Therefore, currently it's not possible for
889      the VFS to do the verification on its own.  Changing this would
890      require significant changes to the VFS and all filesystems.
891
892    - It would require defining a filesystem-independent way to store
893      the verity metadata.  Extended attributes don't work for this
894      because (a) the Merkle tree may be gigabytes, but many
895      filesystems assume that all xattrs fit into a single 4K
896      filesystem block, and (b) ext4 and f2fs encryption doesn't
897      encrypt xattrs, yet the Merkle tree *must* be encrypted when the
898      file contents are, because it stores hashes of the plaintext
899      file contents.
900
901      So the verity metadata would have to be stored in an actual
902      file.  Using a separate file would be very ugly, since the
903      metadata is fundamentally part of the file to be protected, and
904      it could cause problems where users could delete the real file
905      but not the metadata file or vice versa.  On the other hand,
906      having it be in the same file would break applications unless
907      filesystems' notion of i_size were divorced from the VFS's,
908      which would be complex and require changes to all filesystems.
909
910    - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's
911      transaction mechanism so that either the file ends up with
912      verity enabled, or no changes were made.  Allowing intermediate
913      states to occur after a crash may cause problems.
914