1# Introduction 2 3This is `fsverity`, a userspace utility for fs-verity. fs-verity is a 4Linux kernel feature that does transparent on-demand 5integrity/authenticity verification of the contents of read-only 6files, using a hidden Merkle tree (hash tree) associated with 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.ext4 -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 # Enable verity on the file 47 fsverity enable file 48 49 # Show the verity file measurement 50 fsverity measure file 51 52 # File should still be readable as usual. However, all data read 53 # is now transparently checked against a hidden Merkle tree, whose 54 # root hash is incorporated into the verity file measurement. 55 # Reads of any corrupted parts of the data will fail. 56 md5sum file 57``` 58 59Note that in the above example, the file isn't signed. Therefore, to 60get any authenticity protection (as opposed to just integrity 61protection), the output of `fsverity measure` needs to be compared 62against a trusted value. 63 64## Using builtin signatures 65 66With `CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y`, the filesystem supports 67automatically verifying a signed file measurement that has been 68included in the verity metadata. The signature is verified against 69the set of X.509 certificates that have been loaded into the 70".fs-verity" kernel keyring. Here's an example: 71 72```bash 73 # Generate a new certificate and private key: 74 openssl req -newkey rsa:4096 -nodes -keyout key.pem -x509 -out cert.pem 75 76 # Convert the certificate from PEM to DER format: 77 openssl x509 -in cert.pem -out cert.der -outform der 78 79 # Load the certificate into the fs-verity keyring: 80 keyctl padd asymmetric '' %keyring:.fs-verity < cert.der 81 82 # Optionally, lock the keyring so that no more keys can be added 83 # (requires keyctl v1.5.11 or later): 84 keyctl restrict_keyring %keyring:.fs-verity 85 86 # Optionally, require that all verity files be signed: 87 sysctl fs.verity.require_signatures=1 88 89 # Now set up fs-verity on a test file: 90 md5sum file 91 fsverity sign file file.sig --key=key.pem --cert=cert.pem 92 fsverity enable file --signature=file.sig 93 rm -f file.sig 94 md5sum file 95``` 96 97By default, it's not required that verity files have a signature. 98This can be changed with `sysctl fs.verity.require_signatures=1`. 99When set, it's guaranteed that the contents of every verity file has 100been signed by one of the certificates in the keyring. 101 102Note: applications generally still need to check whether the file 103they're accessing really is a verity file, since an attacker could 104replace a verity file with a regular one. 105 106## With IMA 107 108IMA support for fs-verity is planned. 109 110# Notices 111 112This project is provided under the terms of the GNU General Public 113License, version 2; or at your option, any later version. A copy of the 114GPLv2 can be found in the file named [COPYING](COPYING). 115 116Permission to link to OpenSSL (libcrypto) is granted. 117 118Send questions and bug reports to linux-fscrypt@vger.kernel.org. 119 120# Submitting patches 121 122Send patches to linux-fscrypt@vger.kernel.org. Patches should follow 123the Linux kernel's coding style. Additionally, like the Linux kernel 124itself, patches require the following "sign-off" procedure: 125 126The sign-off is a simple line at the end of the explanation for the 127patch, which certifies that you wrote it or otherwise have the right 128to pass it on as an open-source patch. The rules are pretty simple: 129if you can certify the below: 130 131Developer's Certificate of Origin 1.1 132 133By making a contribution to this project, I certify that: 134 135 (a) The contribution was created in whole or in part by me and I 136 have the right to submit it under the open source license 137 indicated in the file; or 138 139 (b) The contribution is based upon previous work that, to the best 140 of my knowledge, is covered under an appropriate open source 141 license and I have the right under that license to submit that 142 work with modifications, whether created in whole or in part 143 by me, under the same open source license (unless I am 144 permitted to submit under a different license), as indicated 145 in the file; or 146 147 (c) The contribution was provided directly to me by some other 148 person who certified (a), (b) or (c) and I have not modified 149 it. 150 151 (d) I understand and agree that this project and the contribution 152 are public and that a record of the contribution (including all 153 personal information I submit with it, including my sign-off) is 154 maintained indefinitely and may be redistributed consistent with 155 this project or the open source license(s) involved. 156 157then you just add a line saying:: 158 159 Signed-off-by: Random J Developer <random@developer.example.org> 160 161using your real name (sorry, no pseudonyms or anonymous contributions.) 162