commit	4e27dad12a2755ec69533e66ca990d5ceb9930ef	[log] [tgz]
author	Eric Biggers <ebiggers@google.com>	Fri Sep 25 06:00:29 2020 +0000
committer	Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>	Fri Sep 25 06:00:29 2020 +0000
tree	60c35761c7415e5dc429e0345f0379ee4d9f8d7b
parent	82f8a3977ed0da76ee52536bb4cab8726b20e20a [diff]
parent	70e71eff016c6eba51736264c4fc37e2864b7806 [diff]

tree: 60c35761c7415e5dc429e0345f0379ee4d9f8d7b

README.md

fsverity-utils

Introduction

This is fsverity-utils, a set of userspace utilities for fs-verity. fs-verity is a Linux kernel feature that does transparent on-demand integrity/authenticity verification of the contents of read-only files, using a hidden Merkle tree (hash tree) associated with the file. It is similar to dm-verity, but implemented at the file level rather than at the block device level. See the kernel documentation for more information about fs-verity.

fs-verity is supported by the ext4 and f2fs filesystems in Linux v5.4 and later when configured with CONFIG_FS_VERITY=y and when the verity filesystem feature flag has been enabled. Other filesystems might add support for fs-verity in the future.

fsverity-utils currently contains just one program, fsverity. The fsverity program allows you to set up fs-verity protected files. In addition, the file measurement computation and signing functionality of fsverity is optionally exposed through a C library libfsverity. See libfsverity.h for the API of this library.

Building and installing

fsverity-utils uses the OpenSSL library, so you first must install the needed development files. For example, on Debian-based systems, run:

    sudo apt-get install libssl-dev

OpenSSL must be version 1.0.0 or later.

Then, to build and install fsverity-utils:

    make
    sudo make install

By default, the following targets are built and installed: the program fsverity, the static library libfsverity.a, and the shared library libfsverity.so. You can also run make check to build and run the tests, or make help to display all available build targets.

By default, fsverity is statically linked to libfsverity. You can use make USE_SHARED_LIB=1 to use dynamic linking instead.

See the Makefile for other supported build and installation options.

Examples

Basic use

    mkfs.ext4 -O verity /dev/vdc
    mount /dev/vdc /vdc
    cd /vdc

    # Create a test file
    head -c 1000000 /dev/urandom > file
    sha256sum file

    # Enable verity on the file
    fsverity enable file

    # Show the verity file measurement
    fsverity measure file

    # File should still be readable as usual.  However, all data read
    # is now transparently checked against a hidden Merkle tree, whose
    # root hash is incorporated into the verity file measurement.
    # Reads of any corrupted parts of the data will fail.
    sha256sum file

Note that in the above example, the file isn't signed. Therefore, to get any authenticity protection (as opposed to just integrity protection), the output of fsverity measure needs to be compared against a trusted value.

Using builtin signatures

With CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y, the filesystem supports automatically verifying a signed file measurement that has been included in the verity metadata. The signature is verified against the set of X.509 certificates that have been loaded into the ".fs-verity" kernel keyring. Here's an example:

    # Generate a new certificate and private key:
    openssl req -newkey rsa:4096 -nodes -keyout key.pem -x509 -out cert.pem

    # Convert the certificate from PEM to DER format:
    openssl x509 -in cert.pem -out cert.der -outform der

    # Load the certificate into the fs-verity keyring:
    keyctl padd asymmetric '' %keyring:.fs-verity < cert.der

    # Optionally, lock the keyring so that no more keys can be added
    # (requires keyctl v1.5.11 or later):
    keyctl restrict_keyring %keyring:.fs-verity

    # Optionally, require that all verity files be signed:
    sysctl fs.verity.require_signatures=1

    # Now set up fs-verity on a test file:
    sha256sum file
    fsverity sign file file.sig --key=key.pem --cert=cert.pem
    fsverity enable file --signature=file.sig
    rm -f file.sig
    sha256sum file

By default, it's not required that verity files have a signature. This can be changed with sysctl fs.verity.require_signatures=1. When set, it's guaranteed that the contents of every verity file has been signed by one of the certificates in the keyring.

Note: applications generally still need to check whether the file they're accessing really is a verity file, since an attacker could replace a verity file with a regular one.

With IMA

IMA support for fs-verity is planned.

Notices

fsverity-utils is provided under the terms of the MIT license. A copy of this license can be found in the file named LICENSE.

Send questions and bug reports to linux-fscrypt@vger.kernel.org.

Signed release tarballs for fsverity-utils can be found on kernel.org.

Contributing

Send patches to linux-fscrypt@vger.kernel.org with the additional tag fsverity-utils in the subject, i.e. [fsverity-utils PATCH]. Patches should follow the Linux kernel's coding style. A .clang-format file is provided to approximate this coding style; consider using git clang-format. Additionally, like the Linux kernel itself, patches require the following "sign-off" procedure:

The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below:

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

    (a) The contribution was created in whole or in part by me and I
        have the right to submit it under the open source license
        indicated in the file; or

    (b) The contribution is based upon previous work that, to the best
        of my knowledge, is covered under an appropriate open source
        license and I have the right under that license to submit that
        work with modifications, whether created in whole or in part
        by me, under the same open source license (unless I am
        permitted to submit under a different license), as indicated
        in the file; or

    (c) The contribution was provided directly to me by some other
        person who certified (a), (b) or (c) and I have not modified
        it.

    (d) I understand and agree that this project and the contribution
        are public and that a record of the contribution (including all
        personal information I submit with it, including my sign-off) is
        maintained indefinitely and may be redistributed consistent with
        this project or the open source license(s) involved.

then you just add a line saying::

Signed-off-by: Random J Developer <random@developer.example.org>

using your real name (sorry, no pseudonyms or anonymous contributions.)