RunSafe Alkemist

ASRI

SOLUTIONS

GET SUPPORT

ALKEMIST

CODE

Deployment Guide How it Works

Step 1

Select Install Method

Choose which install method you would like to see instructions for. Debs work for any debian-based OS such as Debian, Ubuntu, and Mint. RPMS work for any Fedora-based OS such as Fedora, centOS, RHEL, and Rocky Linux.

Step 2

Select Yocto Distribution

Step 3

Clone Repos

1# Get the correct branch of the main Yocto Project repo and the corresponding Alkemist:Code branch
2git clone -b dunfell git://git.yoctoproject.org/poky
3cd poky
4git clone -b dunfell git://github.com/runsafesecurity/meta-lfr
# Get the correct branch of the main Yocto Project repo and the corresponding Alkemist:Code 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:Code' Load-time Function Randomization (LFR) into a yocto build environment.

Step 4

Customize Alkemist:Code layer.conf

1# Add the following to meta-lfr/conf/layer.conf
2# Select the correct lfr package for the target architecture. Currently supports arm
3LFR_PACKAGE = "https://runsafesecurity.jfrog.io/artifactory/yocto/yocto-3.1/lfr-package-armv7vet2hf-neon-qemuarm-3.1.tar.xz"
4ALKEMIST_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.

Step 5

Prepare Build Environment

1# Prepare build environment
2source oe-init-build-env
3# Add meta-lfr layer
4bitbake-layers add-layer ../meta-lfr
# Prepare build environment
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:Code protections in place.

Step 6

Customize Alkemist:Code local.conf

1# Contents of conf/local.conf
2# Machine Selection
3#
4# You need to select a specific machine to target the build with. There are a selection
5# of emulated machines available which can boot and run in the QEMU emulator:
6#
7MACHINE ?= "qemuarm"
8#MACHINE ?= "qemuarm64"
9#MACHINE ?= "qemumips"
10#MACHINE ?= "qemumips64"
11#MACHINE ?= "qemuppc"
12#MACHINE ?= "qemux86"
13#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.

Step 7

Build Yocto Image

1bitbake core-image-minimal
bitbake core-image-minimal

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>.

Step 8

Verify Alkemist:Code Protection

1# Use readelf from the binutils package to check that the section .txtrp has content. The .txtrp section was added by Alkemist:Code 
2# This requires that your build system has the binutils package available
3
4# readelf -x .txtrp <transformed binary> | grep 0x -m3
5
6# For example, to test busybox.suid
7readelf -x .txtrp ./tmp/work/qemuarm-poky-linux-gnueabi/core-image-minimal/1.0-r0/rootfs/bin/busybox.suid | grep 0x -m3
8
9# This will return data similar to the output below, but with different values
10#   0x0000200e 01d10b00 4065f0ff ffffffff ff020000 ....@e..........
11#   0x0000201e 0609027c 09047c16 046bf0ff ffffffff ...|..|..k......
12#   0x0000202e ff020000 0c0d2a7c 072a7c07 2a7c0504 ......*|.*|.*|..
13
14# If Alkemist:Code were not enabled it would return this error:
15# 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:Code 
# 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:Code 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: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.