README.md
1# fsverity-utils
2
3## Introduction
4
5This is fsverity-utils, a set of userspace utilities for fs-verity.
6fs-verity is a Linux kernel feature that does transparent on-demand
7integrity/authenticity verification of the contents of read-only
8files, using a hidden Merkle tree (hash tree) associated with the
9file. It is similar to dm-verity, but implemented at the file level
10rather than at the block device level. See the [kernel
11documentation](https://www.kernel.org/doc/html/latest/filesystems/fsverity.html)
12for more information about fs-verity.
13
14fs-verity is supported by the ext4 and f2fs filesystems in Linux v5.4
15and later when configured with `CONFIG_FS_VERITY=y` and when the
16`verity` filesystem feature flag has been enabled. Other filesystems
17might add support for fs-verity in the future.
18
19fsverity-utils currently contains just one program, `fsverity`. The
20`fsverity` program allows you to set up fs-verity protected files.
21In addition, the file digest computation and signing functionality of
22`fsverity` is optionally exposed through a C library `libfsverity`.
23See `libfsverity.h` for the API of this library.
24
25## Building and installing
26
27fsverity-utils uses the OpenSSL library, so you first must install the
28needed development files. For example, on Debian-based systems, run:
29
30```bash
31 sudo apt-get install libssl-dev
32```
33
34OpenSSL must be version 1.0.0 or later.
35
36Then, to build and install fsverity-utils:
37
38```bash
39 make
40 sudo make install
41```
42
43By default, the following targets are built and installed: the program
44`fsverity`, the static library `libfsverity.a`, and the shared library
45`libfsverity.so`. You can also run `make check` to build and run the
46tests, or `make help` to display all available build targets.
47
48By default, `fsverity` is statically linked to `libfsverity`. You can
49use `make USE_SHARED_LIB=1` to use dynamic linking instead.
50
51See the `Makefile` for other supported build and installation options.
52
53### Building on Windows
54
55There is minimal support for building Windows executables using MinGW.
56```bash
57 make CC=x86_64-w64-mingw32-gcc
58```
59
60`fsverity.exe` will be built, and it supports the `digest` and `sign` commands.
61
62A Windows build of OpenSSL/libcrypto needs to be available.
63
64## Examples
65
66### Basic use
67
68```bash
69 mkfs.ext4 -O verity /dev/vdc
70 mount /dev/vdc /vdc
71 cd /vdc
72
73 # Create a test file
74 head -c 1000000 /dev/urandom > file
75 sha256sum file
76
77 # Enable verity on the file
78 fsverity enable file
79
80 # Show the verity file digest
81 fsverity measure file
82
83 # File should still be readable as usual. However, all data read
84 # is now transparently checked against a hidden Merkle tree, whose
85 # root hash is incorporated into the verity file digest. Reads of
86 # any corrupted parts of the data will fail.
87 sha256sum file
88```
89
90Note that in the above example, the file isn't signed. Therefore, to
91get any authenticity protection (as opposed to just integrity
92protection), the output of `fsverity measure` needs to be compared
93against a trusted value.
94
95### Using builtin signatures
96
97With `CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y`, the filesystem supports
98automatically verifying a signed file digest that has been included in
99the verity metadata. The signature is verified against the set of
100X.509 certificates that have been loaded into the ".fs-verity" kernel
101keyring. Here's an example:
102
103```bash
104 # Generate a new certificate and private key:
105 openssl req -newkey rsa:4096 -nodes -keyout key.pem -x509 -out cert.pem
106
107 # Convert the certificate from PEM to DER format:
108 openssl x509 -in cert.pem -out cert.der -outform der
109
110 # Load the certificate into the fs-verity keyring:
111 keyctl padd asymmetric '' %keyring:.fs-verity < cert.der
112
113 # Optionally, lock the keyring so that no more keys can be added
114 # (requires keyctl v1.5.11 or later):
115 keyctl restrict_keyring %keyring:.fs-verity
116
117 # Optionally, require that all verity files be signed:
118 sysctl fs.verity.require_signatures=1
119
120 # Now set up fs-verity on a test file:
121 sha256sum file
122 fsverity sign file file.sig --key=key.pem --cert=cert.pem
123 fsverity enable file --signature=file.sig
124 rm -f file.sig
125 sha256sum file
126
127 # The digest to be signed can also be printed separately, hex
128 # encoded, in case the integrated signing cannot be used:
129 fsverity digest file --compact --for-builtin-sig | tr -d '\n' | xxd -p -r | openssl smime -sign -in /dev/stdin ...
130```
131
132By default, it's not required that verity files have a signature.
133This can be changed with `sysctl fs.verity.require_signatures=1`.
134When set, it's guaranteed that the contents of every verity file has
135been signed by one of the certificates in the keyring.
136
137Note: applications generally still need to check whether the file
138they're accessing really is a verity file, since an attacker could
139replace a verity file with a regular one.
140
141### With IMA
142
143IMA support for fs-verity is planned.
144
145## Notices
146
147fsverity-utils is provided under the terms of the MIT license. A copy
148of this license can be found in the file named [LICENSE](LICENSE).
149
150Send questions and bug reports to linux-fscrypt@vger.kernel.org.
151
152Signed release tarballs for fsverity-utils can be found on
153[kernel.org](https://kernel.org/pub/linux/kernel/people/ebiggers/fsverity-utils/).
154
155## Contributing
156
157Send patches to linux-fscrypt@vger.kernel.org with the additional tag
158`fsverity-utils` in the subject, i.e. `[fsverity-utils PATCH]`.
159Patches should follow the Linux kernel's coding style. A
160`.clang-format` file is provided to approximate this coding style;
161consider using `git clang-format`. Additionally, like the Linux
162kernel itself, patches require the following "sign-off" procedure:
163
164The sign-off is a simple line at the end of the explanation for the
165patch, which certifies that you wrote it or otherwise have the right
166to pass it on as an open-source patch. The rules are pretty simple:
167if you can certify the below:
168
169Developer's Certificate of Origin 1.1
170
171By making a contribution to this project, I certify that:
172
173 (a) The contribution was created in whole or in part by me and I
174 have the right to submit it under the open source license
175 indicated in the file; or
176
177 (b) The contribution is based upon previous work that, to the best
178 of my knowledge, is covered under an appropriate open source
179 license and I have the right under that license to submit that
180 work with modifications, whether created in whole or in part
181 by me, under the same open source license (unless I am
182 permitted to submit under a different license), as indicated
183 in the file; or
184
185 (c) The contribution was provided directly to me by some other
186 person who certified (a), (b) or (c) and I have not modified
187 it.
188
189 (d) I understand and agree that this project and the contribution
190 are public and that a record of the contribution (including all
191 personal information I submit with it, including my sign-off) is
192 maintained indefinitely and may be redistributed consistent with
193 this project or the open source license(s) involved.
194
195then you just add a line saying::
196
197 Signed-off-by: Random J Developer <random@developer.example.org>
198
199using your real name (sorry, no pseudonyms or anonymous contributions.)
200