Skip to main content
Last updated July 11, 2012 07:30, by MichaelGissing
Feedicon  

Getting Started with JSR321: A Guide

Specification Lead: Ronald Toegl, IAIK, Graz University of Technology

Copyright © 2011 IAIK, Graz University of Technology.

The JSR321 API AND RI SOFTWARE is provided under the terms of the GNU General Public License, version 2, with the Classpath Exception. On individual request, IAIK may in addition grant different license terms. For pricing and further information please contact jce-sales AT iaik.at.

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.


Table of Contents


Introduction to Trusted Computing

Trusted Computing (TC) is a technology mainly developed and promoted by the Trusted Computing Group. With Trusted Computing, the computer is envisioned to consistently behave in expected ways, and those behaviors will be enforced by hardware and software. In practice, Trusted Computing uses cryptography to help enforce a selected behavior. One main functionality of TC is to allow someone else to verify that only authorized code runs on a system. This authorization covers initial booting and kernel and may also cover applications and services. Just by itself TC does not protect against attacks that exploit security vulnerabilities introduced by programming bugs.

Before reading this guide, you should familiarize yourself with the Trusted Computing Group's (TCG) specifications regarding the Trusted Platform Module (TPM), version 1.2 and the TCG Software Stack, version 1.2. We provide a boot-camp-style introduction in Trusted Computing and Java: A Primer.

An extended discourse about JSR321, its history, design and technical background is provided in the following full length journal publication:

Toegl, R., Winkler, T., Nauman, M. and Hong, T. W. (2011), Specification and Standardization of a Java Trusted Computing API. Software: Practice and Experience. Wiley. http://onlinelibrary.wiley.com/doi/10.1002/spe.1095/full.

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. Unfortunately many of the TPMs shipped from various vendors have been built with slightly different interpretations of the specifications or may contain bugs. As an single different bit in any input or output will cause different cryptographic checksums, you may encounter compatibility problems. Recently, TCG made a compliance test kit available and modern firmware versions offer correct implementations. The following implementations are known to support the full feature set of JSR321: Infineon TPM 1.2, Firmware 3.17 and IBM Software TPM (Emulator).
  • 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 Java 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!

Downloadable files

Here we provide an overview of the files of the final release. Usage of the files is described further down this page.

  • JSR 321 Specifications [PDF] the final specification document
  • jsr321-api [ZIP] contains the JSR 321 API as well as source code and javadoc of the API
  • jsr321-ri [ZIP] contains IAIK's reference implementation
  • jsr321-tck [ZIP] contains the Technology Compatibility Kit


System Configuration

Trusted Computing requires the close cooperation of hardware and software. Designed as an opt-in feature, the security mechanisms must be purposefully turned on and activated by the owner of the platform. In the following we describe how to configure your operating system to provide Java with full TPM access.

This guide is written for Windows Vista and later and derivates of Debian Linux. We target advanced users and System and Java security experts.

Install Java and Enable Strong Cryptography

Download and Install a Java Runtime Environment, or for application development 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. A 64-bit JRE is recommended on Windows 64.

Recommended, but optional: 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" or permission problems when initializing a JCE provider, chances are high that these policy files are not (or not correctly) installed. Note that JSR321 does not require the unlimted strengh policies, but some Java configurations might still need this workaround.

Turn your TPM On

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

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 will show in the device manger. In Linux, ls /dev/tpm* should list at least one block device which may be accessed by user root.

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 deb folder. Debian installation packages are supported on several popular LInux distributions, including Ubuntu. Ubuntu package dependencies are jsvc and libcommons-daemon-java, which should be installed first. On Ubuntu, the jTSS package is installed by $ sudo dpkg -i jtss_*_all.deb. Some Linux distributions ship with the TrouSerS tcsd, a C-based TSS. TrouSerS should be uninstalled as it would block the device access for jTSS (on Windows, both stacks can run in parallel).

For other Linux derivates, or if you encounter any problems, 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/run_tests_simple.sh manually - Windows C:\Program Files\JTSS\tests\run_tests_simple.cmd (java.exe needs to be on the PATH)).

A successful test will look like on the picture on the right.

It is essential that jTSS Core services are up and running before you continue. Please do consult the jTSS documentation for information and support contact.

Initialize the TPM

We will now take ownership of the TPM.

Linux Users should download the latest version (0.7 or higher) of IAIK jTpmTools (jTT) and install them to their system (a debian package is provided). For windows, extract the *.tar.gz file using your favorite (de-)compression tool, like WinRAR to a directory of your choice.

jTT also requires the IAIK JCE provider to be placed in its ext_libs folder. If you have installed jTT using the debian package, place the .jar file in /usr/share/jtpmtools/. 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. The command will also initialize the jTSS persisten key storage.

 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 of 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.

 {jtss}/libs
 ------------------
 iaik_jtss_tsp.jar
 iaik_jtss_tsp_soap.jar
 
 {jtss}/ext_libs
 ------------------
 activation.jar
 axis-ant.jar
 axis.jar
 commons-discovery-0.2.jar
 commons-logging-1.0.4.jar
 hsqldbmin.jar
 jaxrpc.jar
 log4j-1.2.8.jar
 mail.jar
 saaj.jar
 wsdl4j-1.5.1.jar


Add the JSR321 API to your Classpath

Get the API definition from http://jsr321.java.net. The jsr321-api.zip archive also includes Javadoc which guides you through the API. Add the jsr321.jar file to your Classpath.

Add IAIK's Reference Implementation to your Classpath

Get IAIK's JSR Reference Implementation from http://jsr321.java.net and unzip the jsr321-ri.zip archive. Add the jsr321-ri.jar file to your Classpath.

It is necessary to set the jsr321.tpmcontextimpl property to the classname of your TPMContext implementation. For example

 java -cp YourClasspath -Djsr321.tpmcontextimpl=iaik.tc.jsr321.tpm.TPMContextImpl yourjavaapplication.class

Program using JSR321

You can now run or implement JSR231 applications by importing the javax.trustedcomputing.* packages. The following minimal example demonstrates the shortest JSR321 program.

package iaik.tc.jsr321.example.tutorial;
import javax.trustedcomputing.tpm.TPMContext;
public class ShortestJSR321Program {
	/**
	 * This is the smallest JSR321 program. It just opens a TPMContext session
	 * with the local TPM.
	 */
	public static void main(String[] args) {
		try {
			// First, get the TPMContext factory.
			TPMContext context = TPMContext.getInstance();
			// Connect it to the local TPM
			context.connect(null);
			// Do something cool here..
			context.close();
		} catch (Exception e) {
			e.printStackTrace();
		}
	}
}

The unique namespace officially assigned to the JSR 321 API is javax.trustedcomputing. Within this namespace, a number of packages have been specified, each representing a well-defined set of functionality. These packages are:

  • javax.trustedcomputing.tpm This package contains all relevant functionality for connecting to a TPM. A TPM connection is represented by the central TPMContext object that acts as a factory for other objects specified by the API such as the KeyManager or the Sealer. The TPM interface is also defined in this package, which provides general TPM related information such as its version and manufacturer. Additionally, it allows PCR registers to be read and extended, as well as providing the quote operation required for platform attestation.
  • javax.trustedcomputing.tpm.keys Contrary to the TSS specification, JSR 321 introduces specific interfaces for the individual key types supported by the TPM. This includes interfaces for storage, sealing, and binding keys. Compared with having one generic key object, this approach reduces ambiguities in the API and allows appropriate key usage to be enforced at the interface level.
  • javax.trustedcomputing.tpm.structures This package holds data structures required for certain TPM operations. They include the PCREvent structure required for operations on the measurement log, PCRInfo used as part of platform attestation and ValidationData as returned by the TPM quote operation.
  • javax.trustedcomputing.tpm.tools In this package, there are interface definitions for helpers classes to perform TPM operations such as binding, sealing, signing and attestation. The javax.trustedcomputing.tpm.tools.remote subpackage offers abstract classes that allow a remote host without TPM to participate in Trusted Computing protocols. It provides the functionality to validate and verify signatures on TC data types.

For error handling, a single TrustedComputingException covers all lower layers. It offers the original TPM/TSS error codes, but also a human readable text representation, which is a great step forward in terms of usability. Despite using only a single exception class, implementations of the API should forward as much error information as possible. For illegal inputs to the JSR 321 API, default Java runtime exceptions are used. Finally, functions offering bit-wise access to status and capability flags are replaced by specific methods that allow access to application relevant flags.

In JSR 321, the KeyManager interface defines methods for creating new TPM keys. Upon creation, a secret for key usage and an optional secret for key migration have to be specified. After a key is created, the KeyManager allows the key, encrypted by its parent, to be stored in non-volatile storage. As required, the KeyManager allows keys to be reloaded into the TPM, provided that the key chain up to the storage root key has been established (i.e., each parent key is already loaded into the TPM). Every time a new key is created or loaded from permanent storage, a usage secret has to be provided. This secret is represented by an instance of a dedicated class Secret that is attached to the key object upon construction. Secret also encapsulates and handles details such as string encoding, which are often a source of incompatibility between different TPM-based applications. The extendable tools package implements various core concepts of Trusted Computing. As each tool that accesses the TPM is already linked to a TPMContext at creation, there are few or no configuration settings required before using the tool. Each tool provides a small group of methods that offer closed functionality. For example, a Binder allows the caller to bind data under a BindingKey and a Secret, and returns the encrypted byte array. Usage complexity is minimal as no further parameters need to be configured, and the call to unbind encrypted data is completely symmetric. Besides, the core set of tools (Signer, Binder, Sealer), implementers of JSR 321 may add further sets of functionality. An example might be a tool, which manages TPM ownership, if the Java library is implemented on an OS without tools for doing so.

Technology Compatibility Kit

To perform a comprehensive test of your JSR321 installation or even your own implementation of the API you can use the JSR321 Technology Compatibility Kit.

Contact

Please contact the specification lead for any comments or questions. (Ronald.Toegl at iaik.tugraz.at)

 
 
Close
loading
Please Confirm
Close