$ 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://80x24.org/lore/pub/scm/linux/kernel/git/jes/fsverity-utils.git