Documentation: add a usecase for FS_IOC_READ_VERITY_METADATA

Mention another potential usecase for FS_IOC_READ_VERITY_METADATA:
creating filesystem images which contain fs-verity-enabled files,
without having to redo all of the work in userspace.

Signed-off-by: Allison Karlitskaya <allison.karlitskaya@redhat.com>
Link: https://lore.kernel.org/r/20241126084833.70538-1-allison.karlitskaya@redhat.com
Signed-off-by: Eric Biggers <ebiggers@google.com>

diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst
index 76e53821786895033ee18be40bed8ba7e5a5b7d9..dacdbc1149e671537da34d9fb53df8b5d3b1a055 100644 (file)
--- a/Documentation/filesystems/fsverity.rst
+++ b/Documentation/filesystems/fsverity.rst
@@ -248,11 +248,17 @@ FS_IOC_READ_VERITY_METADATA
 The FS_IOC_READ_VERITY_METADATA ioctl reads verity metadata from a
 verity file.  This ioctl is available since Linux v5.12.
 
-This ioctl allows writing 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.
+This ioctl is useful for cases where the verity verification should be
+performed somewhere other than the currently running kernel.
+
+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.
+
+Another example is copying verity metadata when creating filesystem
+images in userspace (such as with ``mkfs.ext4 -d``).
 
 This is a fairly specialized use case, and most fs-verity users won't
 need this ioctl.