RunSafe Alkemist

You're only a few steps away from deploying Alkemist:Source into your Yocto environment!

1 of 7

Select Yocto Distribution

2 of 7

Clone Repos

# Get the correct branch of the main Yocto Project repo and the corresponding Alkemist:Source branch
git clone -b dunfell git://git.yoctoproject.org/poky
cd poky
git clone -b dunfell git://github.com/runsafesecurity/meta-lfr# Get the correct branch of the main Yocto Project repo and the corresponding Alkemist:Source branch
git clone -b dunfell git://git.yoctoproject.org/poky
cd poky
git 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 arm
LFR_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>"# Add the following to meta-lfr/conf/layer.conf
# Select the correct lfr package for the target architecture. Currently supports arm
LFR_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.

4 of 7

Prepare Build Environment

# TODO: put something here
source oe-init-build-env
# Add meta-lfr layer
bitbake-layers add-layer ../meta-lfr# TODO: put something here
source oe-init-build-env
# Add meta-lfr layer
bitbake-layers add-layer ../meta-lfr

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"# 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

bitbake core-image-minimalbitbake core-image-minimal

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.suid
readelf -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 ....@e..........
#   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!# 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.suid
readelf -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.