fsverity, a userspace utility for fs-verity. fs-verity is a Linux kernel feature that does transparent on-demand integrity/authenticity verification of the contents of read-only files, using a Merkle tree (hash tree) hidden after the end of the file. The mechanism is similar to dm-verity, but implemented at the file level rather than at the block device level. The
fsverity utility allows you to set up fs-verity protected files.
fs-verity will initially be supported by the ext4 and f2fs filesystems, but it may later be supported by other filesystems too.
fsverity utility uses the OpenSSL library, so you first must install the needed development files. For example, on Debian-based systems, run:
sudo apt-get install libssl-dev
OpenSSL must be version 1.0.0 or later.
Then, to build and install:
make sudo make install
mkfs.f2fs -O verity /dev/vdc mount /dev/vdc /vdc cd /vdc # Create a test file head -c 1000000 /dev/urandom > file md5sum file # Append the Merkle tree and other metadata to the file: fsverity setup file # Enable fs-verity on the file fsverity enable file # Should show the same hash that 'fsverity setup' printed. # This hash can be logged, or compared to a trusted value. fsverity measure file # Contents are now transparently verified and should match the # original file contents, i.e. the metadata is hidden. md5sum file
Note that in the above example, the file isn't signed. Therefore, to get any authenticity protection (as opposed to just integrity protection), the output of
fsverity measure needs to be compared against a trusted value.
CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y, the filesystem supports automatically verifying a signed file measurement that has been included in the fs-verity metadata. The signature is verified against the set of X.509 certificates that have been loaded into the “.fs-verity” kernel keyring. Here's an example:
# Generate a new certificate and private key: openssl req -newkey rsa:4096 -nodes -keyout key.pem -x509 -out cert.pem # Convert the certificate from PEM to DER format: openssl x509 -in cert.pem -out cert.der -outform der # Load the certificate into the fs-verity keyring: keyctl padd asymmetric '' %keyring:.fs-verity < cert.der # Optionally, lock the keyring so that no more keys can be added # (requires keyctl v1.5.11 or later): keyctl restrict_keyring %keyring:.fs-verity # Optionally, require that all fs-verity files be signed: sysctl fs.verity.require_signatures=1 # Now set up fs-verity on a test file: md5sum file fsverity setup file --signing-key=key.pem --signing-cert=cert.pem fsverity enable file md5sum file
By default, it‘s not required that fs-verity files have a signature. This can be changed with
sysctl fs.verity.require_signatures=1. When set, it’s guaranteed that the contents of every fs-verity file has been signed by one of the certificates in the keyring.
Note: applications generally still need to check whether the file they're accessing really is a fs-verity file, since an attacker could replace a fs-verity file with a regular one.
IMA support for fs-verity is planned.
This project is provided under the terms of the GNU General Public License, version 2; or at your option, any later version. A copy of the GPLv2 can be found in the file named COPYING.
Permission to link to OpenSSL (libcrypto) is granted.
Send questions and bug reports to email@example.com.
Send patches to firstname.lastname@example.org. Patches should follow the Linux kernel's coding style. Additionally, like the Linux kernel itself, patches require the following “sign-off” procedure:
The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below:
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
then you just add a line saying::
Signed-off-by: Random J Developer <email@example.com>
using your real name (sorry, no pseudonyms or anonymous contributions.)