Compatibility

The SDK is compatible with the Trusted Computing Group's TPM 2.0 spec. The most recent version of the TPM 2.0 specification (Level 00, Revision 01.38) includes the use of a nonce, which is incompatible with the current version of the Intel® EPID scheme. Therefore, this implementation of Intel® EPID APIs is compatible with an earlier version, which is the TPM 2.0 specification Level 00, Revision 1.16.

Considerations for TPM Manufacturers

This section explains what manufacturers have to do with the SDK in order to have their TPMs recognized to a service provider:

Provisioning TPM devices with crypto secrets
Adapting SDK code to specific TSS functionality

This SDK was tested on the IBM TPM and TSS (Trusted Computing Group Software Stack). Device manufacturers should replace specific items with their own TPM functionality.

Provisioning TPM with Intel® EPID Key Material

For TPM use with Intel® EPID, members and verifiers need to be provisioned with crypto material to enable security function.

In order to ensure that the f value only exists in the volatile memory of the TPM, TPM manufacturers need to provision the TPM with an EPS (Endorsement Primary Seed), from which the f value of the member private key is derived.

Typically, bulk provisioning is more efficient than dynamic provisioning in a manufacturing environment. However, bulk provisioning is not viable for TPM devices for the following reasons:

In bulk provisioning, the issuer provides f as part of each member private key, but it is intentionally difficult to derive EPS from f.
The issuer cannot provide EPS to manufacturers because the translation from EPS to f is dependent upon an implementation specific, deterministic random number generator.

Therefore, in order to provision the TPM with EPS, Intel supports a variation on typical dynamic provisioning in which manufacturers provide their own EPS.

In this variation on dynamic provisioning, which we call bulk-join, some steps are performed in bulk and credentials for many devices can be generated at the same time. This process allows TPM devices to be provisioned during manufacturing.

For bulk-join, TPM device manufacturers need to do the following:

Generate a set of EPS, because EPS are the seeds from which the f values of the member private keys are generated.
Derive a set of f values from the EPS values.
Request a set of nonces from the issuer which will be used to generate join requests.
Generate a set of join requests using the f values and nonces and send them to the issuer. The issuer will respond to the bulk join requests by sending membership credentials to the manufacturer in bulk.
Provision the membership credentials in silicon, mapping each membership credential to the corresponding EPS value.

The following graphic shows how the issuer, manufacturer, TPM, and member interact during the time of key generation, device manufacturing, and signing:

Mapping TPM Commands to Intel® EPID

APIs

The tpm2 module in the member section of the API reference contains internal functions that map to TPM commands. This code is provided as sample code for manufacturers who will use it to write their own implementation of Intel® EPID APIs for TPM.

Intel® EPID Function	Corresponding TPM 2.0 Command
Tpm2Commit	TPM2_Commit
Tpm2CreateContext	N/A
Tpm2DeleteContext	N/A
Tpm2GetRandom	TPM2_GetRandom
Tpm2LoadExternal	TPM2_LoadExternal
Tpm2NvDefineSpace	TPM2_NV_DefineSpace
Tpm2NvUndefineSpace	TPM2_NV_UndefineSpace
Tpm2NvWrite	TPM2_NV_Write
Tpm2NvRead	TPM2_NV_Read
Tpm2Sign	TPM2_Sign

Considerations for TPM Applications

Unlike non-TPM device manufacturers, TPM manufacturers cannot use EpidProvisionKey. TPMs are designed to protect secret values from access even by the programs that use them. Dynamic provisioning is specifically designed to allow this use case.

To get a TPM device running, TPM applications can use the following steps to join a group using a TPM protected secret:

Use EpidMemberGetSize and EpidMemberInit to create a new member context. Those functions take the parameter MemberParams. You will pass NULL to this struct instead of the f value, which indicates that f needs to be derived from the EPS within the TPM.
Use EpidCreateJoinRequest to generate join requests using the f derived from EPS within the TPM. Then send the join request to the issuer to request a membership credential.
After receiving the membership credential (A, x), use EpidProvisionCredential to provision it into the non-volatile memory of the TPM device.

After the TPM device is provisioned with EpidProvisionCredential, the simplest way to get the device running is:

SDK Member Architecture

In the SDK, the Tpm2 module exposes commands that can be mapped to real TSS commands.

The Member Host (member/src) implements Intel® EPID signing in terms of TPM2 commands.

The TPM module (member/tpm2) implements TPM2 commands.

There are two implementations of TPM functionality:

BM TSS dispatcher implementation (member/tpm2/ibm_tss), which calls the IBM TSS, which calls the IBM TPM simulator (in this implementation). It is invoked when building in TPM mode.
TPM SDK software implementation (member/tpm2/src) implements sufficient TPM functionality for Intel® EPID. It is invoked when building in non-TPM mode.

Building the SDK to Take Advantage of TPM

This section describes:

Prerequisites to building the SDK to take advantage of TPM
Building the SDK in TPM mode
Running signing and verification operations with TPM

Prerequisites to Build the SDK in TPM Mode

Download IBM TSS version 966. (The SDK was tested on version 966. Newer versions may also work, but we do not guarantee it.)
Download IBM TPM version 532. (The SDK was tested on version 532 and does not work on newer versions.)
Build the IBM TSS in accordance with the build steps from the package. Copy tss.lib and tss.dll from ibmtss\tpmutils\Release to ibmtss\utils.

Building the SDK in TPM Mode

Set the TSSROOT environment variable to the ..\ibmtss\utils\ folder. Make sure this folder contains the \tss2 folder, tss.lib and tss.dll. Example of the command for Windows:

> set TSSROOT=C:\ibmtss\utils\

To build the SDK in TPM mode, go to the SDK folder and build the SDK with the following command:

> scons --target=x86 --use-tss

To build the SDK in TPM mode using make command, go to the SDK folder and build the SDK with the following commands:

> ./configure CFLAGS=-m32 --with-tss
> make all
> make utest
> make install

Because the IBM TSS only supports x86 targets, you must build in x86.

Intel® EPID Signing and Verification with a TPM

Build the IBM TSS (see above).
Build the IBM TPM (see above).
Build the Intel® EPID SDK with --target=86 --use-tss (see above).
Copy tss.dll from _install/epid-sdk/test to _install/epid-sdk/example.
Go to the ibmtpm folder and run the tpm_server executable. Note: if you built the TPM server with the MS Visual Studio debug mode, go to the ..\ibmtpm\tpmvstudio\tpm_server\Debug\ folder.
You need to run both the TPM server and the powerup and startup executables on IBM TSS. Go to ..\ibmtss\tpmutils\Debug\ or ..\ibmtss\tpmutils\Release\ and run powerup and startup executables.

Then you can run:

> signmsg --hashalg=SHA-256 --msg="test"

Note: In TPM mode samples have to be used with --hashalg=SHA-256.

If signing succeeds, nothing is returned.

Then run:

> verifysig --hashalg=SHA-256 --msg="test"
-signature verified successfully

Warning: The samples use LoadExternal to load keys into the TPM. In a real TPM use case, CreatePrimary should be used, and the SDK implementation provides functions for this use case.

Table of Contents