1. Overview

  • Andreas Fitzek info
  • Johannes Winter info
  • Daniel Hein info
  • Florian Achleitner
  • hopefully more to come ...
Responsive image

1.1. Introduction

On modern devices all different kind of applications are executed. These include games, browsers, or on-line banking applications. Some of these applications we trust, some we do not. The problem is that both trusted and untrusted applications are executed on the same device and we need to trust our device to protect sensitive informations, like for example our banking credentials. We want to isolate trusted and untrusted applications from one another. Therefore we use domain isolation that separates trusted and untrusted execution environments for applications. We want to enforce domain isolation that not even if it the operating system kernel is compromised, untrusted applications can access sensitive information inside the trusted execution environment.

The ARM TrustZone is a security mechanisms available in many ARM proces sors. It introduces two states into the processor, a secure and a normal state. This can be used to provide hardware backed domain isolation. This thesis describes the development of ANDIX OS, an ARM TrustZone aware operating system. It operates in the secure state of the processor. ANDIX OS protects its own memory resources and peripheral devices from access of the normal state. In the normal state an other operating system is running parallel to ANDIX OS. ANDIX OS supports the execution of Linux and Android in the normal state. Linux and Android perform normal system operations, while ANDIX OS provides a trusted execution environment, which is strongly isolated from the normal world operating system.

ANDIX OS allows the development of Trusted Applications, which are exe cuted in the trusted execution environment. ANDIX OS protects the resources of the Trusted Applications against attacks from the normal world. The se cure and the normal world communicate via a Remote Procedure Call mechanism.

ANDIX OS is a free and open source ARM TrustZone aware operating system. It can be used for all kinds of TrustZone aware development projects, either academic or commercial. ANDIX OS runs on a software emulator and on a low cost hardware platform, because we want it to be as easy as possible to start development with ANDIX OS for other parties. We hope that ANDIX OS drives the research in the field of ARM TrustZone aware systems.

Abstract from: Development of an ARM TrustZone aware operating system ANDIX OS

1.2. A Word of Caution

Development of ANDIX OS is still not complete. It currently is regarded as experimental software targeted at research and educational environments. Use the software at your own risk!

1.3. License

Copyright (c) IAIK, Graz University of Technology, 2014. All rights reserved.

ANDIX OS is released under a dual licensing model:

  • For Open Source development, ANDIX OS is licensed under the terms of the GNU GPL version 2. The full text of the GNU GPL v2 is shipped with the product or can be found online at (GPL).

  • In all other cases, the "Stiftung SIC Java (tm) Crypto-Software Development Kit Licence Agreement" applies. The full license text can be found online at Stiftung SIC. For pricing and further information please contact jce-sales@iaik.at.

2. Download

Master thesis describing ANDIX OS Master Thesis
ANDIX Source CodeAndix 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

Secure worldThe secure partition created by the ANDIX OS
Normal worldThe normal (not specifically secured) partition created by the ANDIX OS
Trusted ApplicationAn application or more often a part of an application running in the secure world userland
Linux host systemThe system where you start QEMU to actually run ANDIX.
ANDIX-Linux-UserlandThe user space of the Linux hosted by ANDIX, i.e. the system where you run applications that use Trusted Applications.
ANDIX-Linux-KernelThe 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@
scp -P 2222 /file/from/host linaro@
sftp -P 2222 linaro@

# You can even mount directories of the virtual ARM system on your host filesystem via "sshfs":
sshfs -p 2222 linaro@ /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.