Trusted Computing for the Java(tm) Platform  

Martin Pirker <>
Thomas Winkler
Ronald Toegl <>
Michael Gissing

1. Introduction

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

Development of the IAIK jTpmTools was supported by the European Commission as part of the OpenTC project (Ref. Nr. 027635) OpenTC and is supported by the Austrian FIT-IT Trust in IT Systems programme in project acTvSM (acTvSM).

The IAIK 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. A Word of Caution

Please note that this software is intended to be used for testing and experimentation purposes only. It has to be stressed that this is experimental software.

1.2. License

The copyright for contents of the IAIK 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 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

2. Technical Documentation

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 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 jTSS Wrapper:
Alternatively, you can also use the IAIK 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 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 jTSS Wrapper (available at Trusted Java). The jTpmTools expect the additional IAIK jTSS Wrapper libraries to be located in the ext_libs subfolder. Note that the wrapper option has not been tested for recent releases and thus may not work as smoothly as expected.

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

2.1.3. Libraries

IAIK TCcert:
For certificate related operations, IAIK TCcert is required. This library is bundled by default since IAIK jTpmTools 0.7. IAIK TCcert also requires the IAIK JCE library. You can download a free evaluation release from Stiftung SIC.

If you use the Debian package of IAIK jTpmTools, copy the .jar of IAIK JCE into the /usr/share/jtpmtools folder. You probably need root permissions to do so. If you use the standalone .tar.bz2 package put all external libraries into 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 Wrapper






2.2. Command Overview

This build of jTpmTools offers the following operations:

  • Ownership Management:


    Take TPM ownership.


    Clear TPM ownership (all TPM protected data is lost).

  • PCR Registers:


    Read the current contents of the PCR registers.


    Extend the Platform Configuration Registers (PCRs).


    Print the event log generated by PCR extend operations to the screen.


    Create a quote describing the current state of the platform.

  • Endorsement Key functions:


    Read the public part of the Endorsement Key.


    Read the EK certificate from Infineon 1.1 and 1.2 TPMs.


    Create a PERMANENT Endorsement Key on a factory blank TPM.


    Create a revocable Endorsement Key on a factory blank TPM.


    Revoke a revocable Endorsement Key.

  • PKI functions:


    Create AIK certificate by simulating a local PrivacyCA cycle.

  • Key Management:


    Create TPM keys which are stored in the persistent storage of the TSS.


    List all keys in the persistent storage of the TSS.

  • Data Blocks:


    Bind (encrypt) a file using a TPM key.


    Seal (encrypt w.r.t. PCR values) a file using a TPM key.


    Unbind (decrypt) a TPM-bound file.


    Unseal (decrypt) a sealed file.

  • Non Volatile Storage:


    decode data in non-volatile storage of the TPM


    define an index and space in TPM NV RAM


    set the global lock for the NV storage - FOREVER!


    release a defined index


    write data to TPM’s NV RAM

  • Monotonic Counters:


    create a new monotonic counter


    increment the value of a monotonic counter


    read the value of a monotonic counter


    destroy a monotonic counter

  • Intel® Trusted eXecution Technology (TXT):


    create a TXT Launch Control Policy (LCP)


    show informations about a LCP file


    create a TXT Launch Control Policy (LCP) Version 2


    create and modify LCP_POLICY_ELEMENTs


    create, modify and sign LCP_POLICY_LISTs

  • TBoot:


    calculate value of PCR 18 after trusted boot


    calculate values of PCRs above PCR 18 after trusted boot


    create and modify TBoot Verified Launch Policy (VLP)


    show informations about a VLP file

  • TPM:


    query flags status information of the TPM


    query supported command set of the TPM


    reset the TPM dictionary attack mitigation values


    query version information of the TPM


    obtain some randomness from the TPM

  • Other:


    Query library versions.

2.3. Usage

There is no special installation procedure required to use the IAIK 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 ( is located in the main folder. To get an overview of the individual sub-commands simply call 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 <sub-command>.


If you already took ownership on your TPM with another tool you can load your SRK to jTSS’s persistent storage by simply calling the take_owner command. In this case the take_owner command won’t alter your TPM’s owner state but read out the public part of the SRK and store it to persistent storage.

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

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

      This permission is TPM_NV_PER_WRITEDEFINE (see TPM_NV_ATTRIBUTES datastructure in TPM specification as reference)


      The size is the default size of a LCP

    2. Intel TXT INDEX_AUX

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

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

  2. lock TPM

    ./ nv_lock --force

    This will PERMANENTLY set the lock of your TPM NV storage

  3. define spaces in NV RAM

    1. tboot launch error index

      ./ nv_definespace --index 0x20000002 --size 8 --permission 0x0 \
                              --readlocality 0x07 --writelocality 0x07 -o password
    2. Intel TXT INDEX_LCP_OWN

      ./ nv_definespace --index 0x40000001 --size 34 -o password
    3. tboot’s Verified Launch Policy

      ./ nv_definespace --index 0x20000001 --size 256 -o password
  4. create policies

    1. LCP

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

      ./ tboot_policy --create --type halt --file vl.pol
      ./ tboot_policy --add --num 0 --pcr none --hash image --cmdline [KERNEL COMMANDLINE] \
                            --image [KERNEL IMAGE] --file vl.pol
      ./ tboot_policy --add --num 1 --pcr 19 --hash image --cmdline '' \
                            --image [INITRD] --file vl.pol
      ./ 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

      ./ nv_write --index 0x40000001 --file lcp.pol -o password
    3. write VLP

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

2.3.3. Handling Launch Control Policy (LCP) Version 2

jTpmTools comes with a set of commands which allow you to create and modify Intel TXT Launch Control Policy (LCP) Version 2.

For details regarding LCPs please read Intel’s Measured Launched Environment Developer’s Guide.

LCP_POLICY_ELEMENTs - sub command txt_policy2_element

Currently these elements are supported:




The txt_policy2_element tool implements the following commands:


Create a new element. The required options depend on the type of the element as specified by --type.


Calculate the hash of an mle. The result can be used for creation of an LCP_MLE_ELEMENT.


Decodes a given element file and prints human readable information.

LCP_POLICY_LISTs - sub command txt_policy2_list

The txt_policy2_list tool implements the following commands:


Create a new policy list.


Sign a policy list.


Add a signature block to an existing policy list.


Create a RSA key pair.


Decodes a given policy list file and prints human readable information.

LCP_POLICY and LCP_POLICY_DATA - sub command txt_policy2

The txt_policy2 tool implements the following commands:


Create an LCP version 2 and, if --type is "LIST", an LCP_POLICY_DATA file.


Decodes a given policy file and policy data file and prints human readable information.

Step by Step usage example

This example shows how to create a policy which meets the following requirements:

  • there are two MLEs which should be allowed to run

    • /boot/tboot_1.gz

    • /boot/tboot_2.gz

  • the platform should be in a certain state when a late launch is issued

Here are the steps:

  1. Create a LCP_MLE_ELEMENT

    1. Obtain MLE hashes

      ./ --quiet txt_policy2_element --hash-mle --mle /boot/tboot_1.gz --mle-cmd "CMDLINE" > mle.hashes
      ./ --quiet txt_policy2_element --hash-mle --mle /boot/tboot_2.gz >> mle.hashes
      cat mle.hashes
    2. Create the element

      ./ txt_policy2_element --create --type mle --file mle.elt --data mle.hashes
    3. Alternative: To specify only one MLE, the following can be used:

      ./ txt_policy2_element --create --type mle --file mle.elt --mle /boot/tboot_1.gz --mle-cmd "CMDLINE"

    1. Create a file containing the hashes

      cat pcr.values.example
      00: 32 52 AB B8 82 76 D3 13 BE 44 D2 47 E5 FC 95 CD 03 06 7D 2D
      01: A7 46 DF 87 49 64 75 FE 5C B2 14 47 F3 8E 66 46 04 57 67 5B
      02: 05 A8 C0 53 ED 4B 3D 48 EA 43 F4 64 F4 9A 96 B6 0B 05 0A 72
      13: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
      14: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    2. Create the element

      ./ txt_policy2_element --create --type pconf --file pconf.elt --data pcr.values.example
    3. Alternative: the txt_policy2_element tool can obtain current PCR configuration (PCRs 0 to 7 will be used)

      ./ txt_policy2_element --create --type pconf --file pconf.elt
  3. Create a LCP_POLICY_LIST

    ./ txt_policy2_list --create --file policy.list --elements mle.elt,pconf.elt

    ./ txt_policy2 --create --type list --file lcp2.pol --data-file --lists policy.list
Policy deployment

LCP version 2 is bigger than the older version, the size of the indices INDEX_LCP_DEF and INDEX_LCP_OWN in TPM NV RAM has to be 54 bytes. (See also [txt_cmds])

./ nv_definespace --index 0x40000001 --size 54 -o password
./ nv_write --index 0x40000001 --file lcp2.pol -o password

If the LCP is of type LCP_POLTYPE_LIST, the file containing the LCP_POLICY_DATA has to be stored on a file system which is reachable by the bootloader.

3. Support

For questions, bug reports, feature requests, patches, criticism or suggestions please use the following mailing list:

4. Trademarks

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.

5. Revision History

date version comment
2011/09/06 0.7 bugfixes, quote/monotonicCtr/random commands, bundle tccert 0.2.5, synchronize with jTSS 0.7
2010/10/04 0.6 TXT LCP v2 support, synchronize with jTSS 0.6
2010/03/04 0.5 several new command switches, synchronize with jTSS 0.5
2009/08/26 0.4 EK management, NV/TXT/Tboot support, TPM status functions
2009/05/19 0.4beta improve EK cert extraction, remove XKMS support, various fixes
2008/06/05 0.3c Bugfix
2008/04/09 0.3b Automatic binding selection for jTSS 0.3, partial adaptations to IFX wrapper
2007/08/31 0.3a fix aik key password encoding, synchronise with jTSS 0.2
2007/04/24 0.3 updated to be compliant with jTSS Wrapper 0.3 and IAIK jTSS 0.1, PKI function set added
2007/02/08 0.2 updated to work with TrouSerS 0.2.9 and jTSS Wrapper 0.2.5
2006/10/09 0.1 initial release of IAIK jTpmTools