path: root/Documentation/filesystems/fsverity.rst

.. SPDX-License-Identifier: GPL-2.0

.. _fsverity:

=======================================================
fs-verity: read-only file-based authenticity protection
=======================================================

Introduction
============

fs-verity (``fs/verity/``) is a support layer that filesystems can
hook into to support transparent integrity and authenticity protection
of read-only files.  Currently, it is supported by the ext4, f2fs, and
btrfs filesystems.  Like fscrypt, not too much filesystem-specific
code is needed to support fs-verity.

fs-verity is similar to `dm-verity
<https://www.kernel.org/doc/Documentation/device-mapper/verity.txt>`_
but works on files rather than block devices.  On regular files on
filesystems supporting fs-verity, userspace can execute an ioctl that
causes the filesystem to build a Merkle tree for the file and persist
it to a filesystem-specific location associated with the file.

After this, the file is made readonly, and all reads from the file are
automatically verified against the file's Merkle tree.  Reads of any
corrupted data, including mmap reads, will fail.

Userspace can use another ioctl to retrieve the root hash (actually
the "fs-verity file digest", which is a hash that includes the Merkle
tree root hash) that fs-verity is enforcing for the file.  This ioctl
executes in constant time, regardless of the file size.

fs-verity is essentially a way to hash a file in constant time,
subject to the caveat that reads which would violate the hash will
fail at runtime.

Use cases
=========

By itself, fs-verity only provides integrity protection, i.e.
detection of accidental (non-malicious) corruption.

However, because fs-verity makes retrieving the file hash extremely
efficient, it's primarily meant to be used as a tool to support
authentication (detection of malicious modifications) or auditing
(logging file hashes before use).

A standard file hash could be used instead of fs-verity.  However,
this is inefficient if the file is large and only a small portion may
be accessed.  This is often the case for Android application package
(APK) files, for example.  These typically contain many translations,
classes, and other resources that are infrequently or even never
accessed on a particular device.  It would be slow and wasteful to
read and hash the entire file before starting the application.

Unlike an ahead-of-time hash, fs-verity also re-verifies data each
time it's paged in.  This ensures that malicious disk firmware can't
undetectably change the contents of the file at runtime.

fs-verity does not replace or obsolete dm-verity.  dm-verity should
still be used on read-only filesystems.  fs-verity is for files that
must live on a read-write filesystem because they are independently
updated and potentially user-installed, so dm-verity cannot be used.

fs-verity does not mandate a particular scheme for authenticating its
file hashes.  (Similarly, dm-verity does not mandate a particular
scheme for authenticating its block device root hashes.)  Options for
authenticating fs-verity file hashes include:

- Trusted userspace code.  Often, the userspace code that accesses
  files can be trusted to authenticate them.  Consider e.g. an
  application that wants to authenticate data files before using them,
  or an application loader that is part of the operating system (which
  is already authenticated in a different way, such as by being loaded
  from a read-only partition that uses dm-verity) and that wants to
  authenticate applications before loading them.  In these cases, this
  trusted userspace code can authenticate a file's contents by
  retrieving its fs-verity digest using `FS_IOC_MEASURE_VERITY`_, then
  verifying a signature of it using any userspace cryptographic
  library that supports digital signatures.

- Integrity Measurement Architecture (IMA).  IMA supports fs-verity
  file digests as an alternative to its traditional full file digests.
  "IMA appraisal" enforces that files contain a valid, matching
  signature in their "security.ima" extended attribute, as controlled
  by the IMA policy.  For more information, see the IMA documentation.

- Integrity Policy Enforcement (IPE).  IPE supports enforcing access
  control decisions based on immutable security properties of files,
  including those protected by fs-verity's built-in signatures.
  "IPE policy" specifically allows for the authorization of fs-verity
  files using properties ``fsverity_digest`` for identifying
  files by their verity digest, and ``fsverity_signature`` to authorize
  files with a verified fs-verity's built-in signature. For
  details on configuring IPE policies and understanding its operational
  modes, please refer to :doc:`IPE admin guide </admin-guide/LSM/ipe>`.

- Trusted userspace code in combination with `Built-in signature
  verification`_.  This approach should be used only with great care.

User API
========

FS_IOC_ENABLE_VERITY
--------------------

The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file.  It takes
in a pointer to a struct fsverity_enable_arg, defined as
follows::

    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.
- ``EISDIR``: the file descriptor refers to a directory
- ``EKEYREJECTED``: the builtin signature doesn't match the file
- ``EMSGSIZE``: the salt or builtin signature is too long
- ``ENOKEY``: the ".fs-verity" keyring doesn't contain the certificate
  needed to verify the builtin signature
- ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not
  available in the kernel's crypto API as currently configured (e.g.
  for SHA-512, missing CONFIG_CRYPTO_SHA512).
- ``ENOTTY``: this type of filesystem does not implement fs-verity
- ``EOPNOTSUPP``: the kernel was not configured with fs-verity
  support; or the filesystem superblock has not had the 'verity'
  feature enabled on it; or the filesystem does not support fs-verity
  on this file.  (See `Filesystem support`_.)
- ``EPERM``: the file is append-only; or, a builtin signature is
  required and one was not provided.
- ``EROFS``: the filesystem is read-only
- ``ETXTBSY``: someone has the file open for writing.  This can be the
  caller's file descriptor, another open file descriptor, or the file
  reference held by a writable memory map.

FS_IOC_MEASURE_VERITY
---------------------

The FS_IOC_MEASURE_VERITY ioctl retrieves the digest of a verity file.
The fs-verity file digest is a cryptographic digest that identifies
the file contents that are being enforced on reads; it is computed via
a Merkle tree and is different from a traditional full-file digest.

This ioctl takes in a pointer to a variable-length structure::

    struct fsverity_digest {
            __u16 digest_algorithm;
            __u16 digest_size; /* input/output */
            __u8 digest[];
    };

``digest_size`` is an input/output field.  On input, it must be
initialized to the number of bytes allocated for the variable-length
``digest`` field.

On success, 0 is returned and the kernel fills in the structure as
follows:

- ``digest_algorithm`` will be the hash algorithm used for the file
  digest.  It will match ``fsverity_enable_arg::hash_algorithm``.
- ``digest_size`` will be the size of the digest in bytes, e.g. 32
  for SHA-256.  (This can be redundant with ``digest_algorithm``.)
- ``digest`` will be the actual bytes of the digest.

FS_IOC_MEASURE_VERITY is guaranteed to execute in constant time,
regardless of the size of the file.

FS_IOC_MEASURE_VERITY can fail with the following errors:

- ``EFAULT``: the caller provided inaccessible memory
- ``ENODATA``: the file is not a verity file
- ``ENOTTY``: this type of filesystem does not implement fs-verity
- ``EOPNOTSUPP``: the kernel was not configured with fs-verity
  support, or the filesystem superblock has not had the 'verity'
  feature enabled on it.  (See `Filesystem support`_.)
- ``EOVERFLOW``: the digest is longer than the specified
  ``digest_size`` bytes.  Try providing a larger buffer.

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 is a fairly specialized use case, and most fs-verity users won't
need this ioctl.

This ioctl takes in a pointer to the following structure::

   #define FS_VERITY_METADATA_TYPE_MERKLE_TREE     1
   #define FS_VERITY_METADATA_TYPE_DESCRIPTOR      2
   #define FS_VERITY_METADATA_TYPE_SIGNATURE       3

   struct fsverity_read_metadata_arg {
           __u64 metadata_type;
           __u64 offset;
           __u64 length;
           __u64 buf_ptr;
           __u64 __reserved;
   };

``metadata_type`` specifies the type of metadata to read:

- ``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the
  Merkle tree.  The blocks are returned in order from the root level
  to the leaf level.  Within each level, the blocks are returned in
  the same order that their hashes are themselves hashed.
  See `Merkle tree`_ for more information.

- ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity
  descriptor.  See `fs-verity descriptor`_.

- ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the builtin signature
  which was passed to FS_IOC_ENABLE_VERITY, if any.  See `Built-in
  signature verification`_.

The semantics are similar to those of ``pread()``.  ``offset``
specifies the offset in bytes into the metadata item to read from, and
``length`` specifies the maximum number of bytes to read from the
metadata item.  ``buf_ptr`` is the pointer to the buffer to read into,
cast to a 64-bit integer.  ``__reserved`` must be 0.  On success, the
number of bytes read is returned.  0 is returned at the end of the
metadata item.  The returned length may be less than ``length``, for
example if the ioctl is interrupted.

The metadata returned by FS_IOC_READ_VERITY_METADATA isn't guaranteed
to be authenticated against the file digest that would be returned by
`FS_IOC_MEASURE_VERITY`_, as the metadata is expected to be used to
implement fs-verity compatible verification anyway (though absent a
malicious disk, the metadata will indeed match).  E.g. to implement
this ioctl, the filesystem is allowed to just read the Merkle tree
blocks from disk without actually verifying the path to the root node.

FS_IOC_READ_VERITY_METADATA can fail with the following errors:

- ``EFAULT``: the caller provided inaccessible memory
- ``EINTR``: the ioctl was interrupted before any data was read
- ``EINVAL``: reserved fields were set, or ``offset + length``
  overflowed
- ``ENODATA``: the file is not a verity file, or
  FS_VERITY_METADATA_TYPE_SIGNATURE was requested but the file doesn't
  have a builtin signature
- ``ENOTTY``: this type of filesystem does not implement fs-verity, or
  this ioctl is not yet implemented on it
- ``EOPNOTSUPP``: the kernel was not configured with fs-verity
  support, or the filesystem superblock has not had the 'verity'
  feature enabled on it.  (See `Filesystem support`_.)

FS_IOC_GETFLAGS
---------------

The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
can also be used to check whether a file has fs-verity enabled or not.
To do so, check for FS_VERITY_FL (0x00100000) in the returned flags.

The verity flag is not settable via FS_IOC_SETFLAGS.  You must use
FS_IOC_ENABLE_VERITY instead, since parameters must be provided.

statx
-----

Since Linux v5.5, the statx() system call sets STATX_ATTR_VERITY if
the file has fs-verity enabled.  This can perform better than
FS_IOC_GETFLAGS and FS_IOC_MEASURE_VERITY because it doesn't require
opening the file, and opening verity files can be expensive.

.. _accessing_verity_files:

Accessing verity files
======================

Applications can transparently access a verity file just like a
non-verity one, with the following exceptions:

- Verity files are readonly.  They cannot be opened for writing or
  truncate()d, even if the file mode bits allow it.  Attempts to do
  one of these things will fail with EPERM.  However, changes to
  metadata such as owner, mode, timestamps, and xattrs are still
  allowed, since these are not measured by fs-verity.  Verity files
  can also still be renamed, deleted, and linked to.

- Direct I/O is not supported on verity files.  Attempts to use direct
  I/O on such files will fall back to buffered I/O.

- DAX (Direct Access) is not supported on verity files, because this
  would circumvent the data verification.

- Reads of data that doesn't match the verity Merkle tree will fail
  with EIO (for read()) or SIGBUS (for mmap() reads).

- If the sysctl "fs.verity.require_signatures" is set to 1 and the
  file is not signed by a key in the ".fs-verity" keyring, then
  opening the file will fail.  See `Built-in signature verification`_.

Direct access to the Merkle tree is not supported.  Therefore, if a
verity file is copied, or is backed up and restored, then it will lose
its "verity"-ness.  fs-verity is primarily meant for files like
executables that are managed by a package manager.

File digest computation
=======================

This section describes how fs-verity hashes the file contents using a
Merkle tree to produce the digest which cryptographically identifies
the file contents.  This algorithm is the same for all filesystems
that support fs-verity.

Userspace only needs to be aware of this algorithm if it needs to
compute fs-verity file digests itself, e.g. in order to sign files.

.. _fsverity_merkle_tree:

Merkle tree
-----------

The file contents is divided into blocks, where the block size is
configurable but is usually 4096 bytes.  The end of the last block is
zero-padded if needed.  Each block is then hashed, producing the first
level of hashes.  Then, the hashes in this first level are grouped
into 'blocksize'-byte blocks (zero-padding the ends as needed) and
these blocks are hashed, producing the second level of hashes.  This
proceeds up the tree until only a single block remains.  The hash of
this block is the "Merkle tree root hash".

If the file fits in one block and is nonempty, then the "Merkle tree
root hash" is simply the hash of the single data block.  If the file
is empty, then the "Merkle tree root hash" is all zeroes.

The "blocks" here are not necessarily the same as "filesystem blocks".

If a salt was specified, then it's zero-padded to the closest multiple
of the input size of the hash algorithm's compression function, e.g.
64 bytes for SHA-256 or 128 bytes for SHA-512.  The padded salt is
prepended to every data or Merkle tree block that is hashed.

The purpose of the block padding is to cause every hash to be taken
over the same amount of data, which simplifies the implementation and
keeps open more possibilities for hardware acceleration.  The purpose
of the salt padding is to make the salting "free" when the salted hash
state is precomputed, then imported for each hash.

Example: in the recommended configuration of SHA-256 and 4K blocks,
128 hash values fit in each block.  Thus, each level of the Merkle
tree is approximately 128 times smaller than the previous, and for
large files the Merkle tree's size converges to approximately 1/127 of
the original file size.  However, for small files, the padding is
significant, making the space overhead proportionally more.

.. _fsverity_descriptor:

fs-verity descriptor
--------------------

By itself, the Merkle tree root hash is ambiguous.  For example, it
can't a distinguish a large file from a small second file whose data
is exactly the top-level hash block of the first file.  Ambiguities
also arise from the convention of padding to the next block boundary.

To solve this problem, the fs-verity file digest is actually computed
as a hash of the following structure, which contains the Merkle tree
root hash as well as other fields such as the file size::

    struct fsverity_descriptor {
            __u8 version;           /* must be 1 */
            __u8 hash_algorithm;    /* Merkle tree hash algorithm */
            __u8 log_blocksize;     /* log2 of size of data and tree blocks */
            __u8 salt_size;         /* size of salt in bytes; 0 if none */
            __le32 __reserved_0x04; /* must be 0 */
            __le64 data_size;       /* size of file the Merkle tree is built over */
            __u8 root_hash[64];     /* Merkle tree root hash */
            __u8 salt[32];          /* salt prepended to each hashed block */
            __u8 __reserved[144];   /* must be 0's */
    };

Built-in signature verification
===============================

CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y adds supports for in-kernel
verification of fs-verity builtin signatures.

**IMPORTANT**!  Please take great care before using this feature.
It is not the only way to do signatures with fs-verity, and the
alternatives (such as userspace signature verification, and IMA
appraisal) can be much better.  It's also easy to fall into a trap
of thinking this feature solves more problems than it actually does.

Enabling this option adds the following:

1. At boot time, the kernel creates a keyring named ".fs-verity".  The
   root user can add trusted X.509 certificates to this keyring using
   the add_key() system call.

2. `FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted
   detached signature in DER format of the file's fs-verity digest.
   On success, the ioctl persists the signature alongside the Merkle