From: Eric Biggers <ebiggers@kernel.org>
To: linux-fscrypt@vger.kernel.org
Cc: linux-ext4@vger.kernel.org,
linux-f2fs-devel@lists.sourceforge.net,
linux-fsdevel@vger.kernel.org, linux-api@vger.kernel.org,
linux-integrity@vger.kernel.org, Jaegeuk Kim <jaegeuk@kernel.org>,
"Theodore Y . Ts'o" <tytso@mit.edu>,
Victor Hsieh <victorhsieh@google.com>,
Chandan Rajendra <chandan@linux.vnet.ibm.com>,
Dave Chinner <david@fromorbit.com>,
Christoph Hellwig <hch@lst.de>,
"Darrick J . Wong" <darrick.wong@oracle.com>,
Linus Torvalds <torvalds@linux-foundation.org>
Subject: [PATCH v6 16/17] ext4: update on-disk format documentation for fs-verity
Date: Mon, 1 Jul 2019 08:32:36 -0700 [thread overview]
Message-ID: <20190701153237.1777-17-ebiggers@kernel.org> (raw)
In-Reply-To: <20190701153237.1777-1-ebiggers@kernel.org>
From: Eric Biggers <ebiggers@google.com>
Document the format of verity files on ext4, and the corresponding inode
and superblock flags.
Signed-off-by: Eric Biggers <ebiggers@google.com>
---
Documentation/filesystems/ext4/inodes.rst | 6 ++-
Documentation/filesystems/ext4/overview.rst | 1 +
Documentation/filesystems/ext4/super.rst | 2 +
Documentation/filesystems/ext4/verity.rst | 41 +++++++++++++++++++++
4 files changed, 48 insertions(+), 2 deletions(-)
create mode 100644 Documentation/filesystems/ext4/verity.rst
diff --git a/Documentation/filesystems/ext4/inodes.rst b/Documentation/filesystems/ext4/inodes.rst
index 6bd35e506b6f..e851e6ca31fa 100644
--- a/Documentation/filesystems/ext4/inodes.rst
+++ b/Documentation/filesystems/ext4/inodes.rst
@@ -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
diff --git a/Documentation/filesystems/ext4/overview.rst b/Documentation/filesystems/ext4/overview.rst
index cbab18baba12..123ebfde47ee 100644
--- a/Documentation/filesystems/ext4/overview.rst
+++ b/Documentation/filesystems/ext4/overview.rst
@@ -24,3 +24,4 @@ order.
.. include:: bigalloc.rst
.. include:: inlinedata.rst
.. include:: eainode.rst
+.. include:: verity.rst
diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst
index 04ff079a2acf..6eae92054827 100644
--- a/Documentation/filesystems/ext4/super.rst
+++ b/Documentation/filesystems/ext4/super.rst
@@ -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:
diff --git a/Documentation/filesystems/ext4/verity.rst b/Documentation/filesystems/ext4/verity.rst
new file mode 100644
index 000000000000..3e4c0ee0e068
--- /dev/null
+++ b/Documentation/filesystems/ext4/verity.rst
@@ -0,0 +1,41 @@
+.. 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.
--
2.22.0
next prev parent reply other threads:[~2019-07-01 15:34 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-07-01 15:32 [PATCH v6 00/17] fs-verity: read-only file-based authenticity protection Eric Biggers
2019-07-01 15:32 ` [PATCH v6 01/17] fs-verity: add a documentation file Eric Biggers
2019-07-01 15:32 ` [PATCH v6 02/17] fs-verity: add MAINTAINERS file entry Eric Biggers
2019-07-01 15:32 ` [PATCH v6 03/17] fs-verity: add UAPI header Eric Biggers
2019-07-01 15:32 ` [PATCH v6 04/17] fs: uapi: define verity bit for FS_IOC_GETFLAGS Eric Biggers
2019-07-01 15:32 ` [PATCH v6 05/17] fs-verity: add Kconfig and the helper functions for hashing Eric Biggers
2019-07-01 15:32 ` [PATCH v6 06/17] fs-verity: add inode and superblock fields Eric Biggers
2019-07-01 15:32 ` [PATCH v6 07/17] fs-verity: add the hook for file ->open() Eric Biggers
2019-07-01 15:32 ` [PATCH v6 08/17] fs-verity: add the hook for file ->setattr() Eric Biggers
2019-07-01 15:32 ` [PATCH v6 09/17] fs-verity: add data verification hooks for ->readpages() Eric Biggers
2019-07-01 15:32 ` [PATCH v6 10/17] fs-verity: implement FS_IOC_ENABLE_VERITY ioctl Eric Biggers
2019-07-03 20:14 ` Eric Biggers
2019-07-01 15:32 ` [PATCH v6 11/17] fs-verity: implement FS_IOC_MEASURE_VERITY ioctl Eric Biggers
2019-07-01 15:32 ` [PATCH v6 12/17] fs-verity: add SHA-512 support Eric Biggers
2019-07-01 15:32 ` [PATCH v6 13/17] fs-verity: support builtin file signatures Eric Biggers
2019-07-07 18:47 ` Theodore Ts'o
2019-07-01 15:32 ` [PATCH v6 14/17] ext4: add basic fs-verity support Eric Biggers
2019-07-07 18:51 ` Theodore Ts'o
2019-07-01 15:32 ` [PATCH v6 15/17] ext4: add fs-verity read support Eric Biggers
2019-07-07 18:54 ` Theodore Ts'o
2019-07-01 15:32 ` Eric Biggers [this message]
2019-07-07 18:54 ` [PATCH v6 16/17] ext4: update on-disk format documentation for fs-verity Theodore Ts'o
2019-07-01 15:32 ` [PATCH v6 17/17] f2fs: add fs-verity support Eric Biggers
2019-07-03 1:25 ` [f2fs-dev] " Chao Yu
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190701153237.1777-17-ebiggers@kernel.org \
--to=ebiggers@kernel.org \
--cc=chandan@linux.vnet.ibm.com \
--cc=darrick.wong@oracle.com \
--cc=david@fromorbit.com \
--cc=hch@lst.de \
--cc=jaegeuk@kernel.org \
--cc=linux-api@vger.kernel.org \
--cc=linux-ext4@vger.kernel.org \
--cc=linux-f2fs-devel@lists.sourceforge.net \
--cc=linux-fscrypt@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-integrity@vger.kernel.org \
--cc=torvalds@linux-foundation.org \
--cc=tytso@mit.edu \
--cc=victorhsieh@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).