diff options
author | Eric Biggers <ebiggers@google.com> | 2018-06-27 15:01:06 -0700 |
---|---|---|
committer | Eric Biggers <ebiggers@google.com> | 2018-06-27 15:01:06 -0700 |
commit | be980faf6de9e451310c9124444bcddbc03404cc (patch) | |
tree | b839f5acb25cb3adc0081d13764db0c655e86bb7 | |
parent | 431c67bd2e5c420dd7026966185a685bd6d04a19 (diff) | |
download | fsverity-utils-be980faf6de9e451310c9124444bcddbc03404cc.tar.gz |
Add a README file with some basic examples
Signed-off-by: Eric Biggers <ebiggers@google.com>
-rw-r--r-- | README.md | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..d5428ec --- /dev/null +++ b/README.md @@ -0,0 +1,74 @@ +# Introduction + +This is `fsverity`, the 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. + +Currently, fs-verity is supported by the ext4 and f2fs filesystems. + +# Building and installing + +The `fsverity` utility uses the OpenSSL and zlib libraries, so you +first must install the needed development files. For example, on +Debian-based systems, run: + +```bash + sudo apt-get install libssl-dev libz-dev +``` + +OpenSSL must be version 1.0.0 or later. + +Then, to build and install: + +```bash + make + sudo make install +``` + +# Examples + +```bash + 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, and + # sign the file with the kernel build-time generated key: + fsverity setup file --signing-key ~/linux/certs/signing_key.pem + + # Enable fs-verity on the file + fsverity enable file + + # Contents are now transparently verified and should match the + # original file contents, i.e. the metadata is hidden. + md5sum file +``` + +Usage without signing the file (deprecated, requires that the kernel +was built with `CONFIG_FS_VERITY_USERSPACE_SIG_VERIFY=y`): +```bash + m=$(fsverity setup file | awk '/measurement/{print $3}') + fsverity enable file + fsverity set_measurement file $m + md5sum file +``` + +# Notices + +Copyright (C) 2018 Google, Inc. + +License GPLv2+. Permission to link to OpenSSL (libcrypto) is granted. + +This is not an official Google product. + +Do not fold, spindle, or mutilate. + +Send questions, bug reports, and patches to linux-fscrypt@vger.kernel.org. |