You're only a few steps away from deploying Alkemist:Source into your Yocto environment!
1 of 7
Select Yocto Distribution
2 of 7
# Get the correct branch of the main Yocto Project repo and the corresponding Alkemist:Source branchgit clone -b dunfell git://git.yoctoproject.org/pokycd pokygit clone -b dunfell git://github.com/runsafesecurity/meta-lfr
The RunSafe-maintained meta-lfr layer contains all of the neccessary configuration files to integrate Alkemist:Source' Load-time Function Randomization (LFR) into a yocto build environment.
3 of 7
Customize Alkemist:Source layer.conf
# Add the following to meta-lfr/conf/layer.conf# Select the correct lfr package for the target architecture. Currently supports armLFR_PACKAGE= "https://runsafesecurity.jfrog.io/artifactory/yocto/yocto-3.1/lfr-package-armv7vet2hf-neon-qemuarm-3.1.tar.xz"ALKEMIST_LICENSE_KEY= "<insert Alkemist license here>"
The LFR_PACKAGE contains pre-built binaries cross-compiled for different CPU targets. Currently supported is 32-bit ARM with support for 32- and 64-bit Intel and 64-bit ARM coming soon.
Sourcing oe-init-build-env prepares the environment for building yocto recipes and images. Adding meta-lfr to the list of layers will result in all recipes being built with Alkemist:Source protections in place.
5 of 7
Customize Alkemist:Source local.conf
# Contents of conf/local.conf# Machine Selection## You need to select a specific machine to target the build with. There are a selection# of emulated machines available which can boot and run in the QEMU emulator:#MACHINE ?= "qemuarm"#MACHINE ?= "qemuarm64"#MACHINE ?= "qemumips"#MACHINE ?= "qemumips64"#MACHINE ?= "qemuppc"#MACHINE ?= "qemux86"#MACHINE ?= "qemux86-64"
The binaries contained in the package provided from LFR_PACKAGE in the step 3 cooridinate with the qemuarm MACHINE target.
6 of 7
Build Yocto Image
This command will build the core-image-minimal image with Alkemist:Source protections. The resulting image can be run using runqemu qemuarm.
The bitbake command can be run to build other images, or individual recipes with Alkemist:Source protection using bitbake <recipe/image>.
7 of 7
Verify Alkemist:Source Protection
# Use readelf from the binutils package to check that the section .txtrp has content. The .txtrp section was added by Alkemist:Source # This requires that your build system has the binutils package available# readelf -x .txtrp <transformed binary> | grep 0x -m3# For example, to test busybox.suidreadelf -x .txtrp ./tmp/work/qemuarm-poky-linux-gnueabi/core-image-minimal/1.0-r0/rootfs/bin/busybox.suid |grep 0x -m3# This will return data similar to the output below, but with different values# 0x0000200e 01d10b00 4065f0ff ffffffff ff020000 [email protected]# 0x0000201e 0609027c 09047c16 046bf0ff ffffffff ...|..|..k......# 0x0000202e ff020000 0c0d2a7c 072a7c07 2a7c0504 ......*|.*|.*|..# If Alkemist:Source were not enabled it would return this error:# readelf: Warning: Section '.txtrp' was not dumped because it does not exist!
This shows how to confirm that Alkemist:Source has been applied to a given binary using the readelf tool from the binutils package. You must have binutils on your system for it to work, but it is commonly available.