You're only a few steps away from deploying Alkemist:Code into your Yocto environment!
1 of 7
Select Yocto Distribution
2 of 7
0# Get the correct branch of the main Yocto Project repo and the corresponding Alkemist:Code branch1git clone -b dunfell git://git.yoctoproject.org/poky2cd poky3git 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:Code' Load-time Function Randomization (LFR) into a yocto build environment.
3 of 7
Customize Alkemist:Code layer.conf
0# Add the following to meta-lfr/conf/layer.conf1# Select the correct lfr package for the target architecture. Currently supports arm2LFR_PACKAGE= "https://runsafesecurity.jfrog.io/artifactory/yocto/yocto-3.1/lfr-package-armv7vet2hf-neon-qemuarm-3.1.tar.xz"3ALKEMIST_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:Code protections in place.
5 of 7
Customize Alkemist:Code local.conf
0# Contents of conf/local.conf1# Machine Selection2#3# You need to select a specific machine to target the build with. There are a selection4# of emulated machines available which can boot and run in the QEMU emulator:5#6MACHINE ?= "qemuarm"7#MACHINE ?= "qemuarm64"8#MACHINE ?= "qemumips"9#MACHINE ?= "qemumips64"10#MACHINE ?= "qemuppc"11#MACHINE ?= "qemux86"12#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:Code 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:Code protection using bitbake <recipe/image>.
7 of 7
Verify Alkemist:Code Protection
0# Use readelf from the binutils package to check that the section .txtrp has content. The .txtrp section was added by Alkemist:Code 1# This requires that your build system has the binutils package available23# readelf -x .txtrp <transformed binary> | grep 0x -m345# For example, to test busybox.suid6readelf -x .txtrp ./tmp/work/qemuarm-poky-linux-gnueabi/core-image-minimal/1.0-r0/rootfs/bin/busybox.suid |grep 0x -m378# This will return data similar to the output below, but with different values9# 0x0000200e 01d10b00 4065f0ff ffffffff ff020000 [email protected]10# 0x0000201e 0609027c 09047c16 046bf0ff ffffffff ...|..|..k......11# 0x0000202e ff020000 0c0d2a7c 072a7c07 2a7c0504 ......*|.*|.*|..1213# If Alkemist:Code were not enabled it would return this error:14# readelf: Warning: Section '.txtrp' was not dumped because it does not exist!
This shows how to confirm that Alkemist:Code 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.