1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
% 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/fs/fsverity/fsverity-utils.git/tree/README.md).
Also see the [kernel documentation for
fs-verity](https://www.kernel.org/doc/html/latest/filesystems/fsverity.html).
|
