dm-verity and Yocto/OE ---------------------- The dm-verity feature provides a level of data integrity and resistance to data tampering. It does this by creating a hash for each data block of the underlying device as the base of a hash tree. There are many documents out there to further explain the implementaion, such as the in-kernel one itself: https://docs.kernel.org/admin-guide/device-mapper/verity.html The goal of this document is not to reproduce that content, but instead to capture the Yocto/OE specifics of the dm-verity infrastructure used here. Ideally this should enable a person to build and deploy an image on one of the supported reference platforms, and then further adapt to their own platform and specific storage requirements. Basic Settings -------------- Largely everything is driven off of a dm-verity image class; a typical block of non MACHINE specific settings are shown below: INITRAMFS_IMAGE = "dm-verity-image-initramfs" DM_VERITY_IMAGE = "core-image-minimal" DM_VERITY_IMAGE_TYPE = "ext4" IMAGE_CLASSES += "dm-verity-img" INITRAMFS_IMAGE_BUNDLE = "1" Kernel Configuration -------------------- Kernel configuration for dm-verity happens automatically via IMAGE_CLASSES which will source features/device-mapper/dm-verity.scc when dm-verity-img is used. [See commit d9feafe991c] IMPORTANT: As per the top level README, you *must* put security in the DISTRO_FEATURES, or else you won't get the dm-verity kernel settings. Supported Platforms ------------------- In theory, you can use dm-verity anywhere - there is nothing arch/BSP specific in the core kernel support. However, at the BSP level, one eventually has to decide what device(s) are to be hashed, and where the hash tables are stored. To that end, the BSP storage specifics live in meta-security/wic dir and represent the current set of example configurations that have been tested and submitted at some point. Getting Started --------------- This document assumes you are starting from the basic auto-created conf/local.conf and conf/bblayers.conf from the oe-init-build-env Firstly, you need the meta-security layer to conf/bblayers.conf along with the dependencies it has -- see the top level meta-security README for that. Note that if you are using dm-verity for your rootfs, then it enforces a read-only mount right at the kernel level, so be prepared for issues such as failed creation of temporary files and similar. Yocto does support additional checks and changes via setting: EXTRA_IMAGE_FEATURES = "read-only-rootfs" ...but since read-only is enforced at the kernel level already, using this feature isn't a hard requirement. It may be best to delay/defer making use of this until after you've established basic booting. For more details, see the associated documentation: https://docs.yoctoproject.org/dev/dev-manual/read-only-rootfs.html Also add the basic block of dm-verity settings shown above, and select your MACHINE from one of the supported platforms. If there is a dm-verity-.txt file for your BSP, check that for any additional platform specific recommended settings, such as the WKS_FILES which can specify board specific storage layout discussed below. Then you should be able to do a "bitbake core-image-minimal" just like any other normal build. What you will notice, is the content in tmp/deploy/images// now have suffixes like "rootfs.ext4.verity" While you can manually work with these images just like any other build, this is where the BSP specific recipes in meta-security/wic can simplify things and remove a bunch of manual steps that might be error prone. Consider for example, the beaglebone black WIC file, which contains: part /boot --source bootimg-partition --ondisk mmcblk0 --fstype=vfat --label boot --active --align 4 --fixed-size 32 --sourceparams="loader=u-boot" --use-uuid part / --source rawcopy --ondisk mmcblk0 --sourceparams="file=${IMGDEPLOYDIR}/${DM_VERITY_IMAGE}-${MACHINE}.${DM_VERITY_IMAGE_TYPE}.verity" bootloader --append="console=ttyS0,115200" As can be seen, it maps out the partitions, including the bootloader, and saves doing a whole bunch of manual partitioning and dd steps. This file is copied into tmp/deploy/images// with bitbake variables expanded with their corresponding values for wic to make use of. Continuing with the beaglebone example, we'll see output similar to: ---------------------- $ wic create -e core-image-minimal beaglebone-yocto-verity [...] INFO: Creating image(s)... INFO: The new image(s) can be found here: ./beaglebone-yocto-verity.wks-202303070223-mmcblk0.direct The following build artifacts were used to create the image(s): BOOTIMG_DIR: /home/paul/poky/build-bbb-verity/tmp/work/beaglebone_yocto-poky-linux-gnueabi/core-image-minimal/1.0-r0/recipe-sysroot/usr/share KERNEL_DIR: /home/paul/poky/build-bbb-verity/tmp/deploy/images/beaglebone-yocto NATIVE_SYSROOT: /home/paul/poky/build-bbb-verity/tmp/work/cortexa8hf-neon-poky-linux-gnueabi/wic-tools/1.0-r0/recipe-sysroot-native INFO: The image(s) were created using OE kickstart file: /home/paul/poky/meta-security/wic/beaglebone-yocto-verity.wks.in ---------------------- The "direct" image contains the partition table, bootloader, and dm-verity enabled ext4 image all in one -- ready to write to a raw device, such as a u-SD card in the case of the beaglebone.