$ git log --pretty=format:'%h %s (%cs)%d'
2543e6e v1.6 (2024-03-20)
(HEAD -> master, tag: v1.6)
d54b6bb Eliminate dependency on pandoc (2024-03-20)
da05cca ci.yml: work around ASAN binaries crashing on ubuntu-latest (2024-03-20)
287f133 ci.yml: upgrade to actions/checkout@v4 and actions/cache@v4 (2024-03-20)
4ba7969 cmd_measure: reject options and handle "--" correctly (2023-07-09)
585e14a fsverity.1: update documentation for --block-size (2023-07-05)
5d6f7c4 ci.yml: upgrade to actions/checkout@v3 (2023-01-30)
6866e7e fsverity.1.md: use the new git repo URL (2023-01-25)
c3098e1 README.md: use the new fsverity mailing list (2023-01-24)
49dc216 libfsverity.h: includes should be outside of extern "C" block (2023-01-11)
...
$ git cat-file blob HEAD:README.md
# fsverity-utils
## Introduction
This is fsverity-utils, a set of userspace utilities 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. It is similar to dm-verity, but implemented at the file level
rather than at the block device level. See the [kernel
documentation](https://www.kernel.org/doc/html/latest/filesystems/fsverity.html)
for more information about fs-verity, including which filesystems
support it.
fsverity-utils currently contains just one program, `fsverity`. The
`fsverity` program allows you to set up fs-verity protected files.
In addition, the file digest computation and signing functionality of
`fsverity` is optionally exposed through a C library `libfsverity`.
See `libfsverity.h` for the API of this library.
## Building and installing
To build fsverity-utils, first install the needed build dependencies. For
example, on Debian-based systems, run:
```bash
sudo apt-get install libssl-dev
```
OpenSSL must be version 1.0.0 or later. This is the only runtime dependency.
Then, to build and install fsverity-utils:
```bash
make
sudo make install
```
By default, the following targets are built and installed: the program
`fsverity`, the static library `libfsverity.a`, the shared library
`libfsverity.so`, and the manual page `fsverity.1`. You can also run
`make check` to build and run the tests, or `make help` to display all
available build targets.
By default, `fsverity` is statically linked to `libfsverity`. You can
use `make USE_SHARED_LIB=1` to use dynamic linking instead.
See the `Makefile` for other supported build and installation options.
### Building on Windows
There is minimal support for building Windows executables using MinGW.
```bash
make CC=x86_64-w64-mingw32-gcc
```
`fsverity.exe` will be built, and it supports the `digest` and `sign` commands.
A Windows build of OpenSSL/libcrypto needs to be available.
## Examples
Full usage information for `fsverity` can be found in the manual page
(`man fsverity`). Here, we just show some typical 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
sha256sum file
# Enable verity on the file
fsverity enable file
# Show the verity file digest
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 digest. Reads of
# any corrupted parts of the data will fail.
sha256sum 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.
### With IMA
Since Linux v5.19, the kernel's IMA (Integrity Measurement
Architecture) subsystem supports using fs-verity file digests in lieu
of traditional file digests. This must be configured in the IMA
policy. For more information, see the IMA documentation.
### Using builtin signatures
First, note that fs-verity is essentially just a way of hashing a
file; it doesn't mandate a specific way of handling signatures.
There are several possible ways that signatures could be handled:
* Do it entirely in userspace
* Use IMA appraisal
* Use fs-verity built-in signatures
Any such solution needs two parts: (a) a policy that determines which
files are required to have fs-verity enabled and have a valid
signature, and (b) enforcement of the policy. Each part could happen
either in a trusted userspace program(s) or in the kernel.
fs-verity built-in signatures (which are supported when the kernel was
built with `CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y`) are a hybrid
solution where the policy of which files are required to be signed is
determined and enforced by a trusted userspace program, but the actual
signature verification happens in the kernel. Specifically, with
built-in signatures, the filesystem supports storing a signed file
digest in each file's verity metadata. Before allowing access to the
file, the filesystem will automatically verify the signature against
the set of X.509 certificates in the ".fs-verity" kernel keyring. If
set, the sysctl `fs.verity.require_signatures=1` will make the kernel
enforce that every verity file has a valid built-in signature.
fs-verity built-in signatures are primarily intended as a
proof-of-concept; they reuse the kernel code that verifies the
signatures of loadable kernel modules. This solution still requires a
trusted userspace program to enforce that particular files have
fs-verity enabled. Also, this solution uses PKCS#7 signatures, which
are complex and prone to security bugs.
Thus, if possible one of the other solutions should be used instead.
For example, the trusted userspace program could verify signatures
itself, using a simple signature format using a modern algorithm such
as Ed25519.
That being said, here are some examples of using built-in signatures:
```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:
sha256sum file
fsverity sign file file.sig --key=key.pem --cert=cert.pem
fsverity enable file --signature=file.sig
rm -f file.sig
sha256sum file
# The digest to be signed can also be printed separately, hex
# encoded, in case the integrated signing cannot be used:
fsverity digest file --compact --for-builtin-sig | tr -d '\n' | xxd -p -r | openssl smime -sign -in /dev/stdin ...
```
## Notices
fsverity-utils is provided under the terms of the MIT license. A copy
of this license can be found in the file named [LICENSE](LICENSE).
Send questions and bug reports to fsverity@lists.linux.dev.
Signed release tarballs for fsverity-utils can be found on
[kernel.org](https://kernel.org/pub/linux/kernel/people/ebiggers/fsverity-utils/).
## Contributing
Send patches to fsverity@lists.linux.dev with the additional tag
`fsverity-utils` in the subject, i.e. `[fsverity-utils PATCH]`.
Patches should follow the Linux kernel's coding style. A
`.clang-format` file is provided to approximate this coding style;
consider using `git clang-format`. 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 v1.6 (2024-03-20)
posix-strerror lib: use the POSIX version of strerror_r() (2021-12-18)
# tags:
$ git for-each-ref --sort=-creatordate refs/tags \
--format='%(refname:short) %(subject) (%(creatordate:short))'
v1.6 fsverity-utils-1.6 (2024-03-20) tar.gz
v1.5 fsverity-utils-1.5 (2022-02-06) tar.gz
v1.4 fsverity-utils-1.4 (2021-06-14) tar.gz
v1.3 fsverity-utils-1.3 (2021-01-19) tar.gz
v1.2 fsverity-utils-1.2 (2020-08-17) tar.gz
v1.1 fsverity-utils-1.1 (2020-06-14) tar.gz
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/fs/fsverity/fsverity-utils.git