pub/scm/linux/kernel/git/jes/fsverity-utils.git  about / heads / tags
Jes Sorensen's fork of fsverity-utils.git
$ git log --pretty=format:'%h %s (%cs)%d'
ae75f37 Include local headers first (2020-05-13)
	(HEAD -> master)
cdaefaa Add a script to run 'sparse' (2020-05-13)
a8eeaae scripts/do-release: add .sh suffix and add license ID (2020-05-13)
6585eb4 v1.0 (2019-11-06)
	(tag: v1.0)
9b616d9 Add release script (2019-11-06)
69ebc9d fsverity.c: man page doesn't exist yet (2019-11-06)
2151209 cmd_sign: create detached signatures (2019-06-28)
88438bb cmd_sign: avoid passing NULL to memcpy() (2019-06-28)
ac37171 cmd_sign: use consistent filename quoting style (2019-06-26)
6033f55 cmd_sign: print file measurement on success (2019-06-26)
...

$ git cat-file blob HEAD:README.md
# Introduction

This is `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 hidden Merkle tree (hash tree) associated with 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.

# Building and installing

The `fsverity` utility uses the OpenSSL library, so you first must
install the needed development files.  For example, on Debian-based
systems, run:

```bash
    sudo apt-get install libssl-dev
```

OpenSSL must be version 1.0.0 or later.

Then, to build and install:

```bash
    make
    sudo make install
```

# Examples

## Basic use

```bash
    mkfs.ext4 -O verity /dev/vdc
    mount /dev/vdc /vdc
    cd /vdc

    # Create a test file
    head -c 1000000 /dev/urandom > file
    md5sum file

    # Enable verity on the file
    fsverity enable file

    # Show the verity file measurement
    fsverity measure file

    # File should still be readable as usual.  However, all data read
    # is now transparently checked against a hidden Merkle tree, whose
    # root hash is incorporated into the verity file measurement.
    # Reads of any corrupted parts of the data will fail.
    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.

## Using builtin signatures

With `CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y`, the filesystem supports
automatically verifying a signed file measurement that has been
included in the 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:

```bash
    # 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 verity files be signed:
    sysctl fs.verity.require_signatures=1

    # Now set up fs-verity on a test file:
    md5sum file
    fsverity sign file file.sig --key=key.pem --cert=cert.pem
    fsverity enable file --signature=file.sig
    rm -f file.sig
    md5sum file
```

By default, it's not required that 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 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 verity file, since an attacker could
replace a verity file with a regular one.

## With IMA

IMA support for fs-verity is planned.

# Notices

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](COPYING).

Permission to link to OpenSSL (libcrypto) is granted.

Send questions and bug reports to linux-fscrypt@vger.kernel.org.

# Submitting patches

Send patches to linux-fscrypt@vger.kernel.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 <random@developer.example.org>

using your real name (sorry, no pseudonyms or anonymous contributions.)

# heads (aka `branches'):
$ git for-each-ref --sort=-creatordate refs/heads \
	--format='%(HEAD) %(refname:short) %(subject) (%(creatordate:short))'
* master       Include local headers first (2020-05-13)
  libfsverity  Fixup Makefile (2020-04-24)

# tags:
$ git for-each-ref --sort=-creatordate refs/tags \
	--format='%(refname:short) %(subject) (%(creatordate:short))'
v1.0         fsverity-utils-1.0 (2019-11-06) tar.gz

# associated public inboxes:
# (number on the left is used for dev purposes)
        189 linux-fscrypt
          7 linux-ext4
          6 linux-f2fs-devel
          4 lkml
          3 stable
          3 u-boot
          2 linux-wireless
          2 linux-mtd
          2 linux-xfs
          2 linux-nfs
          2 qemu-devel
          2 netfilter-devel
          2 linux-integrity
          2 linux-fsdevel
          2 netdev
          2 linux-snps-arc
          2 linux-gpio
          2 linux-rdma
          2 dpdk-dev
          2 linuxppc-dev
          2 kvm
          2 linux-bluetooth
          2 util-linux
          2 git
          2 linux-api
          2 cip-dev
          2 dm-devel
          2 buildroot
          2 fio
          2 xenomai
          2 poky
          1 linux-samsung-soc
          1 cocci
          1 linux-block
          1 linux-riscv
          1 linux-nvme
          1 live-patching
          1 bpf
          1 linux-mediatek
          1 linux-crypto
          1 linux-efi
          1 linux-acpi
          1 linux-edac
          1 linux-cifs
          1 linux-devicetree
          1 linux-arm-msm
          1 linux-amlogic
          1 linux-erofs
          1 linux-mm
          1 linux-nvdimm
          1 linux-iommu
          1 linux-media
          1 xen-devel
          1 linux-mips
          1 fstests
          1 linux-pm
          1 linux-hwmon
          1 linux-rtc
          1 linux-input
          1 alsa-devel
          1 linux-scsi
          1 linux-btrfs
          1 linux-arm-kernel
          1 kvmarm
          1 driverdev-devel
          1 linux-usb
          1 linux-renesas-soc
          1 linux-kselftest
          1 selinux
          1 kernel-hardening
          1 linux-clk
          1 linux-iio
          1 dmaengine
          1 linux-next
          1 linux-parisc
          1 linux-leds
          1 linux-security-module
          1 linux-pci
          1 linux-modules
          1 kernelnewbies
          1 linux-rt-users
          1 linux-sgx
          1 linux-ide
          1 linux-serial
          1 linux-watchdog
          1 linux-trace-devel
          1 linux-hyperv
          1 workflows
          1 rcu
          1 linux-m68k
          1 linux-i3c
          1 linux-spdx
          1 linux-wpan
          1 ksummit-discuss
          1 wireguard
          1 backports
          1 io-uring
          1 linux-kernel-mentees
          1 linux-doc
          1 linux-csky
          1 linux-man
          1 linux-mmc
          1 amd-gfx
          1 dri-devel
          1 intel-gfx
          1 tpmdd-devel
          1 linux-unionfs
          1 linux-firmware
          1 linux-omap
          1 linux-audit
          1 linux-spi
          1 linux-i2c
          1 linux-remoteproc
          1 linux-dash
          1 linux-bcache
          1 linux-sparse
          1 mm-commits
          1 linux-pwm
          1 linux-tegra
          1 lttng-dev
          1 virtualization
          1 linux-kbuild
          1 linux-fpga
          1 ceph-devel
          1 linux-arch
          1 linux-can
          1 containers
          1 linux-rockchip
          1 linux-raid
          1 xdp-newbies
          1 platform-driver-x86
          1 phone-devel
          1 openbmc
          1 linux-hardening
          1 dash
          1 keyrings
          1 linux-fbdev
          1 linux-sctp
          1 linux-cxl
          1 linux-perf-users
          1 target-devel
          1 lustre-devel
          1 linux-sh
          1 soc
          1 ocfs2-devel
          1 rust-for-linux
          1 ath10k
          1 ath11k
          1 nouveau
          1 linux-phy
          1 linux-s390
          1 kernel-janitors
          1 sparclinux
          1 linux-staging
          1 linux-sunxi
          1 mptcp
          1 linux-coco
          1 regressions
          1 ksummit
          1 b43-dev
          1 nvdimm
          1 linux-nfc
          1 linux-bcachefs
          1 ath9k-devel
          1 ntfs3
          1 llvm
          1 iwd
          1 ell
          1 ofono
          1 ltp
          1 yocto
          1 yocto-meta-freescale
          1 openembedded-core
          1 yocto-toaster
          1 yocto-meta-arm
          1 yocto-docs
          1 openembedded-devel
          1 bitbake-devel
          1 linux-patches
          1 yocto-meta-virtualization
          1 chrome-platform
          1 ntb
          1 yocto-meta-ti
          1 yocto-meta-arago
          1 outreachy
          1 damon
          1 asahi
          1 openrisc
          1 intel-wired-lan
          1 kexec
          1 loongarch
          1 imx
          1 ath12k
          1 b4-sent
          1 linux-trace-kernel
          1 oe-linux-nfc
          1 oe-kbuild-all
          1 oe-chipsec
          1 batman
          1 intel-xe
          1 linux-um
          1 virtio-dev
          1 virtio-comment
          1 v9fs
          1 ecryptfs
          1 qemu-riscv
          1 linux-ia64
          1 cluster-devel
          1 grub-devel
          1 kbd
          1 autofs
          1 cpufreq
          1 dccp
          1 cgroups
          1 devicetree-spec
          1 devicetree-compiler
          1 initramfs
          1 kvm-ppc
          1 hail-devel
          1 kvm-ia64
          1 linux-8086
          1 kernel-testers
          1 linux-alpha
          1 linux-btrace
          1 linux-embedded
          1 linux-hams
          1 linux-hexagon
          1 linux-hotplug
          1 linux-laptop
          1 linux-sound
          1 trinity
          1 reiserfs-devel
          1 linux-metag
          1 linux-x25
          1 linux-nilfs
          1 lvs-devel
          1 netfilter
          1 linux-oxnas
          1 u-boot-amlogic
          1 lm-sensors
          1 lvm-devel
          1 acpica-devel
          1 perfbook
          1 virtio-fs
          1 smatch
          1 ../../../../../../../fuego
          1 ../../../../../../../wireless-regdb
          1 ../../../../../../../igt-dev
          1 ../../../../../../../powertop

git clone https://yhbt.net/lore/pub/scm/linux/kernel/git/jes/fsverity-utils.git