Skip to main content
This revision made September 01, 2011 17:01, by ronaldtoegl


Getting Started with JSR321: A Guide

This tutorial will enable you to write Trusted Computing enabled software for Java using and testing JSR321 based on IAIK's reference implementation. Specifically, it will guide you to

  • Find out about the basics of Trusted Computing in Java
  • Configure Java
  • Configure IAIK jTSS system service on Windows and Linux
  • Configure the IAIK JSR321 reference implementation
  • Include the JSR321 API in your Java Application
  • Write your first JSR321 program
  • Execute the JSR321 Technology Compatibility Kit for testing compliance to the API specifications.

This guide is written for Windows Vista and later and derivate of Debian Linux.

Table of Contents



System Architecture of the JSR321 Reference Implementation

In this section we provide an Overview of the system architecture of the reference implementation. The following components are needed.

  • A modern computer plattform (usually PC) with hardware TPM and BIOS support for the TPM. TPMs from several vendors and with different firmware versions are available. The hardware TPM should be according to TCG version 1.2 of the specifications.
  • An operating system with TPM driver. We assume either Windows (Vista or higher) or Linux. 32-bit and 64-bit versions are both supported.
  • A Java Runtime Environment or Java Development Kit version 1.5 or higher. 32-bit or 64-bit. JREs usually ship with an implementation of the Javy Cryptography Extension (JCE).
  • IAIK jTSS as TPM Management component. The Core Services must be running in the background.
  • Based on jTSS, IAIK has created a Reference Implementation of JSR321.
  • It implements the JSR321 API, which is subject to standardization.
  • Any Java application may then use the JSR321 API to interact with the TPM.
  • One such application is the JSR321 Technology Compatibility Kit, a test suite that covers the full API.

We will now walk you through all layers and show you how to configure your system for JSR321. Please follow all steps in the provided order, as each component depends its predecessor!

Install Java and Enable Strong Cryptography

Install a Java Runtime Environment, or even better a Java Development Kit version 1.5 or higher. Make sure that you can call java on your command console; else add the JRE's bin directory it to your path. To make full use of the cryptographic capabilities of the JCE, the Unlimited Strength Jurisdiction Policy Files may need to be installed. This is a requirement for jTSS to be able to handle some TPM RSA keys. In case you experience errors like "Illegal key size or default parameters" chances are high that these policy files are not (or not correctly) installed.

Turn your TPM On

First you need to turn on the TPM, as it usually ships in a deactivated mode. Computer manufacturers and Microsoft provide detailed how-to instructions to enable and use the TPM. In general, you need to boot into the BIOS, and enable the TPM chip there. Sometimes it is also called "Security Device".

Verify that driver has been loaded

Modern Linux distributions and Microsoft Windows should now detect the TPM hardware and load the driver. In Windows, a "Trusted Platform Module 1.2" device show in the device manger. In Linux, ls /dev/tpm* should list at least one block device.

Install jTSS Core Services

Download the latest version of jTSS (at least 0.7) from trustedJava. Extract the archive and launch the installer for your operating system.

For Windows, launch setup.exe in the windows folder and follow the instructions. The test program should start automatically at the end of setup.

On Linux, jTSS provides a debian package in the debian folder. Debian installation packages are supported on several popular LInux distributions, including Ubuntu. On Ubuntu, this is accomplished by $ sudo dpkg -i jtss_*_all.deb. For other Linux derivates, you may need to follow the manual installation guidelines found on the TrustedJava: jTSS Documentation.

We can now test the installation of jTSS with the simple GUI tool started at the end of setup (Linux: launch /usr/share/jtss/tests/ manually - Windows C:\Program Files\JTSS\tests\run_tests_simple.cmd) .

A successful test will look like this.

Initialize the TPM

We will now take ownership of the TPM.

Linux Users should download the latest version (0.6.1 or higher) of IAIK jTpmTools (jTT) and install them to their system (a debian package is provided). jTT also requires the IAIK JCE provider to be place in its ext_libs folder. You can download an evaluation version from Stiftung SIC.

First test the installation an learn the version of your tpm

 jtt tpm_version

Then choose a ownership password that is used to identity the owner of the plattform. Execute the following command. It will create a Storage Root Key with TSS_WELL_KNOWN_SECRET (20 bytes of zero) and inject the owner passphrase into the TPM.

 jtt take_owner -o YourOwnerPassphrase

Windows users can either use jTT analogously (manual installation required) or just follow the Windows Trusted Platform Module Management Step-by-Step Guide to initialize the TPM and take ownership. Note that the default configuration of Windows blocks some TPM commands at driver level. Among these are commands for quoting and PCR access. You have to use the group policy editor to unblock this functions. To unblock these commands, run the Group Policy Editor: gpedit.msc | Computer Configuration | Administrative Templates | System | Trusted Platform Module Services | Ignore the default list of blocked TPM commands = enabled.

If taking ownership succeeded, your TPM can now be accessed by Java applications, if they use the right set libraries.

Configure your Classpath

Depending on your project or application a number of configuration settings need to be made to your Java environment.

Add jTSS and its dependencies to your Classpath

Any Java application or project using the jTSS TSP requires the following libraries on its Classpath. jTSS provides all these files in its /lib resp. /ext_libs folders. See the jTSS documentation for more information and detailed license terms.


Add the JSR321 API to your Classpath

Get the API definition from. The archive also includes Javadoc which guides you through the API.

Add IAIK's Reference Implementation to your Classpath

Get IAIK's JSR Reference and unzip the archive.

Add the JAR to your classpath. It is advisable to set the jsr321.tpmcontextimpl to the classname of your TPMContext implementation. For example

 java -cp YourClasspath yourjavaapplication.class

Program using JSR321

Examples and code here!

Technology Compatibility Kit

First, you need to create an Attestation Identity Key and store it in your system persistent key storage. For JSR321 implementations using jTSS, this can be achieved with jTT as follows. Note that this performs a local simulation of a PrivacyCA protocol - the created identity key is therefore only good for testing purposes.

 jtt aik_create -a justASecret -l testAIKLabel -o YourOwnerPassphrase --keyfile testaik
 jtt import_key --keys testaik --dest SYS --secrets justASecret

This is an example result. Copy and paste the random UUID that is created by jTT. You will need it later to configure the TCK!

   IAIK Java TPM Tools
 11:09:05:539 [INFO] ImportKey::loadKeyChain (133):    testaik2 was registered in persistent storage with UUID: 1e9adbb2-4f1e-4002-8e1e-5da242fab42e
 11:09:05:541 [INFO] ImportKey::loadKeyChain (153):    Key successfully imported!

Get the TCK archive and extract it to a working folder.

Complete your system settings in the file. Be sure to set the correct implementation class for TPMContext, the AIK UUID created in the previous steps and same correct owner passphrase you used when taking ownership of the TPM. The test suite expects the JVM property jsr321.tck.abstracttestcaseconfig to point to the completed configuration file.

Configure the paths in the to fit your needs (we also provide a pre-configured script witch covers most settings for the IAIK RI).

You can either start the test suite in text mode with


or in GUI mode using JTHarness with

 ./ -jtharness

JTHarness is a powerful, but not trival tool, see this article for an overview of JTHarness.

Difference compared to previous revision
We can now test the installation of jTSS with the simple GUI tool started at the end of setup (Linux: launch '''/usr/share/jtss/tests/''' manually - Windows '''C:\Program Files\JTSS\tests\run_tests_simple.cmd''') . A successful test will look like this.[[image: simpletest.png | right]] = Initialize the TPM = We will now take ownership of the TPM.
Please Confirm