View source for DM-verity

{{todo| Add a non-initramfs dm-verity implementation, which should use kernel to do dm-verity checking instead of initramfs, which is better for embedded devices, and faster to boot (but hard to implement because of kernel customizations, might need to compile kernel again.)}}

== Why DM-Verity? ==
Possibly you want to continue the RoT ([https://en.wikipedia.org/wiki/Chain_of_trust Root of Trust] [1]) - from the hardware (Hardware TPM as Root of Trust, which ensures only the hardware with the correct secret cryptographic key in the TPM to decrypt the disk/file encryption) -> secure boot (Secure Boot to only run approved signed EFIStub/signed Bootloader) -> <u>To NOW DM-Verity rootfs</u> (which ensures your root-image/root-parition has not been tampered with) -> Mandatory Access Control (AppArmor or SELinux - SELinux is disabled on default linux-lts btw) -> Sandboxed/Virtual-Machined Applications.

=== What's the difference between me just setting the root partition as read-only (basically just an Immutable Root Partition) vs this? ===
DM-Verity COMPLETELY disallows modifying any files in the root-partition/root-image, or even disallow a part of a root-image/root-partition (the root-image/root-partition needs to be INTACT and match the signed cryptography verified by DM-Verity on a different partition), and with this consideration, you may use ERO-FS or SquashFS to generate Read-Only Root-Paritition/File Images. If you set your EXT4 file system to writable, and DM-Verity were to use it, it would be seen as "corrupted" and not boot anymore, because even just ONE tiny data change to the root image/partition would render it "corrupted". This is the same technology used in Android and Chrome OS Devices. Also related to use in A/B root, also used by Fedora.

{{tip| To keep the security reasonable, you would ideally want to work on the whole RoT, if not then anybody else can attack the non-verifed boot process that ISN'T the root-partition/root-image that is enforced by DM-Verity.
* This following guide will use dracut to make a signed secureboot-able EFIStub.
* If you haven't, you may follow [https://wiki.alpinelinux.org/wiki/LVM_on_LUKS the Alpine Linux disk encryption setup] [2] with DM-Crypt LUKS and LVM
* You may choose to decrypt the image with TPM when generating with Dracut Modules with <code>add_dracutdrivers+{{=}}" ... tpm2-tss ... "</code> and [https://github.com/latchset/clevis?tab{{=}}readme-ov-file#pin-tpm2 Clevis] [3]
* Apply AppArmor using [https://wiki.alpinelinux.org/wiki/AppArmor Alpine Linux AppArmor Wiki] (Docker does use AppArmor already, but you may apply an AppArmor profile on any application that should not have access to specific directories (AppArmor is a PATH based MAC)) [4]
* Use [https://gvisor.dev/docs/user_guide/install/ GVisor] [5] with Docker ([https://github.com/google/gvisor?tab{{=}}readme-ov-file#why-does-gvisor-exist Docker is NOT a sandbox] [6] (Because docker uses native kernel compared to Gvisor using its own kernel reimplementation)) for sandboxing on servers}}

=== What is ERO-FS? ===
[https://pocketnow.com/erofs-android-13-explained/ Google thought about implementing ERO-FS with DM-Verity] [7]. Google was reported to be using it in Android 13, and ERO-FS is an excellent and fast compressed read-only filesystem.

Here is an excerpt about <code>mkfs.erofs</code> on [[https://wiki.archlinux.org/title/Dm-verity Arch Linux Wiki]] [8]:

'' mkfs.erofs(1) offers an attractive alternative to ext4 or squashfs on the root partition. EROFS, like squashfs, does not allow writes by design and has better performance in many cases than comparable filesystems on flash and solid-state media. It uses lz4 compression by default and was designed for Android phones by Huawei, which make extensive use of dm-verity. ''

=== Installing ===

==== Working with ERO-FS ====

{{warning| This wiki will be using Alpine Linux Edge Version. (Alpine Linux Non-Edge Versions may not contain these packages in the following rest of the wiki page) (Use Alpine Linux Edge Testing Repository in <code>/etc/apk/repositories</code> as well)}}

{{note| To not be confused, ERO-FS generates a "root image", but you can replace the words "root partition" with "root image" and vice versa.}}

First, some considerations, you may use a strictly READ-ONLY file system, such as SquashFS or ERO-FS, this wiki will be using ERO-FS (if you use a custom kernel, make sure it supports a file system such as ERO-FS, the default linux-lts does). [[https://github.com/erofs/erofs-utils ERO-FS Github]] [9] contains some information about how to compress and make your own read-only root image.

{{cmd| $ apk install erofs-utils}}
{{cmd| $ mkdir image && cd image }}
{{cmd| $ wget https://dl-cdn.alpinelinux.org/alpine/v3.21/releases/x86_64/alpine-minirootfs-3.21.0-x86_64.tar.gz}}
{{cmd| $ tar -xvf alpine-minirootfs-3.21.0-x86_64.tar.gz && rm alpine-minirootfs-3.21.0-x86_64.tar.gz}}
Command below will generate an ERO-FS Image compressed with lz4 as ./erofs.img (erofs.img would be the root-partition file to use for dracut)
{{cmd| $ cd .. && mkfs.erofs -zlz4hc erofs.img ./image}}

----

==== Choose between a file or a partition ====
{{ todo | wip}}
You can verify the integrity of your erofs/squashfs image, by comparing the hashtable. the hashtable can be a <b>file</b> or a <b>partition<b>.

==== Working with mkinitfs/kernel-hooks/secureboot-hooks ====
{{todo| wip}}

Using mkinitfs, it is possible to force veritysetup in initramfs generation. It is recommended to make a chroot or docker so you don't mess with your system files, and by adding these files:

{{todo| The init script is too big to put in wiki, I just acquired it from initramfs generation and decompression (read the tip below)}}
{{note| the APK package "cryptsetup" comes with veritysetup
{{cmd| apk add cryptsetup}}
}}
{{note| make sure the chroot has a linux-kernel}}

Edit /sbin/mkinitfs (put "# Copy custom init" before "# copy modloop signature"):
{{cat| /etc/mkinitfs|...
        # Copy custom init 
        cp /initramfs/init "$tmpdir"/init 
        
        # copy modloop signature
...}}

PUT "# Call custom script" before "if [ "$SINGLEMODE" = "yes" ]; then"
{{cat| /initramfs/init|...
                # Call custom script
                /etc/scripts/my-custom-script.sh
                
        if [ "$SINGLEMODE" {{=}} "yes" ]; then
...
}}
{{cat| /etc/mkinitfs/features.d/my-custom-script.files|
/etc/scripts/my-custom-script.sh
}}
{{cat| /etc/mkinitfs/features.d/veritysetup.files|
/sbin/veritysetup
}}
{{cat| /etc/mkinitfs/features.d/veritysetup.modules|
kernel/drivers/md/dm-verity.ko*
}}
{{cat| /etc/mkinitfs/features.d/erofs.modules|
kernel/fs/erofs
}}
{{cat| /etc/mkinitfs/mkinitfs.conf|...
features{{=}}"... erofs my-custom-script veritysetup"
MODULES{{=}}"veritysetup erofs"
...}}
{{cat| /etc/scripts/my-custom-script.sh|
#!/bin/sh

mount /dev/mapper/root /root
mount /root/var/root/erofs.img /sysroot
}}

Then just do:
{{cmd| apk add secureboot-hook gummiboot gummiboot-efistub efibootmgr kernel-hooks secureboot-hook}}

{{tip|To make sure initramfs has the scripts needed, do:
{{cmd|mkinitfs -c /etc/mkinitfs/mkinitfs.conf -b / $(uname -r)}}
Decompress:
{{cmd|mkdir /tmp/initramfs
cd /tmp/initramfs
<nowiki>zcat /boot/initramfs-$KERNEL | cpio -idmv</nowiki>}}

Test if "init" works by just executing it and see how it runs:
{{cmd|./init}}
}}

----

==== Working with Dracut ====

Remember, mount your <code>$ROOT_PARTITION</code> as read only (assuming you use EXT4, if using ERO-FS or SquashFS, ignore this), since any changes will cause DM-Verity to detect it as "corrupt"

{{warning| The following guide was done with FULL disk encryption, so this might not work perfectly on Non encrypted disk setup, also done on UEFI using gummiboot (now called systemd-boot - yes, systemd-boot is a separate project from the systemd init system) EFIStub and generating a UKI (Unified Kernel Image)}}

===== Install basic stuff: =====

{{cmd| apk add dracut dracut-core cryptsetup gummiboot gummiboot-efistub tpm2-tools clevis tpm2-tss tpm2-tss-tcti-device}}

===== Using Clevis for TPM =====

{{cmd| clevis luks bind -d /$ENCRYPTED_ROOT_PARTITION tpm2 '{"pcr_ids":"1,7"}'}}
Input LUKS passphrase, remember that yes now it has tpm, but if possible remove old luks passphrase and use keyfile or different passphrase to unlock because tpm is better, and so if your computer breaks, you won't be locked out of your data!

===== Create a new partition for your DM-Verity: =====

Replace /dev/sdX with your actual device name.
{{cmd| sudo fdisk /dev/sdX}}

Once in the fdisk interface:
# Press n to create a new partition
# Choose p for primary partition
# Select the partition number (e.g., 4)
# For the first sector, press Enter to use the default
# For the last sector, calculate 10% of your root partition size and use +SIZE format. For example, if your root partition is 100GB, enter +10G
# Press t to change the partition type
# Enter the partition number you just created
# Type 8e for Linux LVM type (closest to verity)
# Press w to write changes and exit

===== Adding custom lines for full disk decryption =====

Edit "<code>/usr/lib/dracut/modules.d/90crypt/cryptroot-ask.sh</code>" and add these lines right BEFORE "<code>exit 0</code>" (add your <code>$ROOT_PARTITION</code> directory and <code>$VERITY_PARTITION</code> directory):

{{cat| /usr/lib/dracut/modules.d/90crypt/cryptroot-ask.sh|...
### DM-Verity
mount /dev/mapper/$ROOT_PARTITION /var/tmp
cryptsetup open --key-file /var/tmp/$KEYFILE_DIR /dev/$VERITY_PARTITION $VERITY_DM_NAME
umount /var/tmp
veritysetup open /dev/$ROOT_PARTITION /dev/$VERITY_PARTITION $(cat /usr/lib/dracut/roothash.txt)
###
...}}

===== Generating an EFIStub with Dracut + DM-Verity =====

To setup DM-Verity (borrowed from [https://wiki.archlinux.org/title/Dm-verity Arch Linux Wiki]):

{{cmd| veritysetup format /dev/$ROOT_PARTITION /dev/$VERITY_PARTITION | grep Root | cut -f2 >> /usr/lib/dracut/roothash.txt}}

/etc/dracut.conf (put whatever your boot parameters are in "<code>kernel_cmdline</code>"):

{{cat| /etc/dracut.conf|...
kernel_cmdline{{=}}""
add_dracutdrivers+{{=}}" busybox crypt crypt-gpg dm rootfs-block kernel-modules kernel-modules-extra tpm2-tss "
/etc/dracut.conf.d/secureboot.conf

# Do the 3 lines below this if you have your own secureboot keys, or want to use secureboot:
uefi_secureboot_cert{{=}}"/$SECUREBOOT_KEYS_DIR/db.crt"
uefi_secureboot_key{{=}}"/$SECUREBOOT_KEYS_DIR/db.key"
/etc/dracut.conf.d/files.conf

# This is what will import veritysetup binary file into dracut initramfs
install_items+{{=}}" /sbin/veritysetup "
...}}

Finally, generate UKI using dracut (replace <code>6.X.X-X-lts</code> with your kernel <code>$VERSION</code>) (also replace <code>/boot/efi/EFI/Linux/alpine-linux.efi</code> with your mount efi partition):

{{cmd| export DRACUT_KMODDIR_OVERRIDE{{=}}1}}
{{cmd| dracut --include /usr/lib/dracut/roothash.txt /usr/lib/dracut/roothash.txt --host-only --kernel-image /boot/vmlinuz-lts --kmoddir /lib/modules/6.X.X-X-lts --kver 6.X.X-X-lts --uefi --uefi-stub /usr/lib/gummiboot/linuxx64.efi.stub --force --compress lz4 /boot/efi/EFI/Linux/alpine-linux.efi /boot/efi/EFI/Linux/alpine-linux.efi}}
{{cmd| efibootmgr --create --disk /dev/$EFI_PARTITION --part 1 --label alpine-linux --loader EFI/Linux/alpine-linux.efi}}

Unfortunately, using the default Alpine Linux kernel (<code>linux-lts</code>) didn't work so download another distributions root system (like debians or devuan), and replace <code>/lib/modules/6.X.X-X-lts</code>, and <code>/boot/vmlinuz-lts</code> with anothers distributions kernel modules and kernel image (Or consider compiling your [https://wiki.alpinelinux.org/wiki/Hardened_linux own linux-hardened kernel] [11]).

{{tip| If you want to test if DM-Verity fully works, change the <code>$ROOT_PARTITION</code>'s files and it should say it is "corrupt", and not continue the boot process (only if you use EXT4).}}

== External Links ==
==== Root of Trust/Chain of Trust ====
* [https://en.wikipedia.org/wiki/Chain_of_trust https://en.wikipedia.org/wiki/Chain_of_trust] [1]
==== Full disk encryption with LVM and LUKS (AlpineWiki): ====
* [https://wiki.alpinelinux.org/wiki/LVM_on_LUKS LVM_on_LUKS] [2]
==== Clevis Github ====
* [https://github.com/latchset/clevis?tab=readme-ov-file#pin-tpm2 https://github.com/latchset/clevis?tab=readme-ov-file#pin-tpm2] [3]
==== AppArmor Wiki (AlpineWiki) ====
* [https://wiki.alpinelinux.org/wiki/AppArmor AppArmor] [4]
==== GVisor ====
* [https://gvisor.dev/docs/user_guide/install/ https://gvisor.dev/docs/user_guide/install/] [5]
==== Gvisor Github stating docker is not a sandbox ====
* [https://github.com/google/gvisor?tab=readme-ov-file#why-does-gvisor-exist https://github.com/google/gvisor?tab=readme-ov-file#why-does-gvisor-exist] [6]
==== Android-13 Possibility of using ERO-FS: ====
* [https://pocketnow.com/erofs-android-13-explained/ https://pocketnow.com/erofs-android-13-explained/] [7]
==== DM-Verity (Arch Wiki): ====
* [https://wiki.archlinux.org/title/Dm-verity https://wiki.archlinux.org/title/Dm-verity] [8]
==== ERO-FS Github ====
* [https://github.com/erofs/erofs-utils https://github.com/erofs/erofs-utils] [9]
==== Dracut (Arch Wiki): ====
* [https://wiki.archlinux.org/title/Dracut https://wiki.archlinux.org/title/Dracut] [10]
==== Linux-Hardened Kernel (AlpineWiki): ====
* [https://wiki.alpinelinux.org/wiki/Hardened_linux Hardened_linux] [11]
==== My old post on how it worked ====
* [https://www.reddit.com/r/AlpineLinux/comments/15oibcc/comment/k1l7jv0/ https://www.reddit.com/r/AlpineLinux/comments/15oibcc/comment/k1l7jv0/] [12]

[[Category:Security]] [[Category:Booting]]