summaryrefslogtreecommitdiff
path: root/meta-security/docs
diff options
context:
space:
mode:
authorAndrew Geissler <geissonator@yahoo.com>2023-03-31 17:57:23 +0300
committerAndrew Geissler <geissonator@yahoo.com>2023-03-31 18:06:58 +0300
commit2daf84b2d486da0b21344da999553c8fa1228195 (patch)
tree04a2402d258019103ad1a4c9da71d78301cd5d42 /meta-security/docs
parentced6278a187ae9eefe16fe59398f714857b7f76e (diff)
downloadopenbmc-2daf84b2d486da0b21344da999553c8fa1228195.tar.xz
subtree updates: raspberrypi security arm
meta-arm: eb9c47a4e1..9b6c8c95e4: Abdellatif El Khlifi (1): CI: append classes to INHERIT in the common fvp.yml Adam Johnston (1): arm-bsp/linux-yocto: Update N1SDP PCI quirk patch Jon Mason (10): CI: add yml files for defaults CI: add support for dev kernel, rt kernel, and poky-tiny arm-bsp/fvp-base: update to u-boot 2023.01 arm-bsp/fvp-base-arm32: remove support ci: add external-toolchain to qemuarm-secureboot arm-bsp/optee: remove unused recipes arm/optee: optee-os include cleanup arm/optee-os: update to 3.20.0 arm/edk2: update version and relocate edk2-basetools to be with edk2 arm-bsp/fvp-base: Add edk2 build testing Ross Burton (7): arm-bsp/linux-arm64-ack: update Upstream-Status tags CI: add CI_CLEAN_REPOS variable to allow cleaning the repo reference cache arm/scp-firmware: fix up whitespace arm/scp-firmware: enable verbose builds arm/scp-firmware: remove textrel from INSANE_SKIP arm/scp-firmware: improve debug packaging CI: mask poky's llvm if we're using clang Rui Miguel Silva (1): arm-bsp/optee: bump corstone1000 to v3.20 Satish Kumar (1): arm-bsp/corstone1000: new gpt based disk layout and fwu metadata Xueliang Zhong (1): arm-bsp/n1sdp: update to linux yocto kernel 6.1 meta-security: c06b9a18a6..a397a38ed9: Armin Kuster (16): openscap: update to 1.3.6 openscap: update to 1.3.7 openscap git: add DEFAULT_PREFERENCE python3-fail2ban: update to 1.0.2 python3-privacyidea: update to 3.8.1 libhtp: update to 0.5.42 lkrg-modules: update to 0.9.6 chkrootkit: update to 0.57 fscrypt: update to 1.1.0 libmspack: update to 1.11 firejail: update 0.9.72 suricata: update to 6.0.10 apparmor: update to 3.1.3 krill: update 0.12.3 cryptmout: update to 6.2.0 packagegroup-core-security: refactor the inclusion of krill Eero Aaltonen (1): dm-verity-img.bbclass: fix syntax warning Jose Quaresma (3): meta-hardening/layer: lower the priority from 10 to 6 meta-security-compliance/layer: lower the priority from 10 to 6 meta-tpm/layer: lower the priority from 10 to 6 Kevin Hao (1): dm-verity-img.bbclass: Fix the hash offset alignment issue Mikko Rapeli (1): ima-evm-utils: disable documentation from build Paul Gortmaker (3): dm-verity: update beaglebone wic to match meta-yocto dm-verity: add basic non-arch/non-BSP yocto specific settings dm-verity: document board specifics for Beaglebone Black Peter Marko (1): tpm2-tss: correct CVE product meta-raspberrypi: e15b876155..3afdbbf782: Carlos Alberto Lopez Perez (1): mesa-demos: enable build with userland graphics drivers. Khem Raj (6): linux-raspberrypi: Add recipes for 6.1 kernel psplash: Make psplash wait for the framebuffer to be ready rpi-default-versions: Use 6.1 kernel as default gstreamer1.0-plugins-bad: Drop gpl packageconfig rpidistro-ffmpeg: Pin to use gcc always rpidistro-vlc: Fix build with clang16 Signed-off-by: Andrew Geissler <geissonator@yahoo.com> Change-Id: Ie6e60085306d31972098b87738eb550e5140b92a
Diffstat (limited to 'meta-security/docs')
-rw-r--r--meta-security/docs/dm-verity-beaglebone.txt37
-rw-r--r--meta-security/docs/dm-verity.txt114
2 files changed, 151 insertions, 0 deletions
diff --git a/meta-security/docs/dm-verity-beaglebone.txt b/meta-security/docs/dm-verity-beaglebone.txt
new file mode 100644
index 0000000000..5f0caa4ecc
--- /dev/null
+++ b/meta-security/docs/dm-verity-beaglebone.txt
@@ -0,0 +1,37 @@
+dm-verity and beaglebone-black
+------------------------------
+Set/uncomment the MACHINE line for "beaglebone-yocto" if you haven't yet.
+
+In addition to the basic dm-verity settings, you'll also want in local.conf:
+
+IMAGE_BOOT_FILES:remove = "zImage"
+IMAGE_BOOT_FILES:append = " zImage-initramfs-${MACHINE}.bin;zImage"
+WKS_FILES = "${MACHINE}-verity.wks.in"
+
+Read-only issues: The beaglebone BSP by default declares the following:
+
+ SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0 115200;ttyAMA0"
+ SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}"
+
+...which are variables used by sysV init, in order to determine the
+appropriate /etc/inittab entries. The problem that arises is that by
+default, an on-target runtime check of /proc/consoles is used to finalize
+the /etc/inittab -- and of course that fails a build with read-only-rootfs
+[see the pkg_postinst_ontarget rule in the sysvinit rule for details.]
+
+If you don't need a serial console, the quick fix is to add in local.conf
+
+SERIAL_CONSOLES = ""
+
+If you do need/want a serial console, then probably a local bbappend to
+manually set the /etc/inittab as desired is easiest.
+
+After running "wic create -e core-image-minimal beaglebone-yocto-verity"
+you should have a "direct" image ready to write to a u-SD card. Remember
+that the "direct" image contains the bootloader and partition table
+already, so you'll be writing it to a device such as /dev/sdb and not
+just a partition -- like /dev/sdb1
+
+Also recall that booting from u-SD requires pressing and holding the S2
+(SYSBOOT) button during power-on in order to divert the boot from the normal
+soldered on storage and to the removable u-SD card.
diff --git a/meta-security/docs/dm-verity.txt b/meta-security/docs/dm-verity.txt
new file mode 100644
index 0000000000..602a826939
--- /dev/null
+++ b/meta-security/docs/dm-verity.txt
@@ -0,0 +1,114 @@
+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]
+
+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.
+
+Next, assuming you'll be using dm-verity for validation of your rootfs,
+you'll need to enable read-only rootfs support in your local.conf with:
+
+EXTRA_IMAGE_FEATURES = "read-only-rootfs"
+
+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-<MACHINE>.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/<MACHINE>/ 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/<MACHINE>/ 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.