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

개요와 인증·감사 사용 사례

fs-verity(`fs/verity/`)는 파일시스템이 연결하여 읽기 전용 파일의 무결성과 진본성을 투명하게 보호할 수 있게 하는 지원 계층입니다. 현재 ext4, f2fs, btrfs가 지원하며 fscrypt와 마찬가지로 파일시스템별 코드는 많지 않습니다.

dm-verity가 블록 장치에 적용되는 것과 달리 fs-verity는 개별 파일에 적용됩니다. 지원 파일시스템의 일반 파일에 ioctl을 실행하면 파일시스템이 파일의 Merkle tree를 만들고 그 파일에 연결된 파일시스템별 위치에 영속화합니다.

활성화가 끝난 파일은 읽기 전용이 되고 이후 모든 읽기를 Merkle tree와 자동 대조합니다. 손상된 데이터의 `read()`뿐 아니라 `mmap()` 읽기도 실패합니다. 별도 ioctl은 tree root hash 자체가 아니라 이를 포함하는 fs-verity file digest를 반환하며, 파일 크기와 무관하게 상수 시간에 실행됩니다.

따라서 fs-verity는 런타임에서 digest를 위반하는 읽기를 실패시키는 조건 아래 파일을 상수 시간에 해시하는 수단으로 볼 수 있습니다.

fs-verity 자체만으로는 우발적이고 비악의적인 손상을 탐지하는 무결성 보호를 제공합니다. 그러나 파일 hash 조회가 매우 효율적이므로 실제 주된 목적은 악의적 변경을 탐지하는 인증이나 사용 전 hash를 기록하는 감사의 기반이 되는 것입니다.

일반적인 전체 파일 hash도 쓸 수 있지만 큰 파일에서 일부만 읽을 때 비효율적입니다. Android APK처럼 번역·class·resource 중 장치에서 거의 또는 전혀 접근하지 않는 데이터가 많은 파일을 시작 전에 전부 읽고 hash하면 느리고 낭비가 큽니다. fs-verity는 필요한 data block만 검증합니다.

사전 계산 hash와 달리 데이터가 page-in될 때마다 다시 검증하므로 악의적인 disk firmware가 실행 중 파일 내용을 몰래 바꾸는 것도 탐지합니다.

fs-verity는 dm-verity를 대체하지 않습니다. 읽기 전용 파일시스템에는 계속 dm-verity를 사용해야 합니다. fs-verity는 독립적으로 갱신되거나 사용자가 설치하여 read-write 파일시스템에 있어야 하는 개별 파일을 보호합니다.

file digest의 인증 방식은 강제하지 않습니다. 신뢰하는 사용자 공간 코드는 `FS_IOC_MEASURE_VERITY`로 digest를 얻고 원하는 digital signature 라이브러리로 서명을 검증할 수 있습니다. 운영체제가 이미 dm-verity partition에서 인증되어 로드한 application loader나 data file을 검증하는 application이 대표적인 예입니다.

IMA는 전통적인 전체 파일 digest 대신 fs-verity digest를 지원하며, IMA policy가 제어하는 `security.ima` xattr의 일치하는 유효 서명을 IMA appraisal로 강제할 수 있습니다.

IPE는 변경 불가능한 보안 속성에 따른 접근 결정을 강제합니다. `fsverity_digest`로 digest에 따라 파일을 식별하고 `fsverity_signature`로 검증된 내장 fs-verity 서명을 가진 파일을 허가할 수 있습니다. 구성과 동작 모드는 `IPE admin guide </admin-guide/LSM/ipe>`를 참고합니다.

신뢰하는 사용자 공간과 fs-verity의 내장 서명 검증을 함께 쓸 수도 있지만 매우 신중해야 합니다. 내장 서명은 가능한 여러 인증 방식 가운데 하나이며 완전한 인증 정책을 자동으로 제공하지 않습니다.

.. 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/admin-guide/device-mapper/verity.rst>`_
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와 digest 측정

`FS_IOC_ENABLE_VERITY`는 파일에서 fs-verity를 활성화하며 `struct fsverity_enable_arg` 포인터를 인수로 받습니다.

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

`version`은 1이어야 합니다. `hash_algorithm`은 `FS_VERITY_HASH_ALG_SHA256` 같은 Merkle tree hash 식별자이며 가능한 값은 `include/uapi/linux/fsverity.h`에 정의됩니다.

`block_size`는 Merkle tree block 크기입니다. Linux 6.3 이상에서는 1024부터 system page size와 filesystem block size 중 작은 값까지의 2의 거듭제곱을 허용합니다. 이전 커널은 page size만 허용했습니다.

`salt_size`는 salt 바이트 수이며 없으면 0입니다. salt는 hash하는 모든 block 앞에 붙여 특정 파일이나 장치에 hash를 개인화할 수 있고 현재 최대 32바이트입니다. `salt_ptr`은 salt 주소이며 없으면 NULL입니다.

`sig_size`는 builtin signature 길이이며 없으면 0, 현재 상한은 다소 임의로 정한 16,128바이트입니다. `sig_ptr`은 서명 주소이며 없으면 NULL입니다. 내장 서명 검증을 쓸 때만 필요하고 IMA appraisal이나 사용자 공간에서 전부 처리하는 서명에는 필요하지 않습니다. 모든 reserved field는 0이어야 합니다.

ioctl은 Merkle tree를 만들고 파일에 연결된 파일시스템별 위치에 저장한 뒤 파일을 verity file로 표시합니다. 큰 파일에서는 오래 걸릴 수 있고 fatal signal로 중단할 수 있습니다.

inode에 대한 write access를 검사하지만 fd 자체는 `O_RDONLY`로 열어야 하며 어떤 프로세스도 파일을 쓰기 위해 열고 있으면 안 됩니다. 실행 중 새 write open은 `ETXTBSY`입니다. 활성화 뒤 writable fd가 남지 않고 tree 생성 중 내용이 안정적임을 보장하기 위한 조건입니다.

성공하면 0을 반환하고 파일이 verity file이 됩니다. fatal signal 중단을 포함해 실패하면 파일에는 아무 변경도 하지 않습니다. 즉 파일시스템 transaction과 결합된 all-or-nothing 동작입니다.

ENABLE 오류는 write access 없음 `EACCES`, 잘못된 builtin signature `EBADMSG`, 같은 ioctl 실행 중 `EBUSY`, 이미 활성화 `EEXIST`, 접근 불가 사용자 메모리 `EFAULT`, 지나치게 큰 파일 `EFBIG`, fatal signal `EINTR`, 버전·algorithm·block size·reserved·fd 형식 오류 `EINVAL`, 디렉터리 `EISDIR`입니다.

서명이 file digest와 불일치하면 `EKEYREJECTED`, salt 또는 signature가 너무 길면 `EMSGSIZE`, `.fs-verity` keyring에 필요한 certificate가 없으면 `ENOKEY`, algorithm은 알지만 커널 구성에 없으면 `ENOPKG`입니다.

파일시스템이 ioctl을 구현하지 않으면 `ENOTTY`, 커널 구성·superblock verity feature·해당 파일의 지원 조건이 맞지 않으면 `EOPNOTSUPP`, append-only 또는 필수 서명 누락이면 `EPERM`, read-only filesystem이면 `EROFS`, fd·다른 fd·writable mmap이 쓰기 참조를 보유하면 `ETXTBSY`입니다.

`FS_IOC_MEASURE_VERITY`는 읽을 때 강제되는 파일 내용을 암호학적으로 식별하는 fs-verity file digest를 가져옵니다. Merkle tree로 계산되므로 전통적인 전체 파일 digest와 다릅니다.

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

호출자는 가변 `digest`에 할당한 바이트 수로 입력 `digest_size`를 초기화합니다. 성공하면 0과 함께 tree에 사용한 `digest_algorithm`, 실제 길이 `digest_size`(SHA-256은 32), digest 바이트를 반환합니다. algorithm은 `fsverity_enable_arg::hash_algorithm`과 일치합니다.

MEASURE는 파일 크기와 관계없이 상수 시간입니다. 오류는 접근 불가 메모리 `EFAULT`, verity file 아님 `ENODATA`, 파일시스템 미구현 `ENOTTY`, 커널 또는 superblock 미지원 `EOPNOTSUPP`, 버퍼가 작음 `EOVERFLOW`이며 마지막 경우 더 큰 버퍼로 재시도합니다.

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 as currently configured
- ``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.

Verity metadata 조회와 상태 확인

Linux 5.12부터 `FS_IOC_READ_VERITY_METADATA`는 verity file의 metadata를 읽습니다. 현재 커널이 아닌 다른 곳에서 fs-verity 호환 검증을 수행해야 하는 전문 용도입니다.

예를 들어 신뢰하지 않는 server가 storage를 제공하고 client가 자체 검증하도록 verity file을 전송하거나, `mkfs.ext4 -d`처럼 사용자 공간에서 filesystem image를 만들 때 verity metadata를 복사하는 데 사용할 수 있습니다. 일반 fs-verity 사용자는 대부분 필요하지 않습니다.

#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;
};

`FS_VERITY_METADATA_TYPE_MERKLE_TREE`는 root level부터 leaf level 순으로 tree block을 반환합니다. 각 level 안에서는 그 hash들이 다시 hash되는 순서와 같은 순서입니다. `DESCRIPTOR`는 fs-verity descriptor, `SIGNATURE`는 ENABLE에 전달한 builtin signature가 있을 때 이를 읽습니다.

동작은 `pread()`와 유사합니다. `offset`은 metadata item 안의 byte offset, `length`는 최대 읽기 길이, `buf_ptr`은 64비트 정수로 cast한 buffer 주소이며 `__reserved`는 0입니다. 성공하면 실제 읽은 byte 수, item 끝에서는 0을 반환합니다. 중단 등으로 요청보다 적게 반환할 수 있습니다.

READ_METADATA가 반환한 정보는 `FS_IOC_MEASURE_VERITY` digest에 대해 인증되었다고 보장되지 않습니다. 이 ioctl의 목적 자체가 별도 fs-verity 호환 검증 구현이므로 파일시스템은 root 경로를 검증하지 않고 disk의 tree block을 그대로 읽을 수 있습니다. 악의적 disk가 없다면 실제로는 일치합니다.

오류는 접근 불가 메모리 `EFAULT`, 한 byte도 읽기 전 중단 `EINTR`, reserved 설정 또는 `offset + length` overflow `EINVAL`, verity file이 아니거나 요청한 signature가 없음 `ENODATA`, 파일시스템 또는 해당 ioctl 미구현 `ENOTTY`, 커널·superblock 미지원 `EOPNOTSUPP`입니다.

기존 `FS_IOC_GETFLAGS`의 반환 flag에 `FS_VERITY_FL`(0x00100000)이 있는지 검사해 활성화 여부를 알 수 있습니다. 이 flag는 `FS_IOC_SETFLAGS`로 설정할 수 없으며 parameter가 필요한 `FS_IOC_ENABLE_VERITY`만 사용해야 합니다.

Linux 5.5부터 `statx()`는 활성화 파일에 `STATX_ATTR_VERITY`를 설정합니다. 파일을 열 필요가 없어 `FS_IOC_GETFLAGS`나 `FS_IOC_MEASURE_VERITY`보다 빠를 수 있으며 verity file open 자체가 비쌀 수 있는 상황에 적합합니다.

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

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:

접근 의미, Merkle tree와 descriptor

애플리케이션은 몇 가지 예외를 제외하면 verity file을 일반 파일처럼 투명하게 읽습니다. 파일 내용은 읽기 전용이므로 mode bit가 허용해도 write open이나 `truncate()`는 `EPERM`입니다. owner, mode, timestamp, xattr 같은 metadata는 fs-verity 측정 대상이 아니므로 변경할 수 있고 rename, delete, link도 가능합니다.

direct I/O는 지원하지 않아 buffered I/O로 폴백합니다. DAX는 data verification을 우회하므로 지원하지 않습니다. Merkle tree와 맞지 않는 데이터는 `read()`에서 `EIO`, `mmap()` 읽기에서 `SIGBUS`가 됩니다.

`fs.verity.require_signatures=1`이고 `.fs-verity` keyring의 키로 서명되지 않았다면 file open이 실패합니다. Merkle tree에 직접 접근할 수 없으므로 파일을 일반 복사하거나 backup·restore하면 verity 속성을 잃습니다. package manager가 관리하는 executable 같은 파일이 주된 대상입니다.

지원 파일시스템 모두 같은 알고리즘으로 file contents를 Merkle tree로 hash해 내용을 암호학적으로 식별하는 digest를 만듭니다. 사용자 공간이 직접 digest를 계산해 서명해야 할 때만 이 알고리즘을 구현할 필요가 있습니다.

파일은 보통 4096바이트인 구성 가능한 block으로 나뉘고 마지막 block은 필요하면 0으로 채웁니다. 각 data block hash가 첫 level이 되고, hash들을 다시 block_size 단위 block으로 묶어 끝을 0으로 채운 뒤 hash해 다음 level을 만듭니다. block 하나만 남을 때까지 반복하고 그 block의 hash가 Merkle tree root hash입니다.

0이 아닌 파일이 한 block에 맞으면 root hash는 그 단일 data block hash입니다. 빈 파일의 root hash는 모두 0입니다. 여기서 block은 filesystem block과 반드시 같지 않습니다.

salt가 있으면 hash compression function input size의 가장 가까운 배수로 0 padding합니다. SHA-256은 64바이트, SHA-512는 128바이트 단위입니다. padded salt를 hash하는 모든 data block과 tree block 앞에 붙입니다.

block padding은 모든 hash가 같은 양의 data를 처리하게 해 구현을 단순화하고 hardware acceleration 가능성을 넓힙니다. salt padding은 salted hash state를 미리 계산해 각 hash에 import할 때 salting 비용을 사실상 없앱니다.

권장 SHA-256과 4K block에서는 block마다 128개 hash가 들어갑니다. 각 level은 아래 level의 약 1/128이고 큰 파일에서 tree 크기는 원본의 약 1/127에 수렴합니다. 작은 파일은 padding 비중이 커서 상대 overhead가 큽니다.

root hash만으로는 큰 파일과 그 큰 파일의 top-level hash block을 data로 가진 작은 파일을 구분하지 못하고 block boundary padding에서도 모호성이 생깁니다. 그래서 실제 file digest는 root hash와 file size 등 문맥을 담은 `struct fsverity_descriptor` 전체의 hash입니다.

struct fsverity_descriptor {
        __u8 version;           /* must be 1 */
        __u8 hash_algorithm;
        __u8 log_blocksize;
        __u8 salt_size;
        __le32 __reserved_0x04; /* must be 0 */
        __le64 data_size;
        __u8 root_hash[64];
        __u8 salt[32];
        __u8 __reserved[144];   /* must be 0's */
};

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 */
    };

내장 서명 검증의 동작과 한계

`CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y`는 fs-verity builtin signature의 커널 내부 검증을 추가합니다. 그러나 유일한 서명 방법이 아니며 사용자 공간 검증이나 IMA appraisal이 훨씬 나을 수 있습니다. 실제보다 더 많은 문제를 해결한다고 오해하기 쉬우므로 사용 전 각 한계를 검토해야 합니다.

부팅 때 커널은 `.fs-verity` keyring을 만들고 root는 `add_key()`로 신뢰할 X.509 certificate를 추가할 수 있습니다.

`FS_IOC_ENABLE_VERITY`는 file digest에 대한 DER 형식 PKCS#7 detached signature를 받을 수 있습니다. 성공하면 Merkle tree와 함께 저장합니다. 그 뒤 파일을 열 때마다 `.fs-verity` certificate로 실제 digest와 signature를 검증합니다. signature가 존재하는 동안은 `fs.verity.require_signatures` 값과 무관하게 검증하며 IPE LSM이 검증된 builtin signature 파일을 인식·표시하는 데 이 동작을 사용합니다.

새 sysctl `fs.verity.require_signatures`를 1로 설정하면 모든 verity file이 올바르게 서명된 digest를 가져야 합니다.

서명 대상은 단순 digest byte가 아니라 magic `FSVerity`, little-endian algorithm과 size, digest를 연결한 `struct fsverity_formatted_digest`입니다.

struct fsverity_formatted_digest {
        char magic[8];          /* must be "FSVerity" */
        __le16 digest_algorithm;
        __le16 digest_size;
        __u8 digest[];
};

내장 검증은 어떤 파일이 fs-verity를 실제로 사용하도록 강제하지 않으므로 완전한 인증 정책이 아닙니다. 신뢰 사용자 공간이 접근 전에 서명과 활성화를 명시적으로 확인해야 합니다. `require_signatures=1`이면 활성화 여부만 확인해도 되지만, 그 정도 사용자 공간 신뢰가 있다면 signature를 파일 옆에 저장하고 암호 라이브러리로 직접 검증할 수도 있습니다.

대안으로 IPE LSM과 결합해 검증된 builtin signature 파일만 실행 같은 특정 연산을 허용하는 커널 강제 시스템 전체 정책을 만들 수 있습니다. IPE는 `fs.verity.require_signatures=1`을 요구하지 않습니다.

builtin signature는 fs-verity 활성화와 동시에만 설정할 수 있습니다. 나중에 변경하거나 삭제하려면 파일을 다시 만들어야 합니다.

시스템의 모든 fs-verity 파일이 같은 공개키 집합을 공유합니다. 파일마다 다른 신뢰 키 범위를 지정할 수 없고 각 키는 전체 파일에 대해 all-or-nothing입니다. `fs.verity.require_signatures`도 시스템 전체에 적용되어 모든 사용자가 1 설정에 동의해야 하므로 유용한 일부 배포를 막을 수 있습니다.

커널이 지원하는 signature algorithm만 쓸 수 있고 새 암호 설계에 흔히 권장되는 Ed25519는 아직 커널이 지원하지 않습니다.

builtin signature는 PKCS#7, 공개키는 X.509입니다. 널리 쓰이고 기능이 많지만 1990년대 ASN.1 기반 형식의 복잡한 parser·handler는 역사적으로 취약점의 원인이 됐으며 이는 암호 자체에 필연적인 복잡성이 아닙니다.

X.509·PKCS#7 고급 기능이 필요 없다면 단순 Ed25519 key와 signature를 사용자 공간에서 검증하는 방식을 강하게 고려해야 합니다. 두 형식을 계속 쓰더라도 사용자 공간 검증은 더 유연하고 `CONFIG_FS_VERITY_BUILTIN_SIGNATURES`가 늘리는 kernel attack surface를 피합니다.

고급 X.509·PKCS#7 기능은 커널에서 항상 의도대로 작동하지 않습니다. 예를 들어 커널은 X.509 certificate validity time을 검사하지 않습니다. fs-verity를 지원하는 IMA appraisal은 signature에 PKCS#7을 쓰지 않아 일부 문제를 피하지만 X.509는 사용합니다.

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
   tree.  Then, any time the file is opened, the kernel verifies the
   file's actual digest against this signature, using the certificates
   in the ".fs-verity" keyring. This verification happens as long as the
   file's signature exists, regardless of the state of the sysctl variable
   "fs.verity.require_signatures" described in the next item. The IPE LSM
   relies on this behavior to recognize and label fsverity files
   that contain a verified built-in fsverity signature.

3. A new sysctl "fs.verity.require_signatures" is made available.
   When set to 1, the kernel requires that all verity files have a
   correctly signed digest as described in (2).

The data that the signature as described in (2) must be a signature of
is the fs-verity file digest in the following format::

    struct fsverity_formatted_digest {
            char magic[8];                  /* must be "FSVerity" */
            __le16 digest_algorithm;
            __le16 digest_size;
            __u8 digest[];
    };

That's it.  It should be emphasized again that fs-verity builtin
signatures are not the only way to do signatures with fs-verity.  See
`Use cases`_ for an overview of ways in which fs-verity can be used.
fs-verity builtin signatures have some major limitations that should
be carefully considered before using them:

- Builtin signature verification does *not* make the kernel enforce
  that any files actually have fs-verity enabled.  Thus, it is not a
  complete authentication policy.  Currently, if it is used, one
  way to complete the authentication policy is for trusted userspace
  code to explicitly check whether files have fs-verity enabled with a
  signature before they are accessed.  (With
  fs.verity.require_signatures=1, just checking whether fs-verity is
  enabled suffices.)  But, in this case the trusted userspace code
  could just store the signature alongside the file and verify it
  itself using a cryptographic library, instead of using this feature.

- Another approach is to utilize fs-verity builtin signature
  verification in conjunction with the IPE LSM, which supports defining
  a kernel-enforced, system-wide authentication policy that allows only
  files with a verified fs-verity builtin signature to perform certain
  operations, such as execution. Note that IPE doesn't require
  fs.verity.require_signatures=1.
  Please refer to :doc:`IPE admin guide </admin-guide/LSM/ipe>` for
  more details.

- A file's builtin signature can only be set at the same time that
  fs-verity is being enabled on the file.  Changing or deleting the
  builtin signature later requires re-creating the file.

- Builtin signature verification uses the same set of public keys for
  all fs-verity enabled files on the system.  Different keys cannot be
  trusted for different files; each key is all or nothing.

- The sysctl fs.verity.require_signatures applies system-wide.
  Setting it to 1 only works when all users of fs-verity on the system
  agree that it should be set to 1.  This limitation can prevent
  fs-verity from being used in cases where it would be helpful.

- Builtin signature verification can only use signature algorithms
  that are supported by the kernel.  For example, the kernel does not
  yet support Ed25519, even though this is often the signature
  algorithm that is recommended for new cryptographic designs.

- fs-verity builtin signatures are in PKCS#7 format, and the public
  keys are in X.509 format.  These formats are commonly used,
  including by some other kernel features (which is why the fs-verity
  builtin signatures use them), and are very feature rich.
  Unfortunately, history has shown that code that parses and handles
  these formats (which are from the 1990s and are based on ASN.1)
  often has vulnerabilities as a result of their complexity.  This
  complexity is not inherent to the cryptography itself.

  fs-verity users who do not need advanced features of X.509 and
  PKCS#7 should strongly consider using simpler formats, such as plain
  Ed25519 keys and signatures, and verifying signatures in userspace.

  fs-verity users who choose to use X.509 and PKCS#7 anyway should
  still consider that verifying those signatures in userspace is more
  flexible (for other reasons mentioned earlier in this document) and
  eliminates the need to enable CONFIG_FS_VERITY_BUILTIN_SIGNATURES
  and its associated increase in kernel attack surface.  In some cases
  it can even be necessary, since advanced X.509 and PKCS#7 features
  do not always work as intended with the kernel.  For example, the
  kernel does not check X.509 certificate validity times.

  Note: IMA appraisal, which supports fs-verity, does not use PKCS#7
  for its signatures, so it partially avoids the issues discussed
  here.  IMA appraisal does use X.509.

Filesystem support
==================

fs-verity is supported by several filesystems, described below.  The

ext4, f2fs, btrfs 지원과 metadata 저장

모든 지원 파일시스템에서 `CONFIG_FS_VERITY`가 필요합니다. `include/linux/fsverity.h`는 `fs/verity/` 계층과 파일시스템 사이 인터페이스를 선언합니다. 파일시스템은 Merkle tree block과 `fsverity_descriptor`를 파일시스템별 위치에서 읽고 쓰는 `fsverity_operations`를 제공하고, file open이나 pagecache read 완료 같은 시점에 `fs/verity/` 함수를 호출해야 합니다.

ext4는 Linux 5.4와 e2fsprogs 1.45.2부터 지원합니다. 포맷할 때 `-O verity`를 주거나 `tune2fs -O verity`를 실행해야 합니다. verity는 RO_COMPAT feature이므로 설정 뒤 구형 커널은 read-only로만 마운트하고 구형 e2fsck는 검사할 수 없습니다.

초기 ext4 구현은 filesystem block size가 보통 4096바이트인 system page size와 같아야 했지만 Linux 6.3에서 제한이 제거됐습니다. verity inode의 on-disk `EXT4_VERITY_FL`은 ENABLE ioctl만 설정할 수 있고 지울 수 없습니다.

ext4 암호화와 fs-verity를 동시에 쓸 때 암호문이 아니라 평문을 검증합니다. 파일마다 암호문이 달라져도 file digest가 의미 있게 유지되기 위한 조건입니다.

ext4는 `i_size`를 넘는 첫 64K boundary부터 파일 끝 뒤에 Merkle tree와 descriptor를 저장합니다. verity file이 읽기 전용이고 `i_size` 완전히 뒤의 page는 사용자 공간에 보이지 않으면서 ext4 내부에서는 작은 변경으로 읽고 쓸 수 있어 가능한 설계입니다.

이 방식은 EA_INODE에 의존하거나 multi-gigabyte xattr를 paging하고 암호화하도록 ext4 xattr를 재설계하는 일을 피합니다. 파일이 암호화됐다면 평문 hash를 담는 verity metadata도 반드시 암호화해야 합니다. ext4는 extent 기반 파일에만 verity를 허용합니다.

f2fs는 Linux 5.4와 f2fs-tools 1.11.0부터 지원하며 포맷할 때 `-O verity`가 필요합니다. `FADVISE_VERITY_BIT`는 ENABLE ioctl만 설정하고 지울 수 없습니다.

f2fs도 `i_size` 뒤 첫 64K boundary부터 metadata를 저장합니다. inode당 xattr entry가 최대 4096바이트라 보통 Merkle tree block 하나도 담기 어려워 이 방식이 필요합니다. atomic write나 volatile write가 pending인 파일에는 verity를 활성화할 수 없습니다.

btrfs는 Linux 5.15부터 지원합니다. verity inode에는 RO_COMPAT inode flag를 표시하고 metadata는 별도 btree item에 저장합니다.

CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on
any of these filesystems.

``include/linux/fsverity.h`` declares the interface between the
``fs/verity/`` support layer and filesystems.  Briefly, filesystems
must provide an ``fsverity_operations`` structure that provides
methods to read and write the verity metadata to a filesystem-specific
location, including the Merkle tree blocks and
``fsverity_descriptor``.  Filesystems must also call functions in
``fs/verity/`` at certain times, such as when a file is opened or when
pages have been read into the pagecache.  (See `Verifying data`_.)

ext4
----

ext4 supports fs-verity since Linux v5.4 and e2fsprogs v1.45.2.

To create verity files on an ext4 filesystem, the filesystem must have
been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
it.  "verity" is an RO_COMPAT filesystem feature, so once set, old
kernels will only be able to mount the filesystem readonly, and old
versions of e2fsck will be unable to check the filesystem.

Originally, an ext4 filesystem with the "verity" feature could only be
mounted when its block size was equal to the system page size
(typically 4096 bytes).  In Linux v6.3, this limitation was removed.

ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files.  It
can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared.

ext4 also supports encryption, which can be used simultaneously with
fs-verity.  In this case, the plaintext data is verified rather than
the ciphertext.  This is necessary in order to make the fs-verity file
digest meaningful, since every file is encrypted differently.

ext4 stores the verity metadata (Merkle tree and fsverity_descriptor)
past the end of the file, starting at the first 64K boundary beyond
i_size.  This approach works because (a) verity files are readonly,
and (b) pages fully beyond i_size aren't visible to userspace but can
be read/written internally by ext4 with only some relatively small
changes to ext4.  This approach avoids having to depend on the
EA_INODE feature and on rearchitecturing ext4's xattr support to
support paging multi-gigabyte xattrs into memory, and to support
encrypting xattrs.  Note that the verity metadata *must* be encrypted
when the file is, since it contains hashes of the plaintext data.

ext4 only allows verity on extent-based files.

f2fs
----

f2fs supports fs-verity since Linux v5.4 and f2fs-tools v1.11.0.

To create verity files on an f2fs filesystem, the filesystem must have
been formatted with ``-O verity``.

f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
It can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be
cleared.

Like ext4, f2fs stores the verity metadata (Merkle tree and
fsverity_descriptor) past the end of the file, starting at the first
64K boundary beyond i_size.  See explanation for ext4 above.
Moreover, f2fs supports at most 4096 bytes of xattr entries per inode
which usually wouldn't be enough for even a single Merkle tree block.

f2fs doesn't support enabling verity on files that currently have
atomic or volatile writes pending.

btrfs
-----

btrfs supports fs-verity since Linux v5.15.  Verity-enabled inodes are
marked with a RO_COMPAT inode flag, and the verity metadata is stored
in separate btree items.

Implementation details
======================

Pagecache·bio 검증 구현과 사용자 공간 도구

fs-verity는 `mmap()`, `read()`, `pread()` 등 syscall 종류와 최초·후속 읽기를 가리지 않고 verity file의 모든 data read를 검증합니다. 이미 검증되어 cache된 data를 그대로 반환하는 경우만 재검증이 필요하지 않습니다.

Linux pagecache를 쓰는 파일시스템은 `->read_folio()`와 `->readahead()`가 folio를 Uptodate로 표시하기 전에 검증하도록 수정해야 합니다. memory map은 `->read_iter()`를 쓰지 않으므로 여기에만 hook하는 것은 불충분합니다.

`fsverity_verify_blocks()`는 verity inode의 pagecache로 읽은 data를 검증합니다. 호출할 때 folio는 여전히 lock된 상태이고 Uptodate가 아니어야 하므로 사용자 공간이 읽을 수 없습니다. 필요한 tree hash block은 `fsverity_operations::read_merkle_tree_page()` callback으로 파일시스템에서 읽습니다.

검증 실패 시 `fsverity_verify_blocks()`는 false를 반환하고 파일시스템은 folio를 Uptodate로 표시하면 안 됩니다. 이후 일반 pagecache 동작에 따라 해당 부분의 `read()`는 `EIO`, memory map 접근은 `SIGBUS`가 됩니다.

원칙적으로 data block 하나를 검증하려면 그 block에서 root hash까지 전체 경로를 확인해야 합니다. 효율을 위해 이미 검증된 hash block을 cache할 수 있으므로 함수는 tree를 올라가다 검증된 block을 만나면 그 block까지만 경로를 확인합니다.

dm-verity도 쓰는 이 최적화는 순차 읽기 성능이 매우 좋습니다. 4K block과 SHA-256에서는 보통 128번 중 127번 아래 level hash block이 직전 data block 읽기에서 이미 cache·검증되어 있습니다. 반면 random read는 더 느립니다.

ext4와 f2fs 같은 block device 기반 파일시스템도 pagecache 규칙을 적용하지만 여러 data block을 `bio` 하나로 묶어 읽습니다. `fsverity_verify_bio()`는 bio 안 모든 data block을 검증하도록 제공됩니다.

verity file이 암호화도 됐다면 검증 전에 복호화해야 합니다. ext4와 f2fs는 각 bio에 `bio_post_read_ctx`를 할당해 `->bi_private`에 저장합니다. `enabled_steps` bitmask는 decryption, verity 또는 둘 다 필요한지 표시합니다.

struct bio_post_read_ctx {
        struct bio *bio;
        struct work_struct work;
        unsigned int cur_step;
        unsigned int enabled_steps;
};

bio 완료 뒤 필요한 각 postprocessing step에 대해 context를 workqueue에 넣고 work가 복호화 또는 검증을 수행합니다. 오류가 없는 folio만 Uptodate로 표시한 뒤 unlock합니다.

파일 hole은 일반 `->readahead()`가 bio 없이 0으로 채우고 Uptodate로 처리할 수 있습니다. 이 경로가 검증을 우회하지 않도록 hole block도 `fsverity_verify_blocks()`로 검증합니다. direct I/O 역시 우회 가능성이 있어 verity file에서 비활성화합니다.

커널 외 사용자 공간 도구는 `https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git`에 있습니다. 보호 파일 구성 예시는 그 source tree의 `README.md`를 참고합니다.

Verifying data
--------------

fs-verity ensures that all reads of a verity file's data are verified,
regardless of which syscall is used to do the read (e.g. mmap(),
read(), pread()) and regardless of whether it's the first read or a
later read (unless the later read can return cached data that was
already verified).  Below, we describe how filesystems implement this.

Pagecache
~~~~~~~~~

For filesystems using Linux's pagecache, the ``->read_folio()`` and
``->readahead()`` methods must be modified to verify folios before
they are marked Uptodate.  Merely hooking ``->read_iter()`` would be
insufficient, since ``->read_iter()`` is not used for memory maps.

Therefore, fs/verity/ provides the function fsverity_verify_blocks()
which verifies data that has been read into the pagecache of a verity
inode.  The containing folio must still be locked and not Uptodate, so
it's not yet readable by userspace.  As needed to do the verification,
fsverity_verify_blocks() will call back into the filesystem to read
hash blocks via fsverity_operations::read_merkle_tree_page().

fsverity_verify_blocks() returns false if verification failed; in this
case, the filesystem must not set the folio Uptodate.  Following this,
as per the usual Linux pagecache behavior, attempts by userspace to
read() from the part of the file containing the folio will fail with
EIO, and accesses to the folio within a memory map will raise SIGBUS.

In principle, verifying a data block requires verifying the entire
path in the Merkle tree from the data block to the root hash.
However, for efficiency the filesystem may cache the hash blocks.
Therefore, fsverity_verify_blocks() only ascends the tree reading hash
blocks until an already-verified hash block is seen.  It then verifies
the path to that block.

This optimization, which is also used by dm-verity, results in
excellent sequential read performance.  This is because usually (e.g.
127 in 128 times for 4K blocks and SHA-256) the hash block from the
bottom level of the tree will already be cached and checked from
reading a previous data block.  However, random reads perform worse.

Block device based filesystems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Block device based filesystems (e.g. ext4 and f2fs) in Linux also use
the pagecache, so the above subsection applies too.  However, they
also usually read many data blocks from a file at once, grouped into a
structure called a "bio".  To make it easier for these types of
filesystems to support fs-verity, fs/verity/ also provides a function
fsverity_verify_bio() which verifies all data blocks in a bio.

ext4 and f2fs also support encryption.  If a verity file is also
encrypted, the data must be decrypted before being verified.  To
support this, these filesystems allocate a "post-read context" for
each bio and store it in ``->bi_private``::

    struct bio_post_read_ctx {
           struct bio *bio;
           struct work_struct work;
           unsigned int cur_step;
           unsigned int enabled_steps;
    };

``enabled_steps`` is a bitmask that specifies whether decryption,
verity, or both is enabled.  After the bio completes, for each needed
postprocessing step the filesystem enqueues the bio_post_read_ctx on a
workqueue, and then the workqueue work does the decryption or
verification.  Finally, folios where no decryption or verity error
occurred are marked Uptodate, and the folios are unlocked.

On many filesystems, files can contain holes.  Normally,
``->readahead()`` simply zeroes hole blocks and considers the
corresponding data to be up-to-date; no bios are issued.  To prevent
this case from bypassing fs-verity, filesystems use
fsverity_verify_blocks() to verify hole blocks.

Filesystems also disable direct I/O on verity files, since otherwise
direct I/O would bypass fs-verity.

Userspace utility
=================

This document focuses on the kernel, but a userspace utility for
fs-verity can be found at:

        https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git

See the README.md file in the fsverity-utils source tree for details,
including examples of setting up fs-verity protected files.

Tests
=====

xfstests와 설계 FAQ

fs-verity는 xfstests의 `verity` group으로 검증합니다. kvm-xfstests 예시는 다음과 같으며 ext4, f2fs, btrfs에서 실패가 없어야 합니다.

kvm-xfstests -c ext4,f2fs,btrfs -g verity

fs-verity와 IMA의 초점은 다릅니다. fs-verity는 Merkle tree로 개별 파일을 hash하는 filesystem mechanism이고, IMA는 어떤 파일을 hash하고 결과를 기록·인증·measurement list에 추가할지 정하는 system-wide policy입니다. IMA는 성능과 보안 이점을 위해 fs-verity hash를 전체 file hash 대신 사용할 수 있지만 모든 fs-verity 용도를 IMA로 강제할 이유는 없습니다. 독립 기능으로도 많은 요구를 충족하고 xfstests로 검사할 수 있습니다.

공격자가 disk의 Merkle tree hash를 바꿀 수 있다는 이유로 무용하지 않습니다. 진본성을 확인하려면 tree root hash가 들어간 fs-verity file digest 자체를 인증해야 합니다. verity file을 비verity file로 바꾸는 공격도 신뢰 사용자 공간이 활성화와 digest를 인증하고 비verity 파일을 신뢰하지 않으면 차단됩니다.

root hash만 disk에 저장하고 tree를 저장하지 않으면 한 byte만 처음 읽어도 전체 tree를 계산해야 합니다. leaf를 검증하려면 root node를 포함한 root까지 전체 경로가 필요한데 root node가 없으면 children을 hash하고 다시 그 children을 계산하는 식으로 결국 전체 파일을 hash하게 됩니다. 이 경우 단순 `sha256(file)`이 더 쉽고 조금 더 빠릅니다.

메모리 tree는 매 읽기 검증 이점은 남지만 큰 tree 전체를 pin할 수 없습니다. hash page가 퇴거될 때마다 그 아래 tree 전체를 다시 hash해야 해 block 하나 읽기가 수 GiB 재hash를 유발할 수 있으므로 Merkle tree 목적을 대부분 잃습니다.

leaf node만 저장하는 것도 한 level 위로 문제를 옮길 뿐입니다. data block을 leaf로 볼 수도 있습니다. SHA-256·4K 설정에서 각 level은 아래보다 1% 미만이므로 leaf level만 저장해도 tree의 99% 이상을 저장합니다. 전체 tree를 저장하는 편이 낫습니다.

package에 미리 만든 Merkle tree를 배포하는 기능은 현재 지원하지 않습니다. 초기 설계에는 있었지만 kernel UAPI 단순화와 낮은 우선순위 때문에 제거됐습니다. 파일은 보통 한 번 설치해 여러 번 쓰고 현대 CPU의 암호 hash는 비교적 빠릅니다.

write 지원은 완전히 다른 설계가 필요합니다. crash 뒤 data와 모든 hash level의 일관성을 유지해야 하므로 data journaling, copy-on-write, log-structured volume 같은 mechanism이 필요하지만 기존 파일시스템에 새 일관성 체계를 덧붙이기 어렵고 ext4 data journaling은 매우 느립니다.

매 write마다 Merkle tree를 다시 만들면 극도로 비효율적이고 authenticated skiplist 같은 다른 authenticated dictionary는 훨씬 복잡합니다. dm-verity는 read-only data와 read-only tree를 단순 검증하지만 dm-integrity는 write를 지원하는 대신 느리고 복잡하며 sector를 독립 인증해 root hash 기반 full-device authentication도 제공하지 않습니다. 서로 다른 문제를 한 target이나 fs-verity 하나에 합칠 이유가 없습니다.

verity file이 변경 불가능해도 `FS_IMMUTABLE_FL`을 재사용하지 않습니다. immutable bit는 내용 쓰기뿐 아니라 delete, rename, link, owner·mode 변경까지 막는데 fs-verity에는 이런 추가 제한이 필요하지 않습니다.

API가 `setxattr()`·`getxattr()`가 아니라 ioctl인 이유는 xattr interface를 임의 syscall처럼 사용하는 것이 Linux filesystem 개발자에게 강하게 권장되지 않기 때문입니다. xattr는 on-disk xattr여야지 Merkle tree 생성을 마술처럼 trigger하는 API가 아니어야 합니다.

현재 구현은 모두 local filesystem이지만 per-file verity metadata를 저장할 수 있다면 원칙적으로 remote filesystem도 지원할 수 있습니다. metadata 저장 선택지가 적다면 파일 끝 뒤에 저장하고 `i_size` 조작으로 사용자 공간에서 숨길 수 있습니다. `fs/verity/` 검증 함수는 Linux pagecache를 가정하지만 local과 remote 파일시스템 모두 보통 pagecache를 사용합니다.

모든 것을 VFS에만 구현하기 어려운 첫 이유는 검증 전에 folio를 Uptodate로 표시하면 안 되는데 현재 각 파일시스템의 `->readahead()`가 그 상태를 책임지기 때문입니다. VFS 단독 검증으로 바꾸려면 VFS와 모든 파일시스템을 크게 수정해야 합니다.

두 번째 이유는 파일시스템 독립 metadata 저장 방식이 마땅하지 않기 때문입니다. Merkle tree는 수 GiB일 수 있지만 많은 파일시스템은 모든 xattr가 4K block 하나에 맞는다고 가정합니다. ext4·f2fs 암호화는 xattr를 암호화하지 않지만 tree는 평문 data hash를 담으므로 파일과 함께 반드시 암호화해야 합니다.

별도 metadata file은 보호 대상 파일의 본질적 일부를 분리해 한쪽만 삭제되는 문제를 만들고, 같은 file에 넣으면 파일시스템의 `i_size`와 VFS `i_size`를 분리하지 않는 한 application을 깨뜨립니다. 이는 모든 파일시스템에 복잡한 변경이 필요합니다.

세 번째 이유는 `FS_IOC_ENABLE_VERITY`가 파일시스템 transaction을 사용해 활성화 완료 또는 변경 없음 중 하나만 남기는 것이 바람직하기 때문입니다. crash 뒤 intermediate state가 남으면 문제가 될 수 있습니다.

To test fs-verity, use xfstests.  For example, using `kvm-xfstests
<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::

    kvm-xfstests -c ext4,f2fs,btrfs -g verity

FAQ
===

This section answers frequently asked questions about fs-verity that
weren't already directly answered in other parts of this document.

:Q: Why isn't fs-verity part of IMA?
:A: fs-verity and IMA (Integrity Measurement Architecture) have
    different focuses.  fs-verity is a filesystem-level mechanism for
    hashing individual files using a Merkle tree.  In contrast, IMA
    specifies a system-wide policy that specifies which files are
    hashed and what to do with those hashes, such as log them,
    authenticate them, or add them to a measurement list.

    IMA supports the fs-verity hashing mechanism as an alternative
    to full file hashes, for those who want the performance and
    security benefits of the Merkle tree based hash.  However, it
    doesn't make sense to force all uses of fs-verity to be through
    IMA.  fs-verity already meets many users' needs even as a
    standalone filesystem feature, and it's testable like other
    filesystem features e.g. with xfstests.

:Q: Isn't fs-verity useless because the attacker can just modify the
    hashes in the Merkle tree, which is stored on-disk?
:A: To verify the authenticity of an fs-verity file you must verify
    the authenticity of the "fs-verity file digest", which
    incorporates the root hash of the Merkle tree.  See `Use cases`_.

:Q: Isn't fs-verity useless because the attacker can just replace a
    verity file with a non-verity one?
:A: See `Use cases`_.  In the initial use case, it's really trusted
    userspace code that authenticates the files; fs-verity is just a
    tool to do this job efficiently and securely.  The trusted
    userspace code will consider non-verity files to be inauthentic.

:Q: Why does the Merkle tree need to be stored on-disk?  Couldn't you
    store just the root hash?
:A: If the Merkle tree wasn't stored on-disk, then you'd have to
    compute the entire tree when the file is first accessed, even if
    just one byte is being read.  This is a fundamental consequence of
    how Merkle tree hashing works.  To verify a leaf node, you need to
    verify the whole path to the root hash, including the root node
    (the thing which the root hash is a hash of).  But if the root
    node isn't stored on-disk, you have to compute it by hashing its
    children, and so on until you've actually hashed the entire file.

    That defeats most of the point of doing a Merkle tree-based hash,
    since if you have to hash the whole file ahead of time anyway,
    then you could simply do sha256(file) instead.  That would be much
    simpler, and a bit faster too.

    It's true that an in-memory Merkle tree could still provide the
    advantage of verification on every read rather than just on the
    first read.  However, it would be inefficient because every time a
    hash page gets evicted (you can't pin the entire Merkle tree into
    memory, since it may be very large), in order to restore it you
    again need to hash everything below it in the tree.  This again
    defeats most of the point of doing a Merkle tree-based hash, since
    a single block read could trigger re-hashing gigabytes of data.

:Q: But couldn't you store just the leaf nodes and compute the rest?
:A: See previous answer; this really just moves up one level, since
    one could alternatively interpret the data blocks as being the
    leaf nodes of the Merkle tree.  It's true that the tree can be
    computed much faster if the leaf level is stored rather than just
    the data, but that's only because each level is less than 1% the
    size of the level below (assuming the recommended settings of
    SHA-256 and 4K blocks).  For the exact same reason, by storing
    "just the leaf nodes" you'd already be storing over 99% of the
    tree, so you might as well simply store the whole tree.

:Q: Can the Merkle tree be built ahead of time, e.g. distributed as
    part of a package that is installed to many computers?
:A: This isn't currently supported.  It was part of the original
    design, but was removed to simplify the kernel UAPI and because it
    wasn't a critical use case.  Files are usually installed once and
    used many times, and cryptographic hashing is somewhat fast on
    most modern processors.

:Q: Why doesn't fs-verity support writes?
:A: Write support would be very difficult and would require a
    completely different design, so it's well outside the scope of
    fs-verity.  Write support would require:

    - A way to maintain consistency between the data and hashes,
      including all levels of hashes, since corruption after a crash
      (especially of potentially the entire file!) is unacceptable.
      The main options for solving this are data journalling,
      copy-on-write, and log-structured volume.  But it's very hard to
      retrofit existing filesystems with new consistency mechanisms.
      Data journalling is available on ext4, but is very slow.

    - Rebuilding the Merkle tree after every write, which would be
      extremely inefficient.  Alternatively, a different authenticated
      dictionary structure such as an "authenticated skiplist" could
      be used.  However, this would be far more complex.

    Compare it to dm-verity vs. dm-integrity.  dm-verity is very
    simple: the kernel just verifies read-only data against a
    read-only Merkle tree.  In contrast, dm-integrity supports writes
    but is slow, is much more complex, and doesn't actually support
    full-device authentication since it authenticates each sector
    independently, i.e. there is no "root hash".  It doesn't really
    make sense for the same device-mapper target to support these two
    very different cases; the same applies to fs-verity.

:Q: Since verity files are immutable, why isn't the immutable bit set?
:A: The existing "immutable" bit (FS_IMMUTABLE_FL) already has a
    specific set of semantics which not only make the file contents
    read-only, but also prevent the file from being deleted, renamed,
    linked to, or having its owner or mode changed.  These extra
    properties are unwanted for fs-verity, so reusing the immutable
    bit isn't appropriate.

:Q: Why does the API use ioctls instead of setxattr() and getxattr()?
:A: Abusing the xattr interface for basically arbitrary syscalls is
    heavily frowned upon by most of the Linux filesystem developers.
    An xattr should really just be an xattr on-disk, not an API to
    e.g. magically trigger construction of a Merkle tree.

:Q: Does fs-verity support remote filesystems?
:A: So far all filesystems that have implemented fs-verity support are
    local filesystems, but in principle any filesystem that can store
    per-file verity metadata can support fs-verity, regardless of
    whether it's local or remote.  Some filesystems may have fewer
    options of where to store the verity metadata; one possibility is
    to store it past the end of the file and "hide" it from userspace
    by manipulating i_size.  The data verification functions provided
    by ``fs/verity/`` also assume that the filesystem uses the Linux
    pagecache, but both local and remote filesystems normally do so.

:Q: Why is anything filesystem-specific at all?  Shouldn't fs-verity
    be implemented entirely at the VFS level?
:A: There are many reasons why this is not possible or would be very
    difficult, including the following:

    - To prevent bypassing verification, folios must not be marked
      Uptodate until they've been verified.  Currently, each
      filesystem is responsible for marking folios Uptodate via
      ``->readahead()``.  Therefore, currently it's not possible for
      the VFS to do the verification on its own.  Changing this would
      require significant changes to the VFS and all filesystems.

    - It would require defining a filesystem-independent way to store
      the verity metadata.  Extended attributes don't work for this
      because (a) the Merkle tree may be gigabytes, but many
      filesystems assume that all xattrs fit into a single 4K
      filesystem block, and (b) ext4 and f2fs encryption doesn't
      encrypt xattrs, yet the Merkle tree *must* be encrypted when the
      file contents are, because it stores hashes of the plaintext
      file contents.

      So the verity metadata would have to be stored in an actual
      file.  Using a separate file would be very ugly, since the
      metadata is fundamentally part of the file to be protected, and
      it could cause problems where users could delete the real file
      but not the metadata file or vice versa.  On the other hand,
      having it be in the same file would break applications unless
      filesystems' notion of i_size were divorced from the VFS's,
      which would be complex and require changes to all filesystems.

    - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's
      transaction mechanism so that either the file ends up with
      verity enabled, or no changes were made.  Allowing intermediate
      states to occur after a crash may cause problems.