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