1. Overview

2. Download

Name	Link
Master thesis describing ANDIX OS	Master Thesis
ANDIX Source Code	Andix Source Code (still in alpha stage)
Hello World Trusted Application (as used in this course)	Hello World Trusted Application
Calculator Trusted Application (as used in this course)	Calculator Trusted Application
Bootscripts (as used in this course)	Bootscripts

3. Getting startet

3.1. Definitions

Term	Meaning
Secure world	The secure partition created by the ANDIX OS
Normal world	The normal (not specifically secured) partition created by the ANDIX OS
Trusted Application	An application or more often a part of an application running in the secure world userland
Linux host system	The system where you start QEMU to actually run ANDIX.
ANDIX-Linux-Userland	The user space of the Linux hosted by ANDIX, i.e. the system where you run applications that use Trusted Applications.
ANDIX-Linux-Kernel	The kernel space of the Linux hosted by ANDIX, i.e. the system kernel of the normal world OS

3.2. Introduction

ANDIX is an ARM TrustZone based security kernel that allows create applications that at least in part run in a trusted execution environment. To test such applications we need to first set up ANDIX. This document explains how to set up ANDIX on a Linux system.

3.3. Software requirements

Building the ANDIX environment should work on any recent Linux distribution. You may, however, have to install a number of additional packages that are not part of your standard distro. At least you will need the following tools on your host:

• GCC, make, cmake, binutils for your host platform * (except for cmake you probably have already all required tools)
• An ARM cross-compiler toolchain for the normal world user-space on the virtual ARM system
  • You are looking for an arm-linux-gnueabihf toolchain..
  • The root file-system (see below) for the virtual ARM system has been successfully tested with a GCC 4.8.2 based normal-world toolchain. The exact version was:

    fuzzy@vm:~$ arm-linux-gnueabihf-gcc --version
arm-linux-gnueabihf-gcc (Ubuntu/Linaro 4.8.2-16ubuntu4) 4.8.2

On an Ubuntu based host-system you probably can get away with a simple apt-get install gcc-defaults-armhf-cross. If this doesn't work for you (incompatible wrong toolchain version, now packages) check out the normal Toolchain from the Linaro 12.06 release.

On Debian 8 you need to you have to follow this guide https://wiki.debian.org/CrossToolchains to add cross-toolchain support. Afterwards you can install the needed packages with sudo apt-get install cross-gcc-dev crossbuild-essential-armhf tree. You also need to install the following packages: sudo apt-get install cmake ccache pkg-config zlib1g-dev libsdl1.2-dev libpixman-1-dev TODO: Check for these packages in the Makefile target check

3.3.1. Alternative setup (w/o distribution packages)

The alternative setup steps should ONLY be used if your host Linux distribution does not provide a suitable cross-compile toolchain.

We recommend to use the Linaro 12.06 tarballs, if you don not want or cannot to install your distributions cross-compiler packages (Assumption: You have already created the /opt/andix directory). A simple solution to "install" the Linaro arm-linux-gnueabihf toolchain without touching the remainder of your system is to unpack the Linaro tarball into your /opt/andix/bin directory:

wget -O linaro-arm-linux-gnueabihf.tar.bz2 http://releases.linaro.org/12.06/components/toolchain/binaries/gcc-linaro-arm-linux-gnueabihf-2012.06-20120625_linux.tar.bz2
tar -C /opt/andix --strip-components=1 -xvjf linaro-arm-linux-gnueabihf.tar.bz2

Next create a file called /opt/andix/src/kernel/script/config.local with exactly the following content (Note that the trailing / is relevant).

ARM_NORM_TOOLCHAIN_DIR := /opt/andix/bin/

Finally you need to disable the prerequisite check for the arm-linux-gnueabihf-gcc compiler in the /opt/andix/src/Makefile top-level Makefile. Open the Makefile in a text-editor and comment out (or delete) the $(call check_shell_command,arm-linux-gnueabihf-gcc) near the end of the file.

3.4. Preparing the ANDIX Directory

Within the remainder of this tutorial we assume that your "base" directory resides directly below your Linux root directory in /opt/andix. You can create the /opt/andix directory in case that you don't have it yet as:

# Create the ANDIX directory
sudo mkdir /opt/andix

# Set ownership to your primary non-root user (replace "$(whoami)" with your username)
sudo chown $(whoami) /opt/andix


Source files and repositories of the ANDIX distribution go into subdirectories of /opt/andix/src. In following steps we will prepare the actual ANDIX kernel tree, the ANDIX newlib port, the Linux kernel for normal world use, a modified version of QEMU, and the root filesystem.

3.5. Getting the source

Download the source code the section Downloads and extract it into /opt/andix/src.

To make live a little bit easier for you, we have included a top-level Makefile that provides targets to automate some of these steps. The simplest way to build the pre-requisites for ANDIX is to run the following command (and go for lunch):

make -C /opt/andix/src check
make -C /opt/andix/src prepare

During the make prepare step the build script will fetch the source of required external components (sources for the GCC cross-compiler, Linux kernel sources, ...) over the Internet, so an online connection is generally required until make prepare has been completed.

Large parts of the build process can be parallelized on multiple CPUs. To run the preparation step with N-1 cores, simple invoke make prepare with the -jN option. So if you have two (2) processor core a typical invocation would be: make -j3 -C /opt/andix/src prepare

The root filesystem image that we use in the exercises is based on Ubuntu/Linaro release 12.06 for the ARM Versatile Express Board (with Cortex-A9 coretile). You can find all information to roll your own image from scratch on the Linaro releases site.

You can mount the root-file system of your virtual ARM platform on your host Linux machine, using loop mounts or QEMU's NBD (Network Block Device) daemon. See the QEMU wikibook for a good description of the required commands.

TODO: rootfs, Linux kernel, example (need to document that for reference)

3.6. Interacting with your ANDIX System

After a successful "make prepare" it is quite easy to fire up your shiny new ANDIX system. You just have to do a:

make -C /opt/andix/src qemu

the make qemu target configures port-forwarding from your host-side TCP port 2222 to port 22 of the virtual ARM system inside QEMU. You can install the OpenSSH? server package inside your virtual ARM machine (apt-get install openssh-server) to setup a simple method for file transfer and command exchange.

After you have installed the OpenSSH? server inside your virtual ARM environment, it can be reached from the outside using:

# Using the standard "linaro" user (password: "linaro")
ssh -p 2222 linaro@127.0.0.1
scp -P 2222 /file/from/host linaro@127.0.0.1:/file/on/guest
sftp -P 2222 linaro@127.0.0.1

# You can even mount directories of the virtual ARM system on your host filesystem via "sshfs":
sshfs -p 2222 linaro@127.0.0.1:/path/on/virtual/system /mountpoint/on/my/host

# To unmount a directory mounted with sshfs you can typically use "fusermount" as regular user:
fusermount -u /mountpoint/on/my/host

You can apply the hello world trustlet GIT patch (via git am) to your spic2015gX working repository to import a simple hello world skeleton trustlet.

3.7. Deploying the ANDIX runtime libraries (and the Trustlet loader)

To actually interact with your ANDIX TEE from within the virtual ARM Linux normal-world environment you have to copy some files from the ANDIX "deploy" directory to your virtual ARM system.

Probably the simplest solution is to install an SSH server on your virtual ARM system, to create the "/deploy" directory with proper file permission, and to use the "rsync" tool for file exchange.

To prepare the "/deploy" folder of your virtual ARM system run the following commands (at least once) inside the (QEMU) simulated environment:

root@linaro-nano:~# mkdir /deploy
root@linaro-nano:~# chown -R linaro /deploy
root@linaro-nano:~# apt-get install openssh-server rsync


After you have compiled the ANDIX kernel, you can then easily sync the "/deploy" folder using the following command (on your host system):

rsync -e "ssh -p 2222" -av --delete /opt/andix/src/kernel/deploy/ linaro@localhost:/deploy/

3.7.1. Loading the normal world components

To interact with the ANDIX TEE you additional have to load the normal world kernel module, and to properly set the LD_LIBRARY_PATH variable of your ANDIX TEE.

To load the kernel module you can manually by run:

root@linaro-nano:~# insmod /deploy/norm/module/andixtee.ko
root@linaro-nano:~# ln -s /dev/andixtee /dev/andixtee0

To set the correct LD_LIBRARY_PATH in your current shell you can run:

root@linaro-nano:~# export LD_LIBRARY_PATH=/deploy/norm/lib:${LD_LIBRARY_PATH}

Please note that the existing scripts in the /deploy/scripts directory are currently broken due to a change in the way how the Linux kernel module registers itself.