1% FSVERITY(1) fsverity-utils v1.5 | User Commands 2% 3% February 2022 4 5# NAME 6 7fsverity - userspace utility for fs-verity 8 9# SYNOPSIS 10**fsverity digest** [*OPTION*...] *FILE*... \ 11**fsverity dump_metadata** [*OPTION*...] *TYPE* *FILE* \ 12**fsverity enable** [*OPTION*...] *FILE* \ 13**fsverity measure** *FILE*... \ 14**fsverity sign** [*OPTION*...] *FILE* *OUT_SIGFILE* 15 16# DESCRIPTION 17 18**fsverity** is a userspace utility for fs-verity. fs-verity is a Linux kernel 19filesystem feature that does transparent on-demand verification of the contents 20of read-only files using Merkle trees. 21 22**fsverity** can enable fs-verity on files, retrieve the digests of fs-verity 23files, and sign files for use with fs-verity (among other things). 24**fsverity**'s functionality is divided among various subcommands. 25 26This manual page focuses on documenting all **fsverity** subcommands and 27options. For examples and more information about the fs-verity kernel feature, 28see the references at the end of this page. 29 30# OPTIONS 31 32**fsverity** always accepts the following options: 33 34**\-\-help** 35: Show the help, for either one subcommand or for all subcommands. 36 37**\-\-version** 38: Show the version of fsverity-utils. 39 40# SUBCOMMANDS 41 42## **fsverity digest** [*OPTION*...] *FILE*... 43 44Compute the fs-verity digest of the given file(s). This is mainly intended to 45used in preparation for signing the digest. In some cases **fsverity sign** 46can be used instead to digest and sign the file in one step. 47 48Options accepted by **fsverity digest**: 49 50**\-\-block-size**=*BLOCK_SIZE* 51: The Merkle tree block size (in bytes) to use. This must be a power of 2 and 52 at least twice the size of the hash values. However, note that currently 53 (as of Linux kernel v5.13), the Linux kernel implementations of fs-verity 54 only support the case where the Merkle tree block size is equal to the 55 system page size, usually 4096 bytes. The default value of this option is 56 4096. 57 58**\-\-compact** 59: When printing the file digest, only print the actual digest hex string; 60 don't print the algorithm name and filename. 61 62**\-\-for-builtin-sig** 63: Format the file digest in a way that is compatible with the Linux kernel's 64 fs-verity built-in signature verification support. This means formatting it 65 as a `struct fsverity_formatted_digest`. Use this option if you are using 66 built-in signatures but are not using **fsverity sign** to do the signing. 67 68**\-\-hash-alg**=*HASH_ALG* 69: The hash algorithm to use to build the Merkle tree. Valid options are 70 sha256 and sha512. Default is sha256. 71 72**\-\-out-merkle-tree**=*FILE* 73: Write the computed Merkle tree to the given file. The Merkle tree layout 74 will be the same as that used by the Linux kernel's 75 `FS_IOC_READ_VERITY_METADATA` ioctl. 76 77 Normally this option isn't useful, but it can be needed in cases where the 78 fs-verity metadata needs to be consumed by something other than one of the 79 native Linux kernel implementations of fs-verity. This is not needed for 80 file signing. 81 82**\-\-out-descriptor**=*FILE* 83: Write the computed fs-verity descriptor to the given file. 84 85 Normally this option isn't useful, but it can be needed in cases where the 86 fs-verity metadata needs to be consumed by something other than one of the 87 native Linux kernel implementations of fs-verity. This is not needed for 88 file signing. 89 90**\-\-salt**=*SALT* 91: The salt to use in the Merkle tree, as a hex string. The salt is a value 92 that is prepended to every hashed block; it can be used to personalize the 93 hashing for a particular file or device. The default is no salt. 94 95## **fsverity dump_metadata** [*OPTION*...] *TYPE* *FILE* 96 97Dump the fs-verity metadata of the given file. The file must have fs-verity 98enabled, and the filesystem must support the `FS_IOC_READ_VERITY_METADATA` ioctl 99(it was added in Linux v5.12). This subcommand normally isn't useful, but it 100can be useful in cases where a userspace server program is serving a verity file 101to a client which implements fs-verity compatible verification. 102 103*TYPE* may be "merkle\_tree", "descriptor", or "signature", indicating the type 104of metadata to dump. "signature" refers to the built-in signature, if present; 105userspace-managed signatures will not be included. 106 107Options accepted by **fsverity dump_metadata**: 108 109**\-\-length**=*LENGTH* 110: Length in bytes to dump from the specified metadata item. Only accepted in 111 combination with **\-\-offset**. 112 113**\-\-offset**=*offset* 114: Offset in bytes into the specified metadata item at which to start dumping. 115 Only accepted in combination with **\-\-length**. 116 117## **fsverity enable** [*OPTION*...] *FILE* 118 119Enable fs-verity on the specified file. This will only work if the filesystem 120supports fs-verity. 121 122Options accepted by **fsverity enable**: 123 124**\-\-block-size**=*BLOCK_SIZE* 125: Same as for **fsverity digest**. 126 127**\-\-hash-alg**=*HASH_ALG* 128: Same as for **fsverity digest**. 129 130**\-\-salt**=*SALT* 131: Same as for **fsverity digest**. 132 133**\-\-signature**=*SIGFILE* 134: Specifies the built-in signature to apply to the file. *SIGFILE* must be a 135 file that contains the signature in PKCS#7 DER format, e.g. as produced by 136 the **fsverity sign** command. 137 138 Note that this option is only needed if the Linux kernel's fs-verity 139 built-in signature verification support is being used. It is not needed if 140 the signatures will be verified in userspace, as in that case the signatures 141 should be stored separately. 142 143## **fsverity measure** *FILE*... 144 145Display the fs-verity digest of the given file(s). The files must have 146fs-verity enabled. The output will be the same as **fsverity digest** with 147the appropriate parameters, but **fsverity measure** will take constant time 148for each file regardless of the size of the file. 149 150**fsverity measure** does not accept any options. 151 152## **fsverity sign** [*OPTION*...] *FILE* *OUT_SIGFILE* 153 154Sign the given file for fs-verity, in a way that is compatible with the Linux 155kernel's fs-verity built-in signature verification support. The signature will 156be written to *OUT_SIGFILE* in PKCS#7 DER format. 157 158The private key can be specified either by key file or by PKCS#11 token. To use 159a key file, provide **\-\-key** and optionally **\-\-cert**. To use a PKCS#11 160token, provide **\-\-pkcs11-engine**, **\-\-pkcs11-module**, **\-\-cert**, and 161optionally **\-\-pkcs11-keyid**. PKCS#11 token support is unavailable when 162fsverity-utils was built with BoringSSL rather than OpenSSL. 163 164**fsverity sign** should only be used if you need compatibility with fs-verity 165built-in signatures. It is not the only way to do signatures with fs-verity. 166For more information, see the fsverity-utils README. 167 168Options accepted by **fsverity sign**: 169 170**\-\-block-size**=*BLOCK_SIZE* 171: Same as for **fsverity digest**. 172 173**\-\-cert**=*CERTFILE* 174: Specifies the file that contains the certificate, in PEM format. This 175 option is required if *KEYFILE* contains only the private key and not also 176 the certificate, or if a PKCS#11 token is used. 177 178**\-\-hash-alg**=*HASH_ALG* 179: Same as for **fsverity digest**. 180 181**\-\-key**=*KEYFILE* 182: Specifies the file that contains the private key, in PEM format. This 183 option is required when not using a PKCS#11 token. 184 185**\-\-out-descriptor**=*FILE* 186: Same as for **fsverity digest**. 187 188**\-\-out-merkle-tree**=*FILE* 189: Same as for **fsverity digest**. 190 191**\-\-pkcs11-engine**=*SOFILE* 192: Specifies the path to the OpenSSL PKCS#11 engine file. This typically will 193 be a path to the libp11 .so file. This option is required when using a 194 PKCS#11 token. 195 196**\-\-pkcs11-keyid**=*KEYID* 197: Specifies the key identifier in the form of a PKCS#11 URI. If not provided, 198 the default key associated with the token is used. This option is only 199 applicable when using a PKCS#11 token. 200 201**\-\-pkcs11-module**=*SOFILE* 202: Specifies the path to the PKCS#11 token-specific module library. This 203 option is required when using a PKCS#11 token. 204 205**\-\-salt**=*SALT* 206: Same as for **fsverity digest**. 207 208# SEE ALSO 209 210For example commands and more information, see the 211[README file for 212fsverity-utils](https://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/fsverity-utils.git/tree/README.md). 213 214Also see the [kernel documentation for 215fs-verity](https://www.kernel.org/doc/html/latest/filesystems/fsverity.html). 216