Alkemist by RunSafe

ASRI

SOLUTIONS

GET SUPPORT

RUNSAFE
CODE
Deployment GuideHow it Works
Step 1
Down Arrow Mirrored

Select Install Method

Deployment Option
Deployment Option
Deployment Option
Deployment Option

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
Down Arrow

Select Distribution

Yocto 3.1 (Dunfell)

Need to know your distribution? Run this command in a terminal: cat /etc/centos-release

Step 3
Down Arrow Mirrored

Clone Repos

1# Get the correct branch of the main Yocto Project repo and the corresponding Code branch
2git clone -b dunfell git://git.yoctoproject.org/poky
3cd poky
4git clone -b dunfell git://github.com/runsafesecurity/meta-lfr

The RunSafe-maintained meta-lfr layer contains all of the neccessary configuration files to integrate Code' Load-time Function Randomization (LFR) into a yocto build environment.

Step 4
Down Arrow

Clone Repos

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

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
Down Arrow Mirrored

Prepare Build Environment

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

Step 6
Down Arrow

Clone Repos

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"

The binaries contained in the package provided from LFR_PACKAGE in the step 3 cooridinate with the qemuarm MACHINE target.

Step 7
Down Arrow Mirrored

Build Yocto Image

1bitbake core-image-minimal

This command will build the core-image-minimal image with 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 Code protection using bitbake <recipe/image>.

Step 8
Alkemist Logo

Verify Code Protection

1# Use readelf from the binutils package to check that the section .txtrp has content. The .txtrp section was added by 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 Code were not enabled it would return this error:
15# readelf: Warning: Section '.txtrp' was not dumped because it does not exist!

This shows how to confirm that 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.