Commit 84fb7ca4 authored by Eric Biggers's avatar Eric Biggers
Browse files

ext4: update on-disk format documentation for fs-verity 



Document the format of verity files on ext4, and the corresponding inode
and superblock flags.

Reviewed-by: default avatarTheodore Ts'o <tytso@mit.edu>
Signed-off-by: default avatarEric Biggers <ebiggers@google.com>
parent 22cfe4b4

Documentation/filesystems/ext4/inodes.rst

+4 −2
Original line number Diff line number Diff line
@@ -277,6 +277,8 @@ The ``i_flags`` field is a combination of these values: 
     - This is a huge file (EXT4\_HUGE\_FILE\_FL).

   * - 0x80000

     - Inode uses extents (EXT4\_EXTENTS\_FL).

   * - 0x100000

     - Verity protected file (EXT4\_VERITY\_FL).

   * - 0x200000

     - Inode stores a large extended attribute value in its data blocks

       (EXT4\_EA\_INODE\_FL).
@@ -299,9 +301,9 @@ The ``i_flags`` field is a combination of these values: 
     - Reserved for ext4 library (EXT4\_RESERVED\_FL).

   * -

     - Aggregate flags:

   * - 0x4BDFFF

   * - 0x705BDFFF

     - User-visible flags.

   * - 0x4B80FF

   * - 0x604BC0FF

     - User-modifiable flags. Note that while EXT4\_JOURNAL\_DATA\_FL and

       EXT4\_EXTENTS\_FL can be set with setattr, they are not in the kernel's

       EXT4\_FL\_USER\_MODIFIABLE mask, since it needs to handle the setting of

Documentation/filesystems/ext4/overview.rst

+1 −0
Original line number Diff line number Diff line
@@ -24,3 +24,4 @@ order. 
.. include:: bigalloc.rst

.. include:: inlinedata.rst

.. include:: eainode.rst

.. include:: verity.rst

Documentation/filesystems/ext4/super.rst

+2 −0
Original line number Diff line number Diff line
@@ -696,6 +696,8 @@ the following: 
       (RO\_COMPAT\_READONLY)

   * - 0x2000

     - Filesystem tracks project quotas. (RO\_COMPAT\_PROJECT)

   * - 0x8000

     - Verity inodes may be present on the filesystem. (RO\_COMPAT\_VERITY)



.. _super_def_hash:

Documentation/filesystems/ext4/verity.rst

0 → 100644
+41 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



Verity files

------------



ext4 supports fs-verity, which is a filesystem feature that provides

Merkle tree based hashing for individual readonly files.  Most of

fs-verity is common to all filesystems that support it; see

:ref:`Documentation/filesystems/fsverity.rst <fsverity>` for the

fs-verity documentation.  However, the on-disk layout of the verity

metadata is filesystem-specific.  On ext4, the verity metadata is

stored after the end of the file data itself, in the following format:



- Zero-padding to the next 65536-byte boundary.  This padding need not

  actually be allocated on-disk, i.e. it may be a hole.



- The Merkle tree, as documented in

  :ref:`Documentation/filesystems/fsverity.rst

  <fsverity_merkle_tree>`, with the tree levels stored in order from

  root to leaf, and the tree blocks within each level stored in their

  natural order.



- Zero-padding to the next filesystem block boundary.



- The verity descriptor, as documented in

  :ref:`Documentation/filesystems/fsverity.rst <fsverity_descriptor>`,

  with optionally appended signature blob.



- Zero-padding to the next offset that is 4 bytes before a filesystem

  block boundary.



- The size of the verity descriptor in bytes, as a 4-byte little

  endian integer.



Verity inodes have EXT4_VERITY_FL set, and they must use extents, i.e.

EXT4_EXTENTS_FL must be set and EXT4_INLINE_DATA_FL must be clear.

They can have EXT4_ENCRYPT_FL set, in which case the verity metadata

is encrypted as well as the data itself.



Verity files cannot have blocks allocated past the end of the verity

metadata.