IBM TSS

This creates the TSS_CONTEXT used in the TSS_Execute() function. It is initialized with the default configuration, which can be then changed using 3.4.3 TSS_SetProperty().

Returns an error if the context cannot be allocated, or if the properties cannot be initialized, typically due to an invalid environment variable.

It does not immediately open a connection, so that the connection properties can be changed from the default first.

The current default connects to the Microsoft format socket simulation. This will eventually change to connect to the resource manager.

The environment variables and TSS_SetProperty property use the same names. The makefile flag uses the name with _DEFAULT appended.

The environment variable overrides the compiler flag, and the TSS_SetProperty() function overrides both the compiler flag and the environment variable.

(Remember that the makefile compiler flag requires _DEFAULT to be added, and that the quotes must be escaped.).

TPM_TRACE_LEVEL

TPM_DATA_DIR

TPM_INTERFACE_TYPE

TPM_SERVER_NAME

TPM_SERVER_TYPE

TPM_COMMAND_PORT

TPM_PLATFORM_PORT

TPM_DEVICE

TPM_ENCRYPT_SESSIONS

Since session state can potentially hold secrets, it should normally be encrypted. When the process terminates, the ephemeral encryption key is lost.

See 4.9 Command Line Utilities for the special case of using the command line utilities. That section is not applicable when using the TSS library in programs.

The TSS_SetProperty() function overrides the defaults and environment variables programmatically.

If the property is related to the connection, an open connection is closed before the property is processed.

NOTE: The close occurs even if the new value is the same as the old value. This can be used to close a connection without deleting the context.

Question: Is it good to mandate this behavior? It offers functionality and makes the implementation easier, but perhaps it's too clever?

NOTE: The value parameter is always a string. For simplicity, the 'value' pointer is stored. The input should be a constant string.

NOTE: For the property TPM_TRACE_LEVEL, tssContext is ignored. The trace level is per process, not per context.

The extra parameter is a catch-all for any parameters that TSS_Execute() requires beyond the normal TPM command and response parameters.

TPM2_StartAuthSession needs the bind password so that it can calculate the session key.

The utility / demo applications cheat a bit, in that they call into TSS utility functions. These are less likely to be stable than the official API above.

The functions without the TSS_ prefix are deprecated. They were borrowed from the TPM side but used a signed value for the size. The functions prefixed TSS_ use an unsigned value for the size.

A typical cause of a hang when sending the first command to the TPM simulator is that it has not received a simulated "powered up." The IBM TPM simulator does not require this, but others may. Send this command:

The platform firmware initializes a hardware TPM. The TPM simulator requires this command:

The caller does NOT perform parameter encryption. Simply set the session attribute to either or both of TPMA_SESSION_ENCRYPT or TPMA_SESSION_DECRYPT.

To salt, the caller should set tpmKey (the handle of a loaded decrypt key) in TPM2_StartAuthSession. The key must be an RSA 2048-bit key or ECC NIST P256 key with sign clear and decrypt set.

The caller must supply the extra parameter as a StartAuthSession_Extra structure.

The caller does NOT supply the HMAC salt. The encryptedSalt parameter is ignored, as the TSS generates the salt.

To bind, the caller should set bind (the bind entity handle) in TPM2_StartAuthSession. The caller must supply the extra parameter as a StartAuthSession_Extra structure and set the bindPassword member to the bind handle password.

For applications that do not share an NV index and don't use global locks or transient locks or written status that change after a reboot, the following details are unnecessary. Just issue the TPM2_NV_DefineSpace and everything works, including HMAC sessions.

For applications that do not satisfy the above criteria, the application must issue TPM2_NV_ReadPublic and validate that the public area is as expected, including the locks.

This will not typically occur in real applications. The transient locks and written status permit low level firmware to perform pre-OS operations. By the time post-OS applications are running, the locks and written status should be restored.

Why? For authorization, the TSS includes the Name (a hash of the public NV metadata) in the HMAC calculation. This ensures that the NV index has not been replaced with a different version with untrusted metadata.

Normally, the TSS tracks the Name, even when the application changes the written or lock attributes. However, if the attributes (and therefore the Name) change outside the application, the TSS is unable to track the change. In those cases, the application must read the public data and validate it.

Why doesn't the TSS automatically issue the TPM2_NV_ReadPublic? If it did that, it would encourage the application developer to blindly trust the index. The application is expected to examine the TPM2_NV_ReadPublic return (e.g., the policy, the attributes) and decide whether the index is trusted. The TSS cannot enforce this, but it does at least encourage it.

The index Name can change as the metadata changes. These changes include the "written" bit and the read and write locks. The TSS automatically tracks the changes performed on a single index by the application. It does not track:

This will surface as an HMAC failure. The application should reissue TPM2_NV_ReadPublic and decide if the index is still trusted.

If the application is aware of the reboot, it can reissue TPM2_NV_ReadPublic and re-evaluate the return. Otherwise, it can wait for the potential HMAC failure and handle it as above.

This case will probably never occur in practice. If it does, handle the HMAC failure as above.

This is the case where some other application has used TPM2_NV_DefineSpace to pre-provision an index. As an alternative to the application evaluating the TPM2_NV_ReadPublic response, the NV metadata and Name can be pre-provisioned when the application is installed. Two files are required:

This command is unique, in that it has an optional parameter, TPM2B_SENSITIVE inPrivate. The caller should use the size as a flag: 0 for not present, and non-zero for present.

The TPM uses the inPrivate.size zero to indicate that the parameter is not present and uses the correct marshaled size to indicate that the parameter is present. This TSS uses that design pattern, but, as with other TPM2B's that wrap structures, it does not require the caller to marshal the structure and determine the correct size.

An issue arises when using the TSS utilities (not the TSS itself) on a platform with a resource manager. Windows 10 has a resource manager called TBS and Linux as of 4.12 uses /dev/tpmrm0.

A resource manager flushes all resources (objects like keys, and sessions) when a connection closes. Since the utilities are standalone processes, the connection closes after each invocation. Thus, for example, a utility can load a key, but, when the "load" command terminates, the resource manager will flush the key.

This is not an issue for a complete application using the TSS because the TSS keeps the connection open through multiple TPM commands. For prototyping using the utilities, the Linux solution is to bypass the resource manager using /dev/tpm0. For Windows 10, use a proxy to simulate this persistent connection behavior.

The "tpmproxy" program connects as a socket server on one side and a TPM device driver on the other. Once the proxy starts, the Windows resource manager sees one persistent connection, as desired. The utilities use the socket interface to the proxy.

Both the TSS and the proxy support both a raw packet format and the Microsoft simulator wrapped format.

The default, using the wrapped format, can also be specified on the TSS side with

There is no reason for a user to trust these certificates. Obtain production certificates directly from the TPM vendor.

These URLs are provided for convenience. Observe that some URLs are http. I encourage all readers to ask the TPM vendors to offer these certificates over a secured web page, since they form the root of trust for TPM authenticity.

Utilities such as "createek" that take a -root argument require a list of EK root certificates in a file. The utilities include a sample file …/utils/certificates/rootcerts.txt. The file MUST be edited, since the file names must have a complete path to your install directory.

The file must have a Unix newline (only LF, 0x0a), not a DOS newline, even on Windows platforms.

Certificates must be in PEM format. To convert from DER format (.cer, .crt) to PEM using openssl:

This list was extracted from http://www.st.com/resource/en/data_brief/stsw-tpmcert1.pdf

As of June 2017, the Intel PTT did not come provisioned with EK certificates. They must be downloaded using this procedure.

As stated in section 3.4.2 Properties, the default is to build the TSS library to encrypt session state with an ephemeral encryption key that is lost when the application exits.

This behavior would preclude using the command line utilities with sessions, since the encryption key would change. There are two facilities to remedy this.

This is new code in 2018. The TSS for TPM 1.2 uses the identical API as in section 3 API, but with TPM 1.2 structures and ordinals.

There is currently support for about 20 TPM 1.2 commands, specifically those commands that are required to implement an attestation client. It also includes support commands to create a SW TPM EK certificate and the activate identity blob, and to extend firmware and IMA event logs into a TPM for testing. More commands can be easily added upon user request.

The utilities and a basic regression test (reg.sh) are in the ../utils12 directory.

The regression test requires a software TPM 1.2 that is 'straight from the factory' - with no TPM state. The reason is that creating the standard TCG EK certificate requires an unlocked TPM. Once NV is locked, it can never be unlocked. Before running the regression test, remove the state and restart the TPM.

The standard TPM 1.2 is opt-in and is shipped disabled and deactivated. While the IBM software TPM comes with tools to enable and activate the TPM, users may find it less of a nuisance to use 'makefile-en-ac' to build a TPM that is already enabled and activated at its first start.

There are also two examples that show how several commands can be chained together to form an application

The signapp.c source demonstrates how the TSS handles bind and salt sessions. It uses sample code to create an EK. It uses a policy session to authorize the EK. It authorizes a signing key using both HMAC and policy sessions, where the policy can be policy password or policy authvalue. The signing key policy also has an AND term for the command code 'sign'.

The writeapp.c source demonstrates how the TSS handles bind and salted session, and tracks entity Name changes without application coding.

In addition to the command line tools for each TPM command, there are several utilities that are useful for development.

They accept various digest and asymmetric algorithms and other options as applicable. Use -h for details.

It is occasionally useful to debug a command packet obtained from a source other than the TSS.

It takes a hex ascii input command string so that TSS processing is excluded. The string can be obtained by running the command first with -v and capturing the TSS trace.

These tools provide primitive aids to calculating and debugging policies. The regression test script comments explain how the tools were used to calculate the test policies. The utils/policies directory holds both the 'source' hexascii and binary policies.

This tool accepts a set of hex ascii AND terms, one per line, and calculates the resulting policy. An empty policyRef is represented by a blank line.

The result can be traced and/or output in binary in a format directly usable as a utility input.

-v traces the intermediate terms. In combination with policygetdigest, it can be used to debug a policy term by term.

-ns (no white space) traces the output in a format that can be used as input to a policy OR (which is just a concatenation of AND terms).

-nz calculates the hash without the normal 'extend starting with zeros', useful for calculating an 'aHash' such as a cpHash.

This tool calculates a policypcr AND term in a format suitable for input to policymaker. It accepts a bit mask of selected PCRs and a white list of PCR values, one per line.

This tool calculates a TPM Name from a TPM object or NV public structure, or from a PEM or DER format public key.

This is useful for constructing policies at times that the TPM is not available to calculate the Name.

This function is also integrated into several tools, such as create, createprimary, createloaded, and readpublic.

The package has sample functions for parsing pre-OS and post-OS (IMA) event logs. These tools aggregate some of these functions.

The builds for Linux and Windows create the TSS shared object / dll and about 110 command line programs. The command line programs can be used in a script for rapid prototyping or as sample usage code.

The build files clear TPM_ENCRYPT_SESSIONS, which is useful for prototyping and regression testing. This should be removed for production applications.

Several compile time macros permit building a variation of the TSS library. Features may be lost, but the tradeoff may be important in some environments.

Since the regression test does not function against all builds, some variations are very lightly tested. Please report bugs.

Define one of these for a POSIX (Linux, AIX, Raspian, zLinux, etc.) or Windows TSS.

Defining this macro builds a TSS library that does not use files for temporary and persistent state. All state is stored in the TSS context and is lost when the context is deleted.

Defining this macro builds a TSS library that does not depend on a crypto library.

Defining this macro builds a TSS that does no tracing and compiles out all print functions.

Defining this macro builds a TSS that does not require crypto library elliptic curve support.

Defining this macro builds a TSS that does not require crypto library RSA support.

Defining this macro builds a TSS that does not call the getenv() function. This supports platforms that do not implement environment variables.

The TSS properties still use defaults that can be changed at build time, and it still supports the TSS_SetProperty() function.

Defining this macro builds a TSS that does not include the socket interface. This supports platforms that do not implement sockets.

Defining this macro builds a TSS that does not implement input parameter checking. The commands are sent as-is to the TPM, which will presumably do its own check.

The main disadvantage of this macro is that debugging is harder. Rather setting breakpoints in the TSS to debug, the developer must rely on the TPM return codes.

Defining this macro removes deprecated TPM functions, This slightly reduces the library size in cases where the application is not using the functions

Defining this macro adds TSS support for the Nuvoton proprietary TPM configuration commands.

…/utils/policies TSS for TPM 2.0 regression test policies and miscellaneous files

These are the mainstream TPM 2.0 instructions. For the new TPM 1.2 support, see the application note in 4.10 TSS for TPM 1.2.

Note: OpenSSL 1.1.x cannot validate early TPM 1.2 EK certificates. Newer TPM 1.2 certificates and TPM 2.0 certificates validate.

After building, run the regression test against a running simulator. -h gives help. The Linux version takes about 1 minute.

The regression test can run against a software TPM at /dev/tpm0. It will skip the power up sequence. However, it uses the environment variable TPM_INTERFACE_TYPE as the determination. If the default TPM_INTERFACE_TYPE was changed at compile time, the regression test will try the power up sequence unless the environment variable is also set.

The regression test does not run against a hardware TPM, since the platform firmware will have set the platform authorization. There are likely to be other errors due to protected or unsupported TPM features.

Install OpenSSL 1.1.1. The usual place to get OpenSSL for Windows is http://slproweb.com/products/Win32OpenSSL.html. Install Win32 OpenSSL, not the "Light" versions, which I believe do not contain the development files. For use with mingw, use the 32-bit build.

I put the OpenSSL DLLs in the OpenSSL binaries directory. I don't know if this matters.

If you chose not to install OpenSSL in this location, you must fix the build paths. In other words, use the recommended location.

This directory should be added to the Path environment variable if it's not already there:

Hardware TPM development requires the Windows 10 SDK, available here: https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk

After building, run the regression test against a running simulator. The Windows version takes about 15 minutes.

The Windows script assumes that typical command line tools such as touch and diff are installed. A typical download location is

The regression test script defaults to the executables being in the same directory as the script, …/tpm2/utils. This is correct for the gcc build, but not for the Visual Studio build. To point to those executables, set this environment variable. Do not omit the trailing slash.

A mingw (Minimalist GNU for Windows) makefile.mak is included. mingw from http://www.mingw.org/ must be installed.

VS solution and project files are supplied. The Visual Studio 2017 Solution is …/tpmutils/tpmutils.sln.

The default is to connect to the socket simulator using the Microsoft simulator packet format. To change the default from a SW TPM to a HW TPM, add the preprocessor definition:

The VS project defines TPM_WINDOWS_TBSI , so the TSS build supports the socket and hardware TPM interface. Users that use only the socket interface may not want to install Tbsi (Windows TPM Base Services). Undefine TPM_WINDOWS_TBSI.

After building, run the regression test against a running Microsoft simulator. -h gives help. Since the TPM simulator does not run on AIX yet, set the TPM_SERVER_NAME environment variable.

This section is only relevant to a Fedora rpm install. It is a work in progress and may not be 100% correct yet.

NOTE: The utility command line arguments are not stable. They change occasionally to improve consistency among utilities or to add features

The utilities currently do not permit all TPM command options. Let me know what needs enhancement.

There are many issues with making a TSS thread safe, because the TPM is inherently single threaded. For example:

I think the best we can do is provide a common "TSS lock semaphore" mechanism, so that threads can coordinate access to the TSS using a common API.

The instructions in 3.4 Optional Customization and elsewhere are often specific to one Unix shell. See your shell documentation for variations. Windows uses yet another syntax.

Settings are local to one process (to one window). When the process exits (when the windows is closed), the setting is lost. To create a persistent setting, use a dotfile (Unix) or a control panel setting (Windows.)

Windows blocks executables with the strings setup, install, update, and patch in the name. Thus, TPM utilities like sequenceupdate.exe will not run.

One work around is to run the commands shell as administrator. Right click "Command Prompt" and select "Run as administrator".

A failure linking with OpenSSL on Windows is very often caused by multiple versions of OpenSSL installed on the platform. The easiest solution is to run the uninstaller, delete all the OpenSSL directories, and then install just once.

The Windows 10 crypto library has function names that clash with OpenSSL, particularly in the area of X.509 support. Visual Studio includes it by default when using. To remove those headers, define WIN32_LEAN_AND_MEAN. Use the command line utilities as samples.

If an object such as a key is loaded successfully in a script but then seems to disappear, it is likely the interaction with the resource manager. The resource manager detects that the process (one line of the script) exits and then frees all allocated resources.

This occurs with a hardware TPM - always on Windows and with Linux when connecting to /dev/tpmrm0. It will not occur when connecting directly with a software TPM or a hardware TPM at /dev/tpm0, which bypasses the resource manager. It will also not occur once the prototyping script is replaced by an executable that does not close the connection after each TPM command.

The solution is to use a proxy, which keeps the TPM connection alive. See section 4.7 Connecting to Resource Managers.