Documentation/filesystems/fsverity.rst

Source file repositories/reference/linux-study-clean/Documentation/filesystems/fsverity.rst

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/fsverity.rst
Extension
.rst
Size
43580 bytes
Lines
929
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct 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];
    };

This structure contains the parameters of the Merkle tree to build for
the file.  It must be initialized as follows:

- ``version`` must be 1.
- ``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.
- ``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.
- ``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.
- ``salt_ptr`` is the pointer to the salt, or NULL if no salt is
  provided.
- ``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.
- ``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.
- All reserved fields must be zeroed.

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.

FS_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.)

On 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.

FS_IOC_ENABLE_VERITY can fail with the following errors:

- ``EACCES``: the process does not have write access to the file
- ``EBADMSG``: the builtin signature is malformed
- ``EBUSY``: this ioctl is already running on the file
- ``EEXIST``: the file already has verity enabled
- ``EFAULT``: the caller provided inaccessible memory
- ``EFBIG``: the file is too large to enable verity on
- ``EINTR``: the operation was interrupted by a fatal signal
- ``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.

Annotation

Implementation Notes