RunSafe Portal

RUNSAFE

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 Distribution

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

Step 3

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
# Get the correct branch of the main Yocto Project repo and the corresponding 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 Code' Load-time Function Randomization (LFR) into a yocto build environment.

Step 4

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"
4RUNSAFE_LICENSE_KEY = "<insert RunSafe 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"
RUNSAFE_LICENSE_KEY = "<insert RunSafe 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 Code protections in place.

Step 6

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

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!
# Use readelf from the binutils package to check that the section .txtrp has content. The .txtrp section was added by 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 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 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.