IAIK/OpenTC jTpmTools — TPM Tools for the Java (tm) Platform

The IAIK/OpenTC jTpmTools are a set of command line tools demonstrating basic interaction with the Trusted Platform Module (TPM) and the Trusted Software Stack (TSS).

This includes tools for taking/clearing ownership and reading/extending PCRs. Further, a command demonstrating creating Attestation Identity Keys (AIKs) is included.

Development of the IAIK/OpenTC jTpmTools 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 jTpmTools package is developed and maintained at the Institute for Applied Information Processing and Communication (Institut fuer Angewandte Informationsverarbeitung und Kommunikation, IAIK), at Graz University of Technology (TU Graz).

1.1. OpenTC Project

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 the OpenTC website.

1.2. A Word of Caution

Please note that all certificates created using the PKI commands are intended to be used for testing and experimentation purposes only. Moreover it has to be stressed that this is experimental software. Its main purpose currently is research and education.

1.3. License

The copyright for contents of the IAIK/OpenTC jTpmTools package, including all related documentation, is owned by IAIK, Graz University of Technology (TU Graz).

jTpmTools is using a dual licensing model:

• For Open Source development, IAIK/OpenTC jTpmTools 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 the Free Software Foundation website.

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

The following sections outline requirements, commands and usage examples for jTpmTools.

2.1. Requirements

jTpmTools require hardware as well as software support components to achieve full functionality. For some of the components there are several options. This section lists these options and provides some background information that helps to pick a suitable component.

Naturally, a hardware TPM or a TPM emulator is a "must" requirement. Additionally, administrative (i.e. root) permissions are usually required to directly access the TPM device.

2.1.1. Java

To use the jTpmTools you need to have a Sun Java (tm) Environment of version 5 or later. Earlier Java versions do not provide the required cryptographic functionality. Compatibility with other Java vendors is unknown and untested.

2.1.2. TSS

All commands require a TCG compliant Trusted Software Stack (TSS) to be running on the system. There are two options to choose from:

IAIK jTSS:
IAIK jTSS provides the toplevel Java TSP interfaces as well as a full TSS core implementation completely written in Java. It therefore has modest external requirements and may be the easiest to set up. To make use of IAIK jTSS the two libraries iaik_jtss_tcs.jar and iaik_jtss_tsp.jar have to be copied into the ext_libs subfolder. IAIK jTSS can be downloaded from Trusted Java.

IAIK/OpenTC jTSS Wrapper:
Alternatively, you can also use the IAIK/OpenTC jTSS Wrapper as an add-on to the IAIK jTSS. In this combination all calls to the TPM are routed via Java native interface (JNI) calls to the TrouSerS C level implementation. jTpmTools originated in the IAIK/OpenTC jTSS Wrapper code which means that both have almost the same basic requirements. For a detailed list of requirements please consult the requirements of IAIK/OpenTC jTSS Wrapper (available at Trusted Java). The jTpmTools expect the additional IAIK/OpenTC jTSS Wrapper libraries to be located in the ext_libs subfolder. jTpmTools requires a IAIK/OpenTC jTSS Wrapper of the 0.3.x series, the 0.2.x series is not compatible!

If a running TrouSerS process is detected on your system, the jTpmTools will try to use TrouSerS together with the IAIK/OpenTC jTSS Wrapper. If no running TrouSerS is available the pure IAIK jTSS variant will be used.

2.1.3. Libraries

IAIK/OpenTC TCcert:
For certificate related operations, IAIK/OpenTC TCcert is required. It can be downloaded from Trusted Java. The package includes a readme file with further details. This library also requires the IAIK JCE library. How to obtain it is described in the readme of the IAIK/OpenTC TCcert. Certificate related commands expect the IAIK/OpenTC TCcert libraries as well as the IAIK JCE libraries to be located in the ext_libs subfolder.

2.1.4. Summary

As reference, for maximum functionality of jTpmTools the content of the ext_libs directory should be:

jTSS

ext_libs/iaik_jtss_tsp.jar
ext_libs/iaik_jtss_tcs.jar

JTss Wrapper

ext_libs/iaik_jtss_wrapper.jar ext_libs/iaik_jtss_wrapper_swig.jar ext_libs/libtspiwrapper.so

IAIK JCE

ext_libs/iaik_jce.jar

IAIK TCcert

ext_libs/iaik_tccert.jar

2.2. Command Overview

This build of jTpmTools offers the following operations:

• Ownership Management:

  take_owner	Take TPM ownership.
  clear_owner	Clear TPM ownership (all TPM protected data is lost).

• PCR Registers:

  pcr_read	Read the current contents of the PCR registers.
  pcr_extend	Extend the Platform Configuration Registers (PCRs).
  dump_eventlog	Print the event log generated by PCR extend operations to the screen.

• Endorsement Key functions:

  read_pubek	Read the public part of the Endorsement Key.
  read_certek	Read the EK certificate from Infineon 1.1 and 1.2 TPMs.
  create_ek	Create a PERMANENT Endorsement Key on a factory blank TPM.
  create_revocable_ek	Create a revocable Endorsement Key on a factory blank TPM.
  revoke_ek	Revoke a revocable Endorsement Key.

• PKI functions:

  aik_create

  Create AIK certificate by simulating a local PrivacyCA cycle.

• Key Management:

  create_key	Create TPM keys which are stored in the persistent storage of the TSS.
  list_keys	List all keys in the persistent storage of the TSS.

• Data Blocks:

  bind	Bind (encrypt) a file using a TPM key.
  seal	Seal (encrypt w.r.t. PCR values) a file using a TPM key.
  unbind	Unbind (decrypt) a TPM-bound file.
  unseal	Unseal (decrypt) a sealed file.

• Non Volatile Storage:

  nv_decode	decode data in non-volatile storage of the TPM
  nv_definespace	define an index and space in TPM NV RAM
  nv_lock	set the global lock for the NV storage - FOREVER!
  nv_releasespace	release a defined index
  nv_write	write data to TPM's NV RAM

• Intel® Trusted eXecution Technology (TXT):

  txt_policy	create a TXT Launch Control Policy (LCP)
  txt_policyinfo	show informations about a LCP file

• TBoot:

  tboot_pcr18	calculate value of PCR 18 after trusted boot
  tboot_pcr19-22	calculate values of PCRs above PCR 18 after trusted boot
  tboot_policy	create and modify TBoot Verified Launch Policy (VLP)
  tboot_policyinfo	show informations about a VLP file

• TPM:

  tpm_flags	query flags status information of the TPM
  tpm_ordinals	query supported command set of the TPM
  tpm_resetlock	reset the TPM dictionary attack mitigation values
  tpm_version	query version information of the TPM

• Other:

  version

  Query library versions.

2.3. Usage

There is no special installation procedure required to use the IAIK/OpenTC jTpmTools. After unpacking the archive, the only precondition is that the required libraries are obtained and placed in the ext_libs folder (see Requirements section).

The main executables (jtt.sh) is located in the main folder. To get an overview of the individual sub-commands simply call jtt.sh without passing any further arguments. A list of available sub-commands is printed to the screen. To get an overview of the parameters that can be passed to a sub-command simply type jtt.sh <sub-command>.

2.3.1. Example

By means of the aik_create sub-command, which is one of the more sophisticated ones, a call example is shown in more detail:

The aik_create command offers the following switches:

required parameters:
  -a        aikSecret   ... password for the new AIK
  -l        aikLabel    ... AIK label
  -o        ownerSecret ... TPM owner password

optional parameters:
  --aikfile aikFileName ... name file to write AIK certificate to (default: aik.cert)
  --ekfile  filename    ... specify file to import EK certificate from
  --keyfile keyFileName ... name file to write the AIK key blob to (default: aik.tpmkey)
  --noek                ... EK certificate is already known by TSS (e.g. via tcsd.conf
                            of TrouSerS)
  -e        encoding    ... encoding for password strings (legal values: ASCII, UTF-16,
                            UTF-16BE, UTF-16LE) (default: UTF-16LE)
  -n                    ... append null termination to password strings
  -s        srkSecret   ... SRK password (default: TSS_WELL_KNOWN_SECRET)

• aikSecret is the password that protects the new AIK key pair

• aikLabel can be freely chosen and helps users to identify a specific AIK

• ownerSecret is the TPM owner password

• aikFile allows users to select the file name the AIK certificate is written to

• ekFile allows to externally provide the EK certificate. By default, the aik_create command tries to read the EK certificate directly from the TPM chip (IFX TPMs).

• noek instructs the aik_create command to neither read the EK certificate from the TPM nor to expect the EK to be supplied as an external file. This is useful if the EK certificate is managed by the underlying TSS stack (e.g. TrouSerS via its tcsd.conf).

• The e and n parameters allow to configure the password encoding and null termination.

• The s option allows to set SRK passwords other than TSS_WELL_KNOWN_SECRET.

2.3.2. Commands for TXT and TBoot setup

jTpmTools comes with a set of commands to manage the NV storage of the TPM. This allows to create and write policies for Intel Trusted eXecution Technology (TXT) enabled machines and for the Trusted Boot (TBoot) tool.

These commands are EXPERIMENTAL! These commands MAY PERMANENTLY DAMAGE YOUR HARDWARE! Use of these commands is AT YOUR OWN RISK - so don't blame us if you brick your hardware!

The following example calls show approximately how to setup TXT with TBoot. Modify according to your setup and your specific TPM. Study the specifications first!

If your TPM is already locked, you can't do/need steps 1 and 2.

1. define defined spaces in NV RAM

   1. Intel TXT INDEX_LCP_DEF

      ./jtt.sh nv_definespace --index 0x50000001 --size 34 --permission 0x00002000 -o password

      Note:	This permission is TPM_NV_PER_WRITEDEFINE (see TPM_NV_ATTRIBUTES datastructure in TPM specification as reference)
      Note:	The size is the default size of a LCP

   2. Intel TXT INDEX_AUX

      ./jtt.sh nv_definespace --index 0x50000002 --size 64 --permission 0x0 --writelocality 3,4 -o password

      Note:

      Write protection is established by restricting localities, not by setting a permission

2. lock TPM

   ./jtt.sh nv_lock --force

   Note:

   This will PERMANENTLY set the lock of your TPM NV storage

3. define spaces in NV RAM

   1. tboot launch error index

      ./jtt.sh nv_definespace --index 0x20000002 --size 8 --permission 0x0 --readlocality 0x07 --writelocality 0x07 -o password

   2. Intel TXT INDEX_LCP_OWN

      ./jtt.sh nv_definespace --index 0x40000001 --size 34 -o password

   3. tboot's Verified Launch Policy

      ./jtt.sh nv_definespace --index 0x20000001 --size 256 -o password

4. create policies

   1. LCP

      ./jtt.sh txt_policy --file lcp.pol --mle /boot/tboot.gz --type hashonly --mle-cmd 'logging=serial,vga,memory'

   2. VLP

      ./jtt.sh tboot_policy --create --type halt --file vl.pol
      ./jtt.sh tboot_policy --add --num 0 --pcr none --hash image --cmdline [KERNEL COMMANDLINE] \
                            --image [KERNEL IMAGE] --file vl.pol
      ./jtt.sh tboot_policy --add --num 1 --pcr 19 --hash image --cmdline '' --image [INITRD] --file vl.pol
      ./jtt.sh tboot_policy --add --num 2 --pcr none --hash any --file vl.pol

5. write policies to NV RAM

   1. If you have done step 1, you have to create default LCP too and write it to index 0x50000001

   2. write user's LCP

      ./jtt.sh nv_write --index 0x40000001 --file lcp.pol -o password

   3. write VLP

      ./jtt.sh nv_write --index 0x20000001 --file vl.pol -o password

For questions, bug reports, feature requests, patches, criticism or suggestions please use the following mailing list: trustedjava-support@lists.sourceforge.net.

Java (tm) and all Java 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.