Trusted Computing for the Java(tm) Platform

v0.7
Martin Pirker <mpirker_iaik@users.sourceforge.net>
Thomas Winkler
Ronald Toegl <rtoegl_iaik@users.sourceforge.net>
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 jce-sales@iaik.at.

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

quote

Create a quote describing the current state of the platform.
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
Monotonic Counters:

ctr_create

create a new monotonic counter

ctr_inc

increment the value of a monotonic counter

ctr_read

read the value of a monotonic counter

ctr_release

destroy a monotonic counter
Intel® Trusted eXecution Technology (TXT):

txt_policy

create a TXT Launch Control Policy (LCP)

txt_policyinfo

show informations about a LCP file

txt_policy2

create a TXT Launch Control Policy (LCP) Version 2

txt_policy2_element

create and modify LCP_POLICY_ELEMENTs

txt_policy2_list

create, modify and sign LCP_POLICY_LISTs
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

get_rand

obtain some randomness from the TPM
Other:

version

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

Note:: 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.

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
lock TPM
```
./jtt.sh nv_lock --force
```
Note:

This will PERMANENTLY set the lock of your TPM NV storage

define spaces in NV RAM

tboot launch error index

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

Intel TXT INDEX_LCP_OWN

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

tboot’s Verified Launch Policy

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

create policies

LCP

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

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

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

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:

LCP_MLE_ELEMENT
LCP_PCONF_ELEMENT
LCP_CUSTOM_ELEMENT

The txt_policy2_element tool implements the following commands:

--create: Create a new element. The required options depend on the type of the element as specified by --type.
--hash-mle: Calculate the hash of an mle. The result can be used for creation of an LCP_MLE_ELEMENT.
--show: 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: Create a new policy list.
--sign: Sign a policy list.
--addsig: Add a signature block to an existing policy list.
--create-key: Create a RSA key pair.
--show: 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: Create an LCP version 2 and, if --type is "LIST", an LCP_POLICY_DATA file.
--show: 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:

Create a LCP_MLE_ELEMENT

Obtain MLE hashes

./jtt.sh --quiet txt_policy2_element --hash-mle --mle /boot/tboot_1.gz --mle-cmd "CMDLINE" > mle.hashes
./jtt.sh --quiet txt_policy2_element --hash-mle --mle /boot/tboot_2.gz >> mle.hashes
cat mle.hashes
63979c98bb6506880cd864e20b82ef3119a081a8
3fec2dd784df10ae71d841b7a74d7282828da437

Create the element

./jtt.sh txt_policy2_element --create --type mle --file mle.elt --data mle.hashes

Alternative: To specify only one MLE, the following can be used:

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

Create a LCP_PCONF_ELEMENT

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

Create the element

./jtt.sh txt_policy2_element --create --type pconf --file pconf.elt --data pcr.values.example

Alternative: the txt_policy2_element tool can obtain current PCR configuration (PCRs 0 to 7 will be used)
```
./jtt.sh txt_policy2_element --create --type pconf --file pconf.elt
```

Create a LCP_POLICY_LIST

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

Create LCP_POLICY and LCP_POLICY_DATA

./jtt.sh txt_policy2 --create --type list --file lcp2.pol --data-file lcp2.data --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])

./jtt.sh nv_definespace --index 0x40000001 --size 54 -o password
./jtt.sh 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: trustedjava-support@lists.sourceforge.net.

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

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