1dm-verity and Yocto/OE 2---------------------- 3The dm-verity feature provides a level of data integrity and resistance to 4data tampering. It does this by creating a hash for each data block of 5the underlying device as the base of a hash tree. There are many 6documents out there to further explain the implementaion, such as the 7in-kernel one itself: 8 9https://docs.kernel.org/admin-guide/device-mapper/verity.html 10 11The goal of this document is not to reproduce that content, but instead to 12capture the Yocto/OE specifics of the dm-verity infrastructure used here. 13 14Ideally this should enable a person to build and deploy an image on one of 15the supported reference platforms, and then further adapt to their own 16platform and specific storage requirements. 17 18Basic Settings 19-------------- 20Largely everything is driven off of a dm-verity image class; a typical 21block of non MACHINE specific settings are shown below: 22 23INITRAMFS_IMAGE = "dm-verity-image-initramfs" 24DM_VERITY_IMAGE = "core-image-minimal" 25DM_VERITY_IMAGE_TYPE = "ext4" 26IMAGE_CLASSES += "dm-verity-img" 27INITRAMFS_IMAGE_BUNDLE = "1" 28 29Kernel Configuration 30-------------------- 31Kernel configuration for dm-verity happens automatically via IMAGE_CLASSES 32which will source features/device-mapper/dm-verity.scc when dm-verity-img 33is used. [See commit d9feafe991c] 34 35Supported Platforms 36------------------- 37In theory, you can use dm-verity anywhere - there is nothing arch/BSP 38specific in the core kernel support. However, at the BSP level, one 39eventually has to decide what device(s) are to be hashed, and where the 40hash tables are stored. 41 42To that end, the BSP storage specifics live in meta-security/wic dir and 43represent the current set of example configurations that have been tested 44and submitted at some point. 45 46Getting Started 47--------------- 48This document assumes you are starting from the basic auto-created 49conf/local.conf and conf/bblayers.conf from the oe-init-build-env 50 51Firstly, you need the meta-security layer to conf/bblayers.conf along with 52the dependencies it has -- see the top level meta-security README for that. 53 54Next, assuming you'll be using dm-verity for validation of your rootfs, 55you'll need to enable read-only rootfs support in your local.conf with: 56 57EXTRA_IMAGE_FEATURES = "read-only-rootfs" 58 59For more details, see the associated documentation: 60 61https://docs.yoctoproject.org/dev/dev-manual/read-only-rootfs.html 62 63Also add the basic block of dm-verity settings shown above, and select 64your MACHINE from one of the supported platforms. 65 66If there is a dm-verity-<MACHINE>.txt file for your BSP, check that for 67any additional platform specific recommended settings, such as the 68WKS_FILES which can specify board specific storage layout discussed below. 69 70Then you should be able to do a "bitbake core-image-minimal" just like any 71other normal build. What you will notice, is the content in 72tmp/deploy/images/<MACHINE>/ now have suffixes like "rootfs.ext4.verity" 73 74While you can manually work with these images just like any other build, 75this is where the BSP specific recipes in meta-security/wic can simplify 76things and remove a bunch of manual steps that might be error prone. 77 78Consider for example, the beaglebone black WIC file, which contains: 79 80part /boot --source bootimg-partition --ondisk mmcblk0 --fstype=vfat 81--label boot --active --align 4 --fixed-size 32 --sourceparams="loader=u-boot" --use-uuid 82part / --source rawcopy --ondisk mmcblk0 --sourceparams="file=${IMGDEPLOYDIR}/${DM_VERITY_IMAGE}-${MACHINE}.${DM_VERITY_IMAGE_TYPE}.verity" 83bootloader --append="console=ttyS0,115200" 84 85As can be seen, it maps out the partitions, including the bootloader, and 86saves doing a whole bunch of manual partitioning and dd steps. 87 88This file is copied into tmp/deploy/images/<MACHINE>/ with bitbake 89variables expanded with their corresponding values for wic to make use of. 90 91Continuing with the beaglebone example, we'll see output similar to: 92 93 ---------------------- 94$ wic create -e core-image-minimal beaglebone-yocto-verity 95 96[...] 97 98INFO: Creating image(s)... 99 100INFO: The new image(s) can be found here: 101 ./beaglebone-yocto-verity.wks-202303070223-mmcblk0.direct 102 103The following build artifacts were used to create the image(s): 104 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 105 KERNEL_DIR: /home/paul/poky/build-bbb-verity/tmp/deploy/images/beaglebone-yocto 106 NATIVE_SYSROOT: /home/paul/poky/build-bbb-verity/tmp/work/cortexa8hf-neon-poky-linux-gnueabi/wic-tools/1.0-r0/recipe-sysroot-native 107 108INFO: The image(s) were created using OE kickstart file: 109 /home/paul/poky/meta-security/wic/beaglebone-yocto-verity.wks.in 110 ---------------------- 111 112The "direct" image contains the partition table, bootloader, and dm-verity 113enabled ext4 image all in one -- ready to write to a raw device, such as a 114u-SD card in the case of the beaglebone. 115