| .\" SPDX-License-Identifier: MIT |
| .\" |
| .\" Copyright 2021 Google LLC |
| .\" |
| .\" Use of this source code is governed by an MIT-style license that can be |
| .\" found in the LICENSE file or at https://opensource.org/licenses/MIT. |
| .\" |
| .TH "FSVERITY" "1" "March 2024" "fsverity-utils v1.6" "User Commands" |
| .hy |
| . |
| .SH NAME |
| .PP |
| fsverity - userspace utility for fs-verity |
| . |
| . |
| .SH SYNOPSIS |
| .PP |
| \f[B]fsverity digest\f[R] [\f[I]OPTION\f[R]\&...] |
| \f[I]FILE\f[R]\&... |
| .PD 0 |
| .P |
| .PD |
| \f[B]fsverity dump_metadata\f[R] [\f[I]OPTION\f[R]\&...] |
| \f[I]TYPE\f[R] \f[I]FILE\f[R] |
| .PD 0 |
| .P |
| .PD |
| \f[B]fsverity enable\f[R] [\f[I]OPTION\f[R]\&...] |
| \f[I]FILE\f[R] |
| .PD 0 |
| .P |
| .PD |
| \f[B]fsverity measure\f[R] \f[I]FILE\f[R]\&... |
| .PD 0 |
| .P |
| .PD |
| \f[B]fsverity sign\f[R] [\f[I]OPTION\f[R]\&...] |
| \f[I]FILE\f[R] \f[I]OUT_SIGFILE\f[R] |
| . |
| . |
| .SH DESCRIPTION |
| .PP |
| \f[B]fsverity\f[R] 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. |
| .PP |
| \f[B]fsverity\f[R] can enable fs-verity on files, retrieve the digests of |
| fs-verity files, and sign files for use with fs-verity (among other things). |
| \f[B]fsverity\f[R]\[cq]s functionality is divided among various subcommands. |
| .PP |
| This manual page focuses on documenting all \f[B]fsverity\f[R] subcommands and |
| options. |
| For examples and more information about the fs-verity kernel feature, see the |
| references at the end of this page. |
| . |
| . |
| .SH OPTIONS |
| .PP |
| \f[B]fsverity\f[R] always accepts the following options: |
| .TP |
| \f[B]--help\f[R] |
| Show the help, for either one subcommand or for all subcommands. |
| .TP |
| \f[B]--version\f[R] |
| Show the version of fsverity-utils. |
| . |
| . |
| .SH SUBCOMMANDS |
| . |
| .SS \f[B]fsverity digest\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R]\&... |
| .PP |
| 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 \f[B]fsverity sign\f[R] can be used instead to digest and sign the |
| file in one step. |
| .PP |
| Options accepted by \f[B]fsverity digest\f[R]: |
| .TP |
| \f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R] |
| 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. |
| .RS |
| .PP |
| Note that the Linux kernel implementations of fs-verity place further |
| restrictions on the Merkle tree block size. |
| Linux v6.2 and earlier require that the Merkle tree block size be equal to both |
| the system page size and the filesystem block size. |
| These values are often 4096. |
| Linux v6.3 and later are more flexible; they require that the Merkle tree block |
| size be a power of 2 that is greater than or equal to 1024 and less than or |
| equal to the system page size and the filesystem block size. |
| The default value of this option is 4096. |
| .RE |
| .TP |
| \f[B]--compact\f[R] |
| When printing the file digest, only print the actual digest hex string; |
| don\[cq]t print the algorithm name and filename. |
| .TP |
| \f[B]--for-builtin-sig\f[R] |
| Format the file digest in a way that is compatible with the Linux kernel\[cq]s |
| fs-verity built-in signature verification support. |
| This means formatting it as a \f[B]struct fsverity_formatted_digest\f[R]. |
| Use this option if you are using built-in signatures but are not using |
| \f[B]fsverity sign\f[R] to do the signing. |
| .TP |
| \f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R] |
| The hash algorithm to use to build the Merkle tree. |
| Valid options are sha256 and sha512. |
| Default is sha256. |
| .TP |
| \f[B]--out-merkle-tree\f[R]=\f[I]FILE\f[R] |
| Write the computed Merkle tree to the given file. |
| The Merkle tree layout will be the same as that used by the Linux kernel\[cq]s |
| \f[B]FS_IOC_READ_VERITY_METADATA\f[R] ioctl. |
| .RS |
| .PP |
| Normally this option isn\[cq]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. |
| .RE |
| .TP |
| \f[B]--out-descriptor\f[R]=\f[I]FILE\f[R] |
| Write the computed fs-verity descriptor to the given file. |
| .RS |
| .PP |
| Normally this option isn\[cq]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. |
| .RE |
| .TP |
| \f[B]--salt\f[R]=\f[I]SALT\f[R] |
| 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. |
| . |
| .SS \f[B]fsverity dump_metadata\f[R] [\f[I]OPTION\f[R]\&...] \f[I]TYPE\f[R] \f[I]FILE\f[R] |
| .PP |
| Dump the fs-verity metadata of the given file. |
| The file must have fs-verity enabled, and the filesystem must support the |
| \f[B]FS_IOC_READ_VERITY_METADATA\f[R] ioctl (it was added in Linux v5.12). |
| This subcommand normally isn\[cq]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. |
| .PP |
| \f[I]TYPE\f[R] may be \[lq]merkle_tree\[rq], \[lq]descriptor\[rq], or |
| \[lq]signature\[rq], indicating the type of metadata to dump. |
| \[lq]signature\[rq] refers to the built-in signature, if present; |
| userspace-managed signatures will not be included. |
| .PP |
| Options accepted by \f[B]fsverity dump_metadata\f[R]: |
| .TP |
| \f[B]--length\f[R]=\f[I]LENGTH\f[R] |
| Length in bytes to dump from the specified metadata item. |
| Only accepted in combination with \f[B]--offset\f[R]. |
| .TP |
| \f[B]--offset\f[R]=\f[I]offset\f[R] |
| Offset in bytes into the specified metadata item at which to start dumping. |
| Only accepted in combination with \f[B]--length\f[R]. |
| . |
| .SS \f[B]fsverity enable\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R] |
| .PP |
| Enable fs-verity on the specified file. |
| This will only work if the filesystem supports fs-verity. |
| .PP |
| Options accepted by \f[B]fsverity enable\f[R]: |
| .TP |
| \f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R] |
| Same as for \f[B]fsverity digest\f[R]. |
| .TP |
| \f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R] |
| Same as for \f[B]fsverity digest\f[R]. |
| .TP |
| \f[B]--salt\f[R]=\f[I]SALT\f[R] |
| Same as for \f[B]fsverity digest\f[R]. |
| .TP |
| \f[B]--signature\f[R]=\f[I]SIGFILE\f[R] |
| Specifies the built-in signature to apply to the file. |
| \f[I]SIGFILE\f[R] must be a file that contains the signature in PKCS#7 DER |
| format, e.g.\ as produced by the \f[B]fsverity sign\f[R] command. |
| .RS |
| .PP |
| Note that this option is only needed if the Linux kernel\[cq]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. |
| .RE |
| . |
| .SS \f[B]fsverity measure\f[R] \f[I]FILE\f[R]\&... |
| .PP |
| Display the fs-verity digest of the given file(s). |
| The files must have fs-verity enabled. |
| The output will be the same as \f[B]fsverity digest\f[R] with the appropriate |
| parameters, but \f[B]fsverity measure\f[R] will take constant time for each file |
| regardless of the size of the file. |
| .PP |
| \f[B]fsverity measure\f[R] does not accept any options. |
| . |
| .SS \f[B]fsverity sign\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R] \f[I]OUT_SIGFILE\f[R] |
| .PP |
| Sign the given file for fs-verity, in a way that is compatible with the Linux |
| kernel\[cq]s fs-verity built-in signature verification support. |
| The signature will be written to \f[I]OUT_SIGFILE\f[R] in PKCS#7 DER format. |
| .PP |
| The private key can be specified either by key file or by PKCS#11 token. |
| To use a key file, provide \f[B]--key\f[R] and optionally \f[B]--cert\f[R]. |
| To use a PKCS#11 token, provide \f[B]--pkcs11-engine\f[R], |
| \f[B]--pkcs11-module\f[R], \f[B]--cert\f[R], and optionally |
| \f[B]--pkcs11-keyid\f[R]. |
| PKCS#11 token support is unavailable when fsverity-utils was built with |
| BoringSSL rather than OpenSSL. |
| .PP |
| \f[B]fsverity sign\f[R] 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. |
| .PP |
| Options accepted by \f[B]fsverity sign\f[R]: |
| .TP |
| \f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R] |
| Same as for \f[B]fsverity digest\f[R]. |
| .TP |
| \f[B]--cert\f[R]=\f[I]CERTFILE\f[R] |
| Specifies the file that contains the certificate, in PEM format. |
| This option is required if \f[I]KEYFILE\f[R] contains only the private key and |
| not also the certificate, or if a PKCS#11 token is used. |
| .TP |
| \f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R] |
| Same as for \f[B]fsverity digest\f[R]. |
| .TP |
| \f[B]--key\f[R]=\f[I]KEYFILE\f[R] |
| Specifies the file that contains the private key, in PEM format. |
| This option is required when not using a PKCS#11 token. |
| .TP |
| \f[B]--out-descriptor\f[R]=\f[I]FILE\f[R] |
| Same as for \f[B]fsverity digest\f[R]. |
| .TP |
| \f[B]--out-merkle-tree\f[R]=\f[I]FILE\f[R] |
| Same as for \f[B]fsverity digest\f[R]. |
| .TP |
| \f[B]--pkcs11-engine\f[R]=\f[I]SOFILE\f[R] |
| 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. |
| .TP |
| \f[B]--pkcs11-keyid\f[R]=\f[I]KEYID\f[R] |
| 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. |
| .TP |
| \f[B]--pkcs11-module\f[R]=\f[I]SOFILE\f[R] |
| Specifies the path to the PKCS#11 token-specific module library. |
| This option is required when using a PKCS#11 token. |
| .TP |
| \f[B]--salt\f[R]=\f[I]SALT\f[R] |
| Same as for \f[B]fsverity digest\f[R]. |
| . |
| . |
| .SH SEE ALSO |
| .PP |
| For example commands and more information, see the README file for |
| fsverity-utils (https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git/tree/README.md). |
| .PP |
| Also see the kernel documentation for |
| fs-verity (https://www.kernel.org/doc/html/latest/filesystems/fsverity.html). |