xref: /third_party/fsverity-utils/man/fsverity.1.md

% FSVERITY(1) fsverity-utils v1.5 | User Commands
%
% February 2022

# NAME

fsverity - userspace utility for fs-verity

# SYNOPSIS
**fsverity digest** [*OPTION*...] *FILE*... \
**fsverity dump_metadata** [*OPTION*...] *TYPE* *FILE* \
**fsverity enable** [*OPTION*...] *FILE* \
**fsverity measure** *FILE*... \
**fsverity sign** [*OPTION*...] *FILE* *OUT_SIGFILE*

# DESCRIPTION

**fsverity** is a userspace utility for fs-verity.  fs-verity is a Linux kernel
filesystem feature that does transparent on-demand verification of the contents
of read-only files using Merkle trees.

**fsverity** can enable fs-verity on files, retrieve the digests of fs-verity
files, and sign files for use with fs-verity (among other things).
**fsverity**'s functionality is divided among various subcommands.

This manual page focuses on documenting all **fsverity** subcommands and
options.  For examples and more information about the fs-verity kernel feature,
see the references at the end of this page.

# OPTIONS

**fsverity** always accepts the following options:

**\-\-help**
:   Show the help, for either one subcommand or for all subcommands.

**\-\-version**
:   Show the version of fsverity-utils.

# SUBCOMMANDS

## **fsverity digest** [*OPTION*...] *FILE*...

Compute the fs-verity digest of the given file(s).  This is mainly intended to
used in preparation for signing the digest.  In some cases **fsverity sign**
can be used instead to digest and sign the file in one step.

Options accepted by **fsverity digest**:

**\-\-block-size**=*BLOCK_SIZE*
:   The Merkle tree block size (in bytes) to use.  This must be a power of 2 and
    at least twice the size of the hash values.  However, note that currently
    (as of Linux kernel v5.13), the Linux kernel implementations of fs-verity
    only support the case where the Merkle tree block size is equal to the
    system page size, usually 4096 bytes.  The default value of this option is
    4096.

**\-\-compact**
:   When printing the file digest, only print the actual digest hex string;
    don't print the algorithm name and filename.

**\-\-for-builtin-sig**
:   Format the file digest in a way that is compatible with the Linux kernel's
    fs-verity built-in signature verification support.  This means formatting it
    as a `struct fsverity_formatted_digest`.  Use this option if you are using
    built-in signatures but are not using **fsverity sign** to do the signing.

**\-\-hash-alg**=*HASH_ALG*
:   The hash algorithm to use to build the Merkle tree.  Valid options are
    sha256 and sha512.  Default is sha256.

**\-\-out-merkle-tree**=*FILE*
:   Write the computed Merkle tree to the given file.  The Merkle tree layout
    will be the same as that used by the Linux kernel's
    `FS_IOC_READ_VERITY_METADATA` ioctl.

    Normally this option isn't useful, but it can be needed in cases where the
    fs-verity metadata needs to be consumed by something other than one of the
    native Linux kernel implementations of fs-verity.  This is not needed for
    file signing.

**\-\-out-descriptor**=*FILE*
:   Write the computed fs-verity descriptor to the given file.

    Normally this option isn't useful, but it can be needed in cases where the
    fs-verity metadata needs to be consumed by something other than one of the
    native Linux kernel implementations of fs-verity.  This is not needed for
    file signing.

**\-\-salt**=*SALT*
:   The salt to use in the Merkle tree, as a hex string.  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.  The default is no salt.

## **fsverity dump_metadata** [*OPTION*...] *TYPE* *FILE*

Dump the fs-verity metadata of the given file.  The file must have fs-verity
enabled, and the filesystem must support the `FS_IOC_READ_VERITY_METADATA` ioctl
(it was added in Linux v5.12).  This subcommand normally isn't useful, but it
can be useful in cases where a userspace server program is serving a verity file
to a client which implements fs-verity compatible verification.

*TYPE* may be "merkle\_tree", "descriptor", or "signature", indicating the type
of metadata to dump.  "signature" refers to the built-in signature, if present;
userspace-managed signatures will not be included.

Options accepted by **fsverity dump_metadata**:

**\-\-length**=*LENGTH*
:   Length in bytes to dump from the specified metadata item.  Only accepted in
    combination with **\-\-offset**.

**\-\-offset**=*offset*
:   Offset in bytes into the specified metadata item at which to start dumping.
    Only accepted in combination with **\-\-length**.

## **fsverity enable** [*OPTION*...] *FILE*

Enable fs-verity on the specified file.  This will only work if the filesystem
supports fs-verity.

Options accepted by **fsverity enable**:

**\-\-block-size**=*BLOCK_SIZE*
:   Same as for **fsverity digest**.

**\-\-hash-alg**=*HASH_ALG*
:   Same as for **fsverity digest**.

**\-\-salt**=*SALT*
:   Same as for **fsverity digest**.

**\-\-signature**=*SIGFILE*
:   Specifies the built-in signature to apply to the file.  *SIGFILE* must be a
    file that contains the signature in PKCS#7 DER format, e.g. as produced by
    the **fsverity sign** command.

    Note that this option is only needed if the Linux kernel's fs-verity
    built-in signature verification support is being used.  It is not needed if
    the signatures will be verified in userspace, as in that case the signatures
    should be stored separately.

## **fsverity measure** *FILE*...

Display the fs-verity digest of the given file(s).  The files must have
fs-verity enabled.  The output will be the same as **fsverity digest** with
the appropriate parameters, but **fsverity measure** will take constant time
for each file regardless of the size of the file.

**fsverity measure** does not accept any options.

## **fsverity sign** [*OPTION*...] *FILE* *OUT_SIGFILE*

Sign the given file for fs-verity, in a way that is compatible with the Linux
kernel's fs-verity built-in signature verification support.  The signature will
be written to *OUT_SIGFILE* in PKCS#7 DER format.

The private key can be specified either by key file or by PKCS#11 token.  To use
a key file, provide **\-\-key** and optionally **\-\-cert**.  To use a PKCS#11
token, provide **\-\-pkcs11-engine**, **\-\-pkcs11-module**, **\-\-cert**, and
optionally **\-\-pkcs11-keyid**.  PKCS#11 token support is unavailable when
fsverity-utils was built with BoringSSL rather than OpenSSL.

**fsverity sign** should only be used if you need compatibility with fs-verity
built-in signatures.  It is not the only way to do signatures with fs-verity.
For more information, see the fsverity-utils README.

Options accepted by **fsverity sign**:

**\-\-block-size**=*BLOCK_SIZE*
:   Same as for **fsverity digest**.

**\-\-cert**=*CERTFILE*
:   Specifies the file that contains the certificate, in PEM format.  This
    option is required if *KEYFILE* contains only the private key and not also
    the certificate, or if a PKCS#11 token is used.

**\-\-hash-alg**=*HASH_ALG*
:   Same as for **fsverity digest**.

**\-\-key**=*KEYFILE*
:   Specifies the file that contains the private key, in PEM format.  This
    option is required when not using a PKCS#11 token.

**\-\-out-descriptor**=*FILE*
:   Same as for **fsverity digest**.

**\-\-out-merkle-tree**=*FILE*
:   Same as for **fsverity digest**.

**\-\-pkcs11-engine**=*SOFILE*
:   Specifies the path to the OpenSSL PKCS#11 engine file.  This typically will
    be a path to the libp11 .so file.  This option is required when using a
    PKCS#11 token.

**\-\-pkcs11-keyid**=*KEYID*
:   Specifies the key identifier in the form of a PKCS#11 URI.  If not provided,
    the default key associated with the token is used.  This option is only
    applicable when using a PKCS#11 token.

**\-\-pkcs11-module**=*SOFILE*
:   Specifies the path to the PKCS#11 token-specific module library.  This
    option is required when using a PKCS#11 token.

**\-\-salt**=*SALT*
:   Same as for **fsverity digest**.

# SEE ALSO

For example commands and more information, see the
[README file for
fsverity-utils](https://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/fsverity-utils.git/tree/README.md).

Also see the [kernel documentation for
fs-verity](https://www.kernel.org/doc/html/latest/filesystems/fsverity.html).