TPM/J Developer's Guide

Overview

User's Guide

Library and Other settings

Note: in addition to the currently-supported platforms, it should be relatively straightforward to make TPM work with any Windows library which provides a TDDL-level interface. For examples, see the code under src/.../drivers/win32 and the c/IFXTPM and c/TBSProxy directory. If you write your own driver code, please contact us to contribute them back to the community.

Working with the Source Code

High-Level TPM/J programming

The best place to start understanding TPM/J and learning to write your own applications using TPM/J, is to look at the tools classes in the tools package.

For the most part, these do not deal directly with TPM commands, but use the convenience functions in the funcs package. The edu.mit.csail.tpmj.funcs package contains higher-level classes that make it easier to perform commonly-needed tasks without having to deal with the TPM command objects directly. To use these, you generally follow the following steps:

1. Initialize the TPMDriver. Note that the TPMUtilityFuncs class stores the TPMDriver object in a static variable which is automatically used by the classes in the funcs package.
   

   TPMUtilityFuncs.initTPMDriver();
   

2. Call the desired function. Note that the output of these functions are typically the relevant TPM structures themselves, and not the direct output of the command.

   TPM_KEY key = TPMStorageFuncs.TPM_CreateWrapKey(
                   parentHandle, parentAuth, keyAuth, migAuth,
                   keyUsageType, keyUsageFlags );
   System.out.println( "Returned wrapped key: " + key );
   

3. At the end of your entire program, call TPMUtilityFuncs.cleanupTPMDriver(); This calls the cleanup() method on the driver, which on some platforms (i.e., Windows and Vista) is needed to close the TDDL session/context.

In addition to these functions, there are also generic utility classes provided in edu.mit.csail.tpmj.util. In particular, CryptoUtil has several useful functions for doing some cryptographic computations in software. (Some of these use the Bouncy Castle library for Java.) Also, TPMToolsUtil has convenience methods that are used by the tools classes to make handling command-line options easier.

Low-level TPM/J programming: How to Use TPM Command Objects

In general, the data structures defined by the TCG's Structures of the TPM spec, are defined as separate Java classes in the edu.mit.csail.tpmj.structs package. To be consistent with TCG notation, we have intentionally violated the standard Java naming conventions, and have named the classes in all caps, according to their TCG names. The structs package also contains some classes which do not directly correspond to TCG structures, but which may represent abstract base classes for TCG classes. These classes are not named in all caps.

Similarly, the TPM commands, as defined in the TCG's Commands spec for the TPM are defined as separate Java classes in the edu.mit.csail.tpmj.commands package, again following the same names and capitalization used in the TCG Spec. Additionally, each of these command classes has a corresponding class that defines its output response data structure, with the name <CommandName>Output, where <CommandName> is the name of the command (e.g., TPM_GetPubKey and TPM_GetPubKeyOutput would be the Java class files corresponding to the TPM_GetPubKey command).

1. Initialize and get a TPMDriver
   

   TPMUtilityFuncs.initTPMDriver();
   TPMDriver tpmDriver = TPMUtilityFuncs.getTPMDriver();
   

2. Create the command object.

   TPM_PCRRead cmd = new TPM_PCRRead( pcrIndex );
   

3. Call the command's execute method, giving it the TPMDriver object, and receiving the output in the appropriate response type.

   TPM_PCRReadOutput output = cmd.execute( tpmDriver );
   

   
   Note that this command can throw a TPMException, so it should generally be surrounded by a try-catch. Any errors in executing the command, including TPM errors with a corresponding return code will throw a type of TPMException.
   
4. Read and use the output data structure using its fields.

   TPM_PCRVALUE pcrVal = output.getOutDigest();
   System.out.println( "PCR " + pcrIndex + "= " + pcrVal );
   

Using commands which require authorization is more complicated. For these, you would need to use one of the authorization session classes. See edu.mit.csail.tpmj.tests.TPMAuthTest for an example. Note also that there are many "convenience classes" in the edu.mit.csail.tpmj.funcs package for hiding the complexity of using authorization sessions directly for commonly-used tasks.

How to Create Your Own TPM Command Objects

1. Check to see the TPM structures used in the input and output structures of the command. Create the corresponding Java files for these in the structs package, as necessary. The key tasks in defining these class files is writing the fields, the constructor, the toBytes method, and the fromBytes method. Look at the source code in the structs package for examples.
2. Create the command class under the commands package, under the same name as given by TCG. It should be descended from TPMCommand (commands that require authorization should extend one of the TPMAuth* classes or TPMKeyAuth1Command). Note that TPMCommand classes are themselves TPMStructs, so you must also define the toBytes and fromBytes methods to specify how the command is converted into a byte array.
3. Create the corresponding <CommandName>Output class. This should be placed in the commands package (not the structs package).
4. Override the execute(...) method(s) of the <CommandName> class to return the appropriate type. e.g.,

       @Override
       public TPM_PCRReadOutput execute( TPMDriver tpmDriver ) throws TPMException
       {
           return (TPM_PCRReadOutput) super.execute( tpmDriver );
       }
   

5. Also override the getReturnType() method of the <CommandName> class to return the class of the appropriate type. e.g.,

       @Override
       public Class getReturnType()
       {
           return TPM_PCRReadOutput.class;
       }
   

6. If desired, add corresponding convenience functions for using the new command to one of the classes (or a new class) in the funcs package. These convenience functions should hide the creation of the TPM command object itself. It should receive the user-level input data for the command, and return the desired TPM structure. (Although in cases where the TPM returns several data structures of interest, it is OK, or even better, to return the entire command output data structure itself directly.)

See the source code in the commands package for examples.

(TODO: More explicit documentation on how to define ByteArrayables and write toBytes and fromBytes methods. For now, please look at the examples in the source code.)

Parameter Handling

Debugging

The edu.mit.csail.tpmj.util.Debug class provides debugging functions in the form of print statements that only print when debugging for certain classes is on. To use, add Debug.setDebugOn( MyClass.class, true ) for each class "MyClass" that you want to debug, at the beginning of the main() method of the main class you are running. Then, in MyClass, you can use Debug.print( ... ) and Debug.println( ... ) methods for conditional debugging output. If debugging has been turned on for MyClass, then these methods will print to System.out. Otherwise, they won't. See the demos, tools, and tests classes, and the classes that these debug, for examples.

Note that the print and println commands accept a variable-length argument list of Objects. The recommended way to use it is to use a comma (',') instead of string concatenation ('+') when printing a complex object (e.g., a TPMStruct object) with a long toString(...) method. This way the call to the toString of the object is delayed until within the method itself, and only happens if debugging is on. This can save a significant amount of time when debugging is off.

Debug.println( "output = ", outputStruct );

Debug.println( "output = " + outputStruct );

The main() method of the Debug class has a demonstration of the performance differences of these two techniques.

For more complex conditional Debug operations, you can also use an if statement with the Debug.isDebugOn() method.

Finally, most of the tools in the tools package support the /D option, which turns on debugging mode for the tpm driver. This prints all the input and output bytes to/from the TPM.

To-Do List

Unresolved/Unexplained problems

• On an Intel Mac (with Infineon 1.2 chip), the TPMSeal tool returns a TPM_BAD_PARAMETER error if PCRs are specified. The same tool has been shown to work on a Broadcom 1.2 chip under Linux, and an Infineon TPM 1.1 chip under Windows XP.
• Signing a transport session log with an AIK works on a Broadcom 1.2 chip and an Infineon 1.2 chip (on the Mac), but fails on the ST Micro TPM 1.2 chip on a Gateway M465E. Strangely, signing with a non-AIK signing key works on the ST Micro chip. (However, signing a transport session log with a non-AIK key is not useful because such transport session logs can easily be forged using a TPM_Sign command using the same TPM, and so does not prove that the commands were actually executed, which is what signed transport session logs are supposed to prove.)

Others

1. Not all TPM commands have corresponding command classes yet. Continue to implement unimplemented ordinals.
2. Currently, transport sessions work enough to be usable for signing monotonic counter operation outputs. (This is the only way to get non-forgeable signed outputs certifying the value of the monotonic counters). At present, however, transport sessions do not fully support encryption. They also do not support all TPM Commands. (Some ordinals which require special HMAC handling may or may not work properly right now.)
3. NVRAM functions are working but not fully tested.
4. AIK creation creates usable AIKs, but has not been tested with real privacy CAs.
5. Javadoc documentation should be cleaned-up and produced.
6. Some of the examples can be improved or documented better. There are some tests or main functions in the funcs package, which can/should eventually be turned into independent tools classes.

Timing Tests

java edu.mit.csail.tpmj.tests.TPMTiming <ownerPwd> [srkPwd]

• This test will create a test key file in the process.
• Warning! This test extends some of the PCRs and may change your configuration, and these changes cannot be reversed without rebooting your machine. This may or may not interfere with other applications which depend on having a specific PCR configuration (e.g., to seal and unseal data).
• For TPM 1.1b chips, some of these demos will fail.

Other (Old) Tests

The code in the tpmj.tests folder is rough code intended to test certain features of TPM/J as well as give developers an idea of ways to use these features at a lower level. Note also that some of the classes in the tpmj.funcs folder contain their test code in their main() methods.

• Test running TPM commands in OIAP and OSAP sessions
• Test the PCR quoting functionality of the TPM
• Test a saved key
• Test the functionality of a monotonic counter
• Test the timing constraints of a monotonic counter
• Test the functionality of the transport sessions

Test running TPM commands in OIAP and OSAP sessions

java edu.mit.csail.tpmj.tests.TPMAuthTest <keyHandle>

Test the PCR quoting functionality of the TPM

java edu.mit.csail.tpmj.tests.TPMPcrTest <keyFile> <keyPassword>

Test a saved key

java edu.mit.csail.tpmj.tests.TPMPcrTest <keyFile> <keyPassword> <parentPassword>

Test the functionality of a monotonic counter

java edu.mit.csail.tpmj.tests.TPMCounterTest <counterID>

Test the timing constraints of a monotonic counter

java edu.mit.csail.tpmj.tests.TPMCounterTimingTest <counterID>

Test the functionality of the transport sessions

java edu.mit.csail.tpmj.tests.TPMTransTest <counterID>

Contributors

• Lead author: Luis Sarmenta (MIT CSAIL)
• Other Contributors:
  • Jonathan Rhodes(MIT CSAIL), some documentation and code
  • Thomas Müller (xnos.org), Windows Vista TBS proxy