1# Introduction 2 3This is `fsverity`, a userspace utility for fs-verity. fs-verity is 4a Linux kernel feature that does transparent on-demand 5integrity/authenticity verification of the contents of read-only 6files, using a Merkle tree (hash tree) hidden after the end of the 7file. The mechanism is similar to dm-verity, but implemented at the 8file level rather than at the block device level. The `fsverity` 9utility allows you to set up fs-verity protected files. 10 11fs-verity will initially be supported by the ext4 and f2fs 12filesystems, but it may later be supported by other filesystems too. 13 14# Building and installing 15 16The `fsverity` utility uses the OpenSSL library, so you first must 17install the needed development files. For example, on Debian-based 18systems, run: 19 20```bash 21 sudo apt-get install libssl-dev 22``` 23 24OpenSSL must be version 1.0.0 or later. 25 26Then, to build and install: 27 28```bash 29 make 30 sudo make install 31``` 32 33# Examples 34 35## Basic use 36 37```bash 38 mkfs.f2fs -O verity /dev/vdc 39 mount /dev/vdc /vdc 40 cd /vdc 41 42 # Create a test file 43 head -c 1000000 /dev/urandom > file 44 md5sum file 45 46 # Append the Merkle tree and other metadata to the file: 47 fsverity setup file 48 49 # Enable fs-verity on the file 50 fsverity enable file 51 52 # Should show the same hash that 'fsverity setup' printed. 53 # This hash can be logged, or compared to a trusted value. 54 fsverity measure file 55 56 # Contents are now transparently verified and should match the 57 # original file contents, i.e. the metadata is hidden. 58 md5sum file 59``` 60 61Note that in the above example, the file isn't signed. Therefore, to 62get any authenticity protection (as opposed to just integrity 63protection), the output of `fsverity measure` needs to be compared 64against a trusted value. 65 66## Using builtin signatures 67 68With `CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y`, the filesystem supports 69automatically verifying a signed file measurement that has been 70included in the fs-verity metadata. The signature is verified against 71the set of X.509 certificates that have been loaded into the 72".fs-verity" kernel keyring. Here's an example: 73 74```bash 75 # Generate a new certificate and private key: 76 openssl req -newkey rsa:4096 -nodes -keyout key.pem -x509 -out cert.pem 77 78 # Convert the certificate from PEM to DER format: 79 openssl x509 -in cert.pem -out cert.der -outform der 80 81 # Load the certificate into the fs-verity keyring: 82 keyctl padd asymmetric '' %keyring:.fs-verity < cert.der 83 84 # Optionally, lock the keyring so that no more keys can be added 85 # (requires keyctl v1.5.11 or later): 86 keyctl restrict_keyring %keyring:.fs-verity 87 88 # Optionally, require that all fs-verity files be signed: 89 sysctl fs.verity.require_signatures=1 90 91 # Now set up fs-verity on a test file: 92 md5sum file 93 fsverity setup file --signing-key=key.pem --signing-cert=cert.pem 94 fsverity enable file 95 md5sum file 96``` 97 98By default, it's not required that fs-verity files have a signature. 99This can be changed with `sysctl fs.verity.require_signatures=1`. 100When set, it's guaranteed that the contents of every fs-verity file 101has been signed by one of the certificates in the keyring. 102 103Note: applications generally still need to check whether the file 104they're accessing really is a fs-verity file, since an attacker could 105replace a fs-verity file with a regular one. 106 107## With IMA 108 109IMA support for fs-verity is planned. 110 111# Notices 112 113This project is provided under the terms of the GNU General Public 114License, version 2; or at your option, any later version. A copy of the 115GPLv2 can be found in the file named [COPYING](COPYING). 116 117Permission to link to OpenSSL (libcrypto) is granted. 118 119Send questions and bug reports to linux-fscrypt@vger.kernel.org. 120 121# Submitting patches 122 123Send patches to linux-fscrypt@vger.kernel.org. Patches should follow 124the Linux kernel's coding style. Additionally, like the Linux kernel 125itself, patches require the following "sign-off" procedure: 126 127The sign-off is a simple line at the end of the explanation for the 128patch, which certifies that you wrote it or otherwise have the right 129to pass it on as an open-source patch. The rules are pretty simple: 130if you can certify the below: 131 132Developer's Certificate of Origin 1.1 133 134By making a contribution to this project, I certify that: 135 136 (a) The contribution was created in whole or in part by me and I 137 have the right to submit it under the open source license 138 indicated in the file; or 139 140 (b) The contribution is based upon previous work that, to the best 141 of my knowledge, is covered under an appropriate open source 142 license and I have the right under that license to submit that 143 work with modifications, whether created in whole or in part 144 by me, under the same open source license (unless I am 145 permitted to submit under a different license), as indicated 146 in the file; or 147 148 (c) The contribution was provided directly to me by some other 149 person who certified (a), (b) or (c) and I have not modified 150 it. 151 152 (d) I understand and agree that this project and the contribution 153 are public and that a record of the contribution (including all 154 personal information I submit with it, including my sign-off) is 155 maintained indefinitely and may be redistributed consistent with 156 this project or the open source license(s) involved. 157 158then you just add a line saying:: 159 160 Signed-off-by: Random J Developer <random@developer.example.org> 161 162using your real name (sorry, no pseudonyms or anonymous contributions.) 163