This repository contains the overall configuration for the Open-TEE project and the associated documentation.
The goal of the Open-TEE open source project is to implement a "virtual TEE" compliant with the recent Global Platform TEE specifications .
Our primary motivation for the virtual TEE is to use it as a tool for developers of Trusted Applications and researchers interested in using TEEs or building new protocols and systems on top of it. Although hardware-based TEEs are ubiquitous in smartphones and tablets ordinary developers and researchers do not have access to it. While the emerging Global Platform specifications may change this situation in the future, a fully functional virtual TEE can help developers and researchers right away.
We intend that Trusted Applications developed using our virtual TEE can be compiled and run for any target that complies with the specifications.
The Open-TEE project is being led by the Secure Systems group as part of our activities at the Intel Collaborative Research Institute for Secure Computing
All activities of the project are public and all results are in the public domain. We welcome anyone interested to join us in contributing to the project.
A minimalistic guide is tested on Ubuntu 20.04 (Focal Fossa). If you run into any errors or need more information, see topics below or raise an issue.
NOTE: We have also a docker envronment!
# prerequisite packages
$ sudo apt-get install -y build-essential git pkg-config uuid-dev libelf-dev wget curl autoconf automake libtool libfuse-dev
# Google repo (skip if you already have it)
$ mkdir -p ~/bin
$ curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod +x ~/bin/repo
# mbedtls 3.1.0: fetch, compile and install
# (Note: Tested with 3.1.0, but 3.x.x version should be sufficient)
# (Note: Currently Apt package contains 2.x.x version)
# (NOTE: If you already have installed mbedtls, update with your own risk and cautions!!)
$ wget https://github.com/ARMmbed/mbedtls/archive/refs/tags/v3.1.0.tar.gz
$ tar -xf v3.1.0.tar.gz && cd mbedtls-3.1.0
$ cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On .
$ make -j && make install
# Clone opentee
$ mkdir opentee && cd opentee
$ ~/bin/repo init -u https://github.com/Open-TEE/manifest.git
$ ~/bin/repo sync -j10
# Build opentee and install (cd into opentee source folder)
# Note: Install location is "/opt/OpenTee"
$ mkdir build && cd build
$ ../autogen.sh
$ make -j && sudo make install
# Generate opentee conf
$ sudo echo -e "[PATHS]\nta_dir_path = /opt/OpenTee/lib/TAs\ncore_lib_path = /opt/OpenTee/lib\nsubprocess_manager = libManagerApi.so\nsubprocess_launcher = libLauncherApi.so" > /etc/opentee.conf
# Run opentee and connection test program
# /opt/OpenTee/bin/opentee
# /opt/OpenTee/bin/conn_test
Docker environment tested on Ubuntu 20.04 (Focal Fossa) and Community docker engine 20.10.12. If you run on other platforms then you might need to adjust docker volumes. Please see tips for streamlining your development/usage
# Prerequisite: Clone opentee source code
# Please see quickstart guide points
# 1. Google repo (skip if you already have it)
# 2. Clone opentee
# Run Docker
$ cd docker
$ ./build-docker.sh
$ ./run-docker.sh
# Inside docker: Compile and run opentee
# Please see quickrstart guide points
# 1. Build opentee and install
# 2. Run opentee and connection test program
a) OpenTEE prints its debug prints to syslog and therefore /dev/log
is mounted. You can read logs from your host machine
b) You can pass "--prefix="-option to autogen.sh and you can
avoid sudo-location installation!
c) Remember to change /etc/opentee.conf file paths if you are
using "--prefix="-option
d) Dockers "--ipc=host"-options allows to connect from outside to
inside container. So you can run opentee deamon inside docker
and your CA can connect it from outside docker container
This guide describes how to obtain and build Open-TEE from source on Ubuntu 14.04 LTS (Trusty Tahr). We currently support building Open-TEE using Autotools.
If you simply wish to build Open-TEE using the suggested configuration, you can also follow the tutorial at:
http://open-tee.github.io/documentation/
If you wish to build Open-TEE for Android, consult the Android specific build documentation at:
http://open-tee.github.io/android
Open-TEE uses the Android repo tool to manage the Git repositories that contain the source code. What follows are step-by-step instructions for setting up the build environment for Open-TEE.
Full documentation for repo is available at https://source.android.com/source/using-repo.html
You'll also need to install git, curl, pkg-config and the necessary build dependencies:
$ sudo apt-get install git curl pkg-config build-essential uuid-dev libssl-dev libglu1-mesa-dev libelfg0-dev mesa-common-dev libfuse-dev
Introduce yourself to git if you haven't done so already:
$ git config --global user.name "Firstname Lastname"
$ git config --global user.email "name@example.com"
Fetch the repo repository management tool:
$ mkdir -p ~/bin
$ curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod +x ~/bin/repo
The Autotools build has been tested with Autoconfig 2.69 and above. To perform an Autotools build you need to install autoconf, automake and libtool:
$ sudo apt-get install autoconf automake libtool
Create a directory where the repositories are to be cloned:
$ mkdir Open-TEE
$ cd Open-TEE
Have repo fetch the manifest for the Open-TEE project:
$ ~/bin/repo init -u https://github.com/Open-TEE/manifest.git
Those wishing to contribute to Open-TEE need signup to the GerritHub Code Review tool (requires a GitHub account) and initialize repo using the the developer configuration:
$ ~/bin/repo init -u https://github.com/Open-TEE/manifest.git -m developer.xml
To submit changes to GerritHub you'll also need to add the following to your ~/.ssh/config:
host review.gerrithub.io
port 29418
user
Have repo fetch the repositories defined in the manifests:
$ ~/bin/repo sync -j10
Once cloned, you can work on the repositories in a normal git fashion. Developers wishing to contribute can push changes ro Gerrit for review using the following command:
$ git push origin HEAD:refs/for/master
We recommend using a parallel build tree (a.k.a. VPATH build):
$ mkdir build
The provided autogen.sh script will generate and run the configure script.
$ cd build
$ ../autogen.sh
To build and install Open-TEE run:
$ make
$ sudo make install
By default Open-TEE will be installed under /opt/Open-TEE. The directory will contain the following subdirectories:
-
/opt/Open-TEE/bin- executables -
/opt/Open-TEE/include- public header files -
/opt/Open-TEE/lib- shared library objects (libdir) -
/opt/Open-TEE/lib/TAs- trusted application objects (tadir)
Open the configuration file with your preferred editor:
$ sudo $EDITOR /etc/opentee.conf
Add the sample configuration given below to the configuration file:
[PATHS]
ta_dir_path = PATH/TO/TADIR
core_lib_path = PATH/TO/LIBDIR
subprocess_manager = libManagerApi.so
subprocess_launcher = libLauncherApi.so
where PATHNAME is replaced with the absolute path to the parent directory of the Open-TEE directory you created earlier. The pathname must not include special variables such as ~ or $HOME.
For an autotools build you can use
[PATHS]
ta_dir_path = /opt/OpenTee/lib/TAs
core_lib_path = /opt/OpenTee/lib
subprocess_manager = libManagerApi.so
subprocess_launcher = libLauncherApi.so
You are now ready to launch the opentee-engine.
For an autotools build:
$ /opt/Open-TEE/bin/opentee-engine
Verify that Open-TEE is running with ps:
$ ps waux | grep tee
You should see output similar to the example below:
gcc-debug$ ps waux |grep tee
brian 5738 0.0 0.0 97176 852 ? Sl 10:40 0:00 tee_manager
brian 5739 0.0 0.0 25216 1144 ? S 10:40 0:00 tee_launcher
Now launch and attach gdb to the tee_launcher process:
$ gdb -ex "set follow-fork-mode child" opentee-engine $(pidof tee_launcher)
The set follow-fork-mode child command passed to gdb on the command line causes gdb to follow children processes across forks in order to drop into the TA process itself and resume execution.
In second terminal run the client application:
$ /opt/Open-TEE/bin/conn_test_app
You should now expect to see output similar to the following:
./conn_test_app
START: conn test app
Initializing context:
Back in gdb you can now step through and debug the trusted application the conn_test_app is connected to. If you continue execution you should see output from the conn_test_app similar to the following:
gcc-debug$ ./conn_test_app
START: conn test app
Initializing context: initialized
Openning session: opened
yyyyyyyyyyyyyyyyyyyyxxxxx
Invoking command: invoked
Closing session: Closed
Finalizing ctx: Finalized
END: conn test app
The opentee-engine executable supports the following command line options:
Usage: ./bin/opentee-engine [OPTION...]
-
-p,--pid-dir=PATH
Specify path to keep pid file.
Defaults to:/var/run/openteewhen run by root, or/tmp/opentee whenrun by a non-root user.
-
-c,--config=FILE
Specify path to configuration file.
Defaults to:/etc/opentee.conf -
-f,--foreground
Do not daemonize but start the process in foreground. -
-h,--help
Print list of command line options.
The following environmental variables control the behaviour of Open-TEE:
-
OPENTEE_SOCKET_FILE_PATH
Defines path to socket used for communication betweentee_managerandlibtee.
Defaults to/tmp/open_tee_sockon Linux
Defaults to/data/local/tmp/open_tee_sockon Android -
OPENTEE_STORAGE_PATH
Defines directory used for object storage.
Defaults to$HOME/.TEE_secure_storageon Linux
Defaults to/dataon Android
If you get the following error when trying to attach gdb to tee_launcher:
Could not attach to process. If your uid matches the uid of the target
process, check the setting of /proc/sys/kernel/yama/ptrace_scope, or try
again as the root user. For more details, see /etc/sysctl.d/10-ptrace.conf
ptrace: Operation not permitted.
Run the following command and invoke gdb again:
$ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
Bug reports and other issues:
Open-TEE is licensed under the Apache License 2.0 (see LICENSE).