IAIK/OpenTC jTSS Wrapper - TSS Wrapper for the Java (tm) Platform

Trusted Computing, as specified by the Trusted Computing Group (TCG, http://www.trustedcomputinggroup.org/), comprises multiple layers of hard and software. While the hardware consists of the Trusted Platform Module (TPM) and related trusted building blocks, the main software components include the TPM hardware driver and a Trusted Software Stack (TSS). This TSS is typically developed in pure C and can therefore not directly be used from other languages such as Java (tm). For that reason, the IAIK/OpenTC jTSS Wrapper provides language bindings for Java (tm). The goal is to make the Trusted Service Provider Interface (TSPI) layer of the TSS stack available to Java (tm) developers, by wrapping a complete, functional system stack with a Java (tm) interface.

Development of the IAIK/OpenTC jTSS Wrapper is supported by the European Commission as part of the OpenTC project (Ref. Nr. 027635). For more information about the OpenTC project please refer to the OpenTC Project section below.

The IAIK/OpenTC jTSS Wrapper is developed and maintained at the Institute for Applied Information Processing and Communication (Institut fuer Angewandte Informationsverarbeitung und Kommunikation, IAIK, http://www.iaik.tugraz.at/) at Graz University of Technology (http://www.tugraz.at/).

The Open Trusted Computing (OpenTC) consortium is an R&D project focusing on the development of trusted and secure computing systems based on open source software. The project targets traditional computer platforms as well as embedded systems such as mobile phones.

The goal of OpenTC is to reduce system-related threats, errors and malfunctions. The lack of platform security in today's computers has given rise to waves of successful attacks, resulting in severe damages to enterprises and potential failure of critical infrastructures.

The OpenTC consortium will define and implement an open Trusted Computing framework. The architecture is based on security mechanisms provided by low level operating system layers with isolation properties and interfaces to Trusted Computing hardware. These layers make it possible to leverage enhanced trust and security properties of the platform for standard operating systems, middleware, and applications.

For more information about the OpenTC project please refer to http://www.opentc.net/.

When experimenting with a real TPM, please keep in mind that the IAIK/OpenTC jTSS Wrapper is currently experimental software. If you are using your TPM in a real production environment, the use of the IAIK/OpenTC jTSS Wrapper is discouraged. No guarantees for data protected by the TPM can be made. Use the software at your own risk!

The IAIK/OpenTC jTSS Wrapper is using a dual licensing model:

• For Open Source development, the IAIK/OpenTC jTSS Wrapper 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: http://www.gnu.org/licenses/gpl.html

• 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: http://jce.iaik.tugraz.at/sic/sales/licences/commercial. For pricing and further information please contact mailto:jce-sales@iaik.at.

Since version 0.3, IAIK/OpenTC jTSS Wrapper is no longer a standalone package but it is an addon to the IAIK jTSS. IAIK jTSS is a TSS completely written using the Java (tm) programming language while IAIK/OpenTC jTSS Wrapper provides Java (tm) bindings for the TrouSerS TSS. To make switching between the wrapper and the full Java (tm) stack as simple as possible, both packages have to use the same API (TSP interface or TSPI). For that reason, IAIK/OpenTC jTSS Wrapper version 0.3 was modified to use the same top level API as the IAIK jTSS. As a consequence, applications developed for older version of IAIK/OpenTC jTSS Wrapper have to be modified to work with the new API. A porting guide is included with IAIK/OpenTC jTSS Wrapper that provides all required information for application porting.

This section deals with the technical aspects of the IAIK/OpenTC jTSS Wrapper. After outlining the basic architecture, this section deals with the requirements and the installation procedure.

Development of the IAIK/OpenTC jTSS Wrapper is done under Linux using IBM's TrouSerS TSS stack (http://trousers.sourceforge.net/) and hardware TPMs as well as the TPM Emulator from ETH Zuerich (https://developer.berlios.de/projects/tpm-emulator/). Since all software components are publicly available they provide an ideal playground for everyone who is interested in getting a "hands on" experience with Trusted Computing even if there is no hardware TPM available.

The following sections will also provide some instructions about how to install the TPM Emulator and the TrouSerS TSS stack.

6.1. Current Status

The IAIK/OpenTC jTSS Wrapper is currently considered almost feature complete with respect to the TSS 1.1 specification. That means that the TSPI layer of the TSS stack (TrouSerS) is fully made available to Java (tm) developers in an object oriented fashion. The only missing parts are the callback functions Tspicb_*. Those callback functions are not required to make full use of the TSS as they only provide a mechanism to customize the behavior of the TSS.

6.2. Architecture

The following table provides an outline of the architecture of IAIK/OpenTC jTSS Wrapper. The layers are described from the lowest layer, the TPM, upwards.

6.3. External Requirements

TSS Stack

As stated earlier, IAIK/OpenTC jTSS Wrapper was developed using IBM's TrouSerS TSS stack. At the time of this writing, TrouSerS is the only publicly available TSS stack for Linux. As a consequence, TrouSerS is a requirement to use the IAIK/OpenTC jTSS Wrapper. In theory, any other TSS stack that complies with the TCG specifications should work as well. However, this has not yet been tested and any feedback on this topic would be welcome. From IAIK/OpenTC jTSS Wrapper ver. 0.3 onwards at least TrouSerS 0.2.9 is required.

Hardware TPM or TPM Emulator

For development, a software TPM emulator as well as hardware TPMs have been used. Any hardware TPM should be supported, as long as a Linux Kernel driver is available for the TPM and the driver conforms with the interface expected by TrouSerS.

Java (tm) JRE 1.5 or above

The IAIK/OpenTC jTSS Wrapper was developed for JRE 1.5 and above. Moreover, unlimited strength encryption has to be enabled in the JRE. For more information refer to: http://java.sun.com/j2se/1.5.0/download.jsp#docs. If you see an error message like Illegal key size or default parameters this is an indication that unlimited strength encryption is not enabled on your system.

IAIK jTSS TSP library

Since IAIK/OpenTC jTSS Wrapper and the IAIK jTSS share the same top level API, the IAIK jTSS TSP library is required to use IAIK/OpenTC jTSS Wrapper. IAIK jTSS can be downloaded from http://trustedjava.sf.net/. The IAIK jTSS TSP library (iaik_jtss_tsp.jar) can be found in the lib folder. It has to be copied into the ext_libs folder of the IAIK/OpenTC jTSS Wrapper.

GCC Toolchain

To compile the native C part of the JNI interface, a C compiler and linker is required. GCC is usually a part of Linux distributions.

SWIG (optional)

If you want to re-create the C and Java (tm) JNI glue code SWIG is required. Note that IAIK/OpenTC jTSS Wrapper already comes with pre-generated JNI glue code. In many cases, SWIG can be installed using the package management of your Linux Distribution.

JUnit (optional)

JUnit is required if you want run the test cases provided with the IAIK/OpenTC jTSS Wrapper package. JUnit can be downloaded from http://www.junit.org/.

6.4. Compiling and Installing

This section will guide you through the build and installation process. It covers the TPM Emulator from ETH, the TrouSerS TSS stack and finally the IAIK/OpenTC jTSS Wrapper.

6.5. Building and Installing the TPM Emulator

If you have a hardware TPM you can skip this step (but you have to make sure that you have a hardware driver installed for your TPM that is compatible with TrouSerS).

• download the sources (v0.5 or above) from: https://developer.berlios.de/projects/tpm-emulator/

• unpack the sources: tar zxf tpm_emulator-0.5.tar.gz

• enclosed you will find a README file that describes the next steps

• build and install the TPM emulator according to the README

6.6. Building and Installing the TrouSerS TSS stack

• download the sources (v0.2.9.0 or v0.2.9.1) from: http://trousers.sourceforge.net/

• Note: this release is not compatible with TrouSerS 0.3.x.

• unpack the sources: tar zxf trousers-0.2.9.tar.gz

• enclosed you will find a README file that describes the next steps

• if you use a TPM version 1.2 you need to apply IAIK's TPM 1.2 Patch for TrouSerS 0.2.9 before building. It is available from the http://trustedjava.sf.net/.

• build and install the TrouSerS TSS stack according to the README

6.7. Building and Installing the IAIK/OpenTC jTSS Wrapper

This section provides a step by step guide of the build process of the "partially prebuilt" version of the IAIK/OpenTC jTSS Wrapper.

unpack the source and change into the source folder +tar jxf jTssWrapper_0.3.tar.bz2 +cd jTssWrapper_0.3
customizing the Makefile: Open the Makefile with your favorite text editor and customize the following options:

• JDK_INC_PATH has to point to the include folder of your JDK

• GCC has to point to your C compiler (typically gcc is already installed on most Linux distributions)

• LD has to point to your linker

Now save and close the Makefile.

building the native library with +make

note: For linking, it is assumed that the libtspi library of TrouSerS is located in a path known to your linker. Otherwise you might want to set the LD_LIBRARY_PATH environment variable accordingly.

note: you can re-generate the prebuilt swig interface with make full.

At this point you should now have a file called libtspiwrapper.so in the output/lib folder. For testing the setup, please proceed to the Testing the Setup section below.

6.8. IAIK jTSS TSP Library

Please ensure that you have downloaded the IAIK jTSS TSP library (see External Requirements). The IAIK jTSS TSP library has to be copied from the lib folder of the IAIK jTSS to the ext_libs folder of the IAIK/OpenTC jTSS Wrapper.

6.9. Testing the Setup

The IAIK/OpenTC jTSS Wrapper is shipped together with a set of unit tests which can be found in the tsp_tests folder. The unit test come already as a jar. This section describes how to start the individual components to be able to run the unit tests. It is assumed that the TPM emulator is used. If you are using a hardware TPM simply skip the steps involving the emulator.

WARNING: If you are not using the TPM emulator, please note that the jUnit tests include also test code for the TakeOwnership operation where an owner password (for instance "opentc") is set. The TakeOwnership operation will fail if there is already an owner set. It is generally NOT recommended to run the test suite on a TPM that is actually used in a production system with sensitive data protected by the TPM.

Before the unit tests can be run, the TPM emulator Kernel module has to be loaded:

modprobe tpmd_dev

In the next step start the userspace part of the TPM Emulator:

tpmd -f clear

Please note, that it might be required to unload TPM hardware drivers loaded by your distribution since they might conflict with your distribution.

After loading the emulator, a new device node /dev/tpm should show up. Depending on distribution, you might need to create the following symlink to make the TrouSerS TSS work with the emulator:

ln -s /dev/tpm /dev/tpm0

As a next step, the Trusted Core Services Daemon tcsd of the TrouSerS TSS has to be started (-f for foreground):

tcsd -f

The tcsd binary is assumed to be located in the PATH of your shell.

Finally, to start the unit tests change into the IAIK/OpenTC jTSS Wrapper folder and enter the following command:

make run_tests

This will run the JUnit test suit. If all goes well, the test run should conclude with a statement like: OK (52 tests).

In case you want to clear the persistent storage of the TrouSerS TSS (which might happen from time to time when doing tests and development), you have to delete the following file (default location):

/usr/local/var/lib/tpm/system.data

6.10. Summary of components

This section presents a summary of the of the most important parts of the IAIK/OpenTC jTSS Wrapper distribution.

• src_tsp: source of the object oriented API

• src_tsp_test: JUnit test code

• output/jars: JAR archives of the lowlevel JNI classes (iaik_jtss_wrapper_swig.jar), the highlevel object oriented API classes (iaik_jtss_wrapper.jar) and test classes (iaik_jtss_wrapper_test.jar).

• output/lib: native library (libtspiwrapper.so)

• output/javadoc_highlevel: JavaDoc of the highlevel API

IAIK/OpenTC jTSS Wrapper distribution comes together with a JavaDoc type documentation which can be found in the output/javadoc_highlevel folder.

A good starting point for further reading is the TSS 1.1b specification at http://www.trustedcomputinggroup.org/ where all TSS functions are described. As far as the IAIK/OpenTC jTSS Wrapper is concerned, the relevant parts are the general sections of the document and the parts detailing the Tspi_* functions.

A good place to get started with the IAIK/OpenTC jTSS Wrapper are the JUnit tests provided in the highlevel_tests folder.

This software is provided "as is". However, a mailing list mailto:trustedjava-support@lists.sourceforge.net is maintained at http://trustedjava.sf.net/ to assist users and to allow users to help each other. You are invited to join the discussion, but kindly take a look at the mailing list archive before posting a question.

These features are purely experimental, not throughly tested and NO support whatsoever can be provided.

• Experimental support for compilation to native code with GCJ. This can be useful for debugging the JNI interface and the underlying stack with standard tools like GDB or valgrind.

• Experimental support for Infineon's TSS implementation. Note that this stack currently is NOT available to the public.

• Hans Brandl (Infineon) for providing a mainboard with an 1.1b TPM.

• Georg Rankl (Infineon) for answering numerous TPM related questions.

• Kent Yoder (IBM) for discussions and answers regarding the TSS.

The copyright for contents of the IAIK/OpenTC jTSS Wrapper package, including all related documentation, is owned by IAIK, Graz University of Technology.

Java (tm) and all Java (tm) based marks are a trademark or registered trademark of Sun Microsystems, Inc, in the United States and other countries. All other trademarks and copyrights are property of their respective owners.