IBM TPM 2.0 (and 1.2) TSS API
Ken Goldman
IBM Research
kgoldman@us.ibm.com
January April 215,
20230
4............ Application Notes
4.7. Connecting
to Resource Managers
4.8. Endorsement
Key (EK) Certificates
4.8.5.1. Intel EK
Certificate Download
7.1.1. TPM_TPM20
and TPM_TPM12
7.1.2. TPM_POSIX
or TPM_WINDOWS
8.2. Alternative
Local Install
11.2. Command
line utilities fail on Windows 10
11.3. OpenSSL
Linking on Windows
11.4. Loaded
objects (keys) disappear
The IBM TSS is designed for:
The package is upstreamed to
The TSS handles the following, completely hidden from the caller:
and almost hidden from the caller:
The API consists of the following calls:
#include <ibmtss/tss.h>
TPM_RC TSS_Execute(TSS_CONTEXT *tssContext,
RESPONSE_PARAMETERS *out,
COMMAND_PARAMETERS *in,
EXTRA_PARAMETERS *extra,
TPM_CC commandCode,
...);
This is the primary TSS function.
tssContext: Opaque object
out: The standard TPM2 Part 3 response parameter
in: The standard TPM2 Part 3 command parameter
extra: Some commands (only two so far) require extra parameter s.
commandCode: The standard TPM2 Part 2 command code.
. . . : A list of session 3-tuples , of the form
TPMI_SH_AUTH_SESSION sessionHandle,
const char *password,
unsigned int sessionAttributes
The list is terminated with (TPM_RH_NULL, NULL, 0)
#include <ibmtss/tss.h>
TPM_RC TSS_Create(TSS_CONTEXT **tssContext);
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.
See 3.3 TSS_Delete().
It does not immediately open a connection, so that the connection properties can be changed from the default first.
#include <ibmtss/tss.h>
TPM_RC TSS_Delete(TSS_CONTEXT *tssContext);
The deletes the opaque context created using 3.2 TSS_Create().
It closes an open connection.
Returns an error if the connection close fails.
The TSS is designed to work by default with no configuration.
The current default connects to the Microsoft format socket simulation. This will eventually change to connect to the resource manager.
There are three ways to customize the configuration:
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.
To change the default TPM interface to the TPM device driver:
-DTPM_INTERFACE_TYPE_DEFAULT="\"dev\""
> setenv TPM_INTERFACE_TYPE dev
rc = TSS_SetProperty(tssContext, TPM_INTERFACE_TYPE, "dev");
(Remember that the makefile compiler flag requires _DEFAULT to be added, and that the quotes must be escaped.).
The property and legal values are:
default - 0
0 - no tracing
1 - trace errors
2 - trace errors and execution flow
default - current directory
set the directory where the TSS can store persistent data
default - socsim
socsim - the socket simulator
see
TPM_SERVER_NAME
TPM_SERVER_TYPE
TPM_COMMAND_PORT
TPM_PLATFORM_PORT
dev - TPM device driver
see
TPM_DEVICE
default - localhost
set the socket server name (full host name or dotted decimal)
Used with TPM_INTERFACE_TYPE = socsim
default - mssim
mssim - send packets in the Microsoft simulator format (header and footer)
raw - send packets in the raw TPM 2.0 specification Part 3 format
rawsingle - same as raw but opens and closes the connection for each command
(useful with the IBM SW TPM 1.2 simulator)
default - 2321
set the socket port for TPM commands
default - 2322
set the socket port for TPM simulator platform commands
Unix/Linux default - /dev/tpm0 (single user)
Windows default - Windows 7,8,10 Tbsi
For Unix, sets the TPM device name
/dev/tpmrm0 is the multi-user kernel resource manager
Once the kernel resource manager is upstreamed, this
may become the default.
For Windows, not currently used, only Tbsi supported
default 1
1 - Session state is saved encrypted
0 - Session state is saved in plaintext
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.
default 0
set the locality for transmitting a command.
This property only affects the TPM_INTERFACE_TYPET socsim and TPM_SERVER_TYPE mssim. That is, the SW TPM packet format permits a locality specifier. HW TPM locality requires hardware support and cannot typically be set by an OS level application.
The main use case for this property is to send TPM2_Startup at a different locality to simulate the UEFI event EV_NO_ACTION, which sets PCR 0 to the startup locality.
#include <ibmtss/tss.h>
TPM_RC TSS_SetProperty(TSS_CONTEXT *tssContext,
int property,
const char *value);
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.
Headers are in the /utils/ibmtss directory.
#include <ibmtss/tss.h>
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.
Several areas have non-obvious usage. They are described here.
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:
> powerup
The platform firmware initializes a hardware TPM. The TPM simulator requires this command:
> startup
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:
[01nnnnnn] is the hex value of the NV index.
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.
Rationale:
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
> TPM_INTERFACE_TYPE=socsim
> TPM_SERVER_TYPE=mssim
and the tpmproxy with -mssim.
The raw format can be specified with
> TPM_INTERFACE_TYPE=socsim
> TPM_SERVER_TYPE=raw
and the tpmproxy with -raw.
The TSS includes several TPM vendor EK root certificates for convenience.
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:
> openssl x509 -in cert.cer -inform DER -out cert.pem
https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton%20TPM%20Root%20CA%202110.cer
https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton%20TPM%20Root%20CA%201110.cer
https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton%20TPM%20Root%20CA%202111.cer
https://www.nuvoton.com/security/NTC-TPM-EK-Cert/NuvotonTPMRootCA1210.cer
https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton
TPM Root CA 2112.cer
https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton
TPM Root CA 1111.cer
This list was extracted from http://www.st.com/resource/en/data_brief/stsw-tpmcert1.pdf
GlobalSign Trusted Computing CA
http://secure.globalsign.com/cacert/gstpmroot.crt
ST TPM Root certificate
http://secure.globalsign.com/cacert/stmtpmekroot.crt
ST Intermediate CA 01
http://secure.globalsign.com/cacert/stmtpmekint01.crt
ST Intermediate CA 02
http://secure.globalsign.com/cacert/stmtpmekint02.crt
ST Intermediate CA 03
http://secure.globalsign.com/cacert/stmtpmekint03.crt
ST Intermediate CA 04
http://secure.globalsign.com/cacert/stmtpmekint04.crt
ST Intermediate CA 05
http://secure.globalsign.com/cacert/stmtpmekint05.crt
GlobalSign Trusted Platform Module ECC
Root CA
http://secure.globalsign.com/cacert/tpmeccroot.crt
STM TPM ECC Root CA 01
http://secure.globalsign.com/stmtpmeccroot01.crt
STM TPM ECC Intermediate CA 01
http://secure.globalsign.com/stmtpmeccint01.crt
https://www.infineon.com/cms/en/product/promopages/optiga_tpm_certificates
Root
https://pki.nationz.com.cn/EkRootCA/EkRootCA.crt
Intermediate certificates
https://pki.nationz.com.cn/EkMfrCA001/EkMfrCA001.crt
https://pki.nationz.com.cn/EkMfrCA002/EkMfrCA002.crt
https://pki.nationz.com.cn/EkMfrCA003/EkMfrCA003.crt
PTT EK Root Certificate
https://upgrades.intel.com/content/CRL/ekcert/EKRootPublicKey.cer
PTT EK Intermediate Certificate
http://upgrades.intel.com/content/CRL/ekcert/SPTHEPIDPROD_EK_Platform_Public_Key.cer
As of June 2017, the Intel PTT did not come provisioned with EK certificates. They must be downloaded using this procedure.
See also section 4.7 Connecting to Resource Managers.
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.
> setenv TPM_ENCRYPT_SESSIONS 0 (csh, tcsh)
> export TPM_ENCRYPT_SESSIONS=0 (bash)
> set TPM_ENCRYPT_SESSIONS=0 (windows)
or the equivalent compile time flag
-DTPM_ENCRYPT_SESSIONS_DEFAULT="\"0\""
In the script:
TPM_SESSION_ENCKEY=`./getrandom -by 16 -ns`
On the command line:
> setenv TPM_SESSION_ENCKEY `./getrandom -by 16 -ns`
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.
To build a combined TPM 2.0 and TPM 1.2 TSS:
> make -f makefiletpmc clean all
To build a TPM 2.0 only TSS
> make -f makefiletpm20 clean all
To build a TPM 1.2 only TSS
> make -f makefiletpm12 clean all
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.
Each standalone utility serves as an example for a single command.
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.
Prints a TPM or TSS hex response code as text.
Prints a TPM hex attribute as text.
It supports object, session, startup, and NV attributes.
This is useful for profiling - timing the duration of a single command.
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.
This tool is restricted to commands that:
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 tools aggregates several EK manipulation tasks:
This tools provisions an EK certificate in TPM NV for testing.
The EK is generated based on TCG standards.
This tools converts an existing TPM format public key to PEM format.
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.
This tool parses a pre-OS (BIOS, UEFI) event log. It can:
This tool parses a post-OS Linux IMA log. It can:
To permit scripting a test platform, it can accept beginning and ending events.
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.
There are currently makefiles for common build options, listed later.
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 or both of these for a TSS that supports TPM 2.0 and/or TPM 1.2.
TPM 1.2 support is incomplete. See section 4.10 TSS for TPM 1.2.
Define one of these for a POSIX (Linux, AIX, Raspian, zLinux, etc.) or Windows TSS.
For Windows, compiles in hardware TPM support.
This was useful to remove hardware TPM support for Windows 7, where the TPM 2.0 install required several hacks. Since Windows 10 supports TPM 2.0, there is little reason not to define this macro.
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.
Drawbacks:
Defining this macro builds a TSS library that does not depend on a crypto library.
Drawbacks:
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.
When this macro is defined, TPM_INTERFACE_TYPE defaults to dev, not socsim.
Defining this macro builds a TSS that does not include the TPM device driver interface.
The main use for this macro is a Windows platform using mingw. mingw does not apparently support the Tbsi interface.
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.
ThisTh
twoe two main use cases of this macro are:
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.
To skip those algorithms in the regression test, set the environment variable TPM_TSS_NODEPRECATEDALGS.
Defining this macro
removes deprecated crypto algorithms from both the TSS
and the command line utilities. If the algorithm
is used, the TSS returns an error.
Currently, the only
algorithm removed is SHA-1.
Defining this macro
adds TSS support for the Nuvoton proprietary TPM configuration commands.
The TSS ships with these directories:
/utils TSS for both TPM 1.2 and TPM 2.0.
TPM 2.0 utility / demo applications
/utils/regtests TSS for TPM 2.0 regression tests
/utils/policies TSS for TPM 2.0 regression test policies and miscellaneous files
/utils/certificates TPM for TPM 2.0 and TPM 1.2 vendor EK root certificates
/utils12 TPM 1.2 utility / demo applications
TSS for TPM 1.2 regression test
/demo TSS for TPM 2.0 demo web pages
/tpmutils TSS for TPM 2.0 Visual Studio files
To extract the tarball
> cd
> tar xvf ibmtssnnn.tar .
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.
Install OpenSSL 1.0.x or 1.1.x.3.x., including
the development package.
Note:
OpenSSL 1.1.x cannot validate early TPM 1.2 EK certificates. Newer TPM 1.2 certificates and TPM 2.0
certificates validate.
> cd /utils
> make -f makefiletpm20c
Note: Linux builds must have TPM_POSIX defined.
After building, run the regression test against a running simulator. See 7.5 Regression Test.
After building, run the regression test against a
running simulator. -h gives help. The Linux version takes about 1 minute.
> ./reg.sh -a
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.
Use the regression test for TSS verification, not
as a TPM test tool.
The TPM device driver normally does not permit non-root access. Either
> chmod 777 /dev/tpm0
or run as root or sudo.
Read all of this. Its tricky.
Install OpenSSL 3.1 64-bit. Install Win64 OpenSSL,
not the "Light" versions, which I believe do not contain the
development files. The usual place to get OpenSSL binaries for Windows is:
http://slproweb.com/products/Win32OpenSSL.html
Recent Shining Light installs point to
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.
There is no need to build / compile from
source. Just run the downloaded .exe.
I put the OpenSSL DLLs in the OpenSSL binaries
directory. I don't know if this matters.
Recent Shining Light installs point to
C:\OpenSSL-Win3642
Change this to
C:\Program Files\OpenSSL
If you chose not to install OpenSSL in this location, you must fix the build paths. In other words, use the recommended location.
After install, copy
C:\Program Files\openssl\bin\libcrypto-1.1.dll
to
C:\Program Files\openssl\bin\libcrypto.dll.
Please contribute a fix to eliminate this step.
This directory should be added to the Path environment variable if it's not already there:
c:\Program Files\OpenSSL\bin
Note: Windows builds must have TPM_WINDOWS defined.
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. See 7.5 Regression
Test.
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
http://gnuwin32.sourceforge.net/packages.html
See CoreUtils and
DiffUtils.
> reg.bat
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.
> set TPM_EXE_PATH=..\tpmutils\Debug\
A mingw (Minimalist GNU for
Windows) makefile.mak is included. mingw from http://www.mingw.org/
must be installed.
Issues:
For these reasons, the Visual Studio project is recommended.
Contributions to fix thisese
isare
welcome.
> cd /utils
> make -f makefile.mak
VS solution and project files are supplied. The Visual Studio 202217
Solution is
/tpmutils/tpmutils.sln.
The .lib should be in c:\program
files\openssl\lib\vc.
If not
Common Properties
Expand Linker, General
Change Additional Library Directories
to
the correct path
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:
TPM_INTERFACE_TYPE_DEFAULT="dev"
These instructions have been tested for Windows 10
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.
Note: To define the macro in Visual Studio:
1.
View - Other
Windows - Property Manager
1.
Expand one of the
projects
1.
Expand Debug (or
Release if doing a release build)
1.
Double click
CommonProperties
1.
Expand Common
Properties, then C/C++, then select Preprocessor
1.
Next to
Preprocessor Definitions, click the value, then the down arrow, then
<Edit>
1.
Remove the macros
TPM_WINDOWS_TBSI and TPM_WINDOWS_TBSI_WIN8
1.
OK, OK
Note: The TPM_WINDOWS_TBSI_WIN8 macro also supports
Windows 10.
After building for
Windows or Linux, run the regression test against a running simulator.
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.
Use the regression
test for TSS verification, not as a TPM test tool.
Windows,
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
http://gnuwin32.sourceforge.net/packages.html
See
CoreUtils and DiffUtils.
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.
> set
TPM_EXE_PATH=..\tpmutils\x64\Debug\
> set
TPM_EXE_PATH=..\tpmutils\x64\Release\
> reg,bat
Linux,
takes about 5 minutes:
> ./reg.sh -a
Selective tests can
be run. See reg.sh -h for the test
numbers.
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.
This is a contribution. I did not test it.
· install homebrew
· install openssl -> brew install openssl
· install gawk -> brew install gawk
· set PATH of shell (terminal):
PATH=/usr/local/Cellar/openssl/1.0.2m/bin/:$PATH
PATH=/usr/local/Cellar/gawk/4.2.0/bin/:$PATH
Make this permanent by adding to a profile.
· Build using makefile.mac
Use gnu make (gmake), not make.
> cd /utils
> gmake -f makefile.aix
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.
> reg.sh -a
This section is only relevant to a Fedora rpm install. It is a work in progress and may not be 100% correct yet.
Prerequisite:
# yum install rpm-build
Download the rpms:
TBD
1. Install binaries:
# rpm -ivh ibmtss-nnn-1.el6.x86_64.rpm
2. Install development headers:
# rpm -ivh ibmtss-devel-nnn-1.el6.x86_64.rpm
3. Install debug source and support
# rpm -ivh ibmtss-debuginfo-nnn-1.el6.x86_64.rpm
Erase an old version as needed:
# yum erase ibmtss-devel-nnn-1.el6.x86_64
# yum erase ibmtss-nnn-1.el6.x86_64
# yum erase ibmtss-debuginfo-nnn-1.el6.x86_64
Install (new method)
# dnf install ./ibmtss-nnn-1.el6.x86_64.rpm
# dnf install ./ibmtss-devel-nnn-1.el6.x86_64.rpm
# dnf install ./ibmtss-debuginfo-nnn-1.el6.x86_64.rpm
Install (old method)
# yum install ./ibmtss-nnn-1.el6.x86_64.rpm
# yum install ./ibmtss-devel-nnn-1.el6.x86_64.rpm
# yum install ./ibmtss-debuginfo-nnn-1.el6.x86_64.rpm
Once the packages have been upstreamed, use this process.
# dnf install ibmtss
This assumes that the SW TPM has been installed, see this link:
https://sourceforge.net/projects/ibmtpm20tss/?source=navbar
It also assumes that the regression test has been installed. See Section 8.5.
In reg.sh, change the utility prefix variable to tss.
PREFIX=tss
Run the regression test:
> cd ~/rpmbuild/BUILD/ibmtss-nnn/utils
> ./reg.sh
Install source (as non-root user)
> rpm -ivh ibmtss-nnn-1.el6.src.rpm
The src rpm has a tarball and spec file.
The utilities serve several purposes:
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.
Please report bugs.
These may "just work" but they have not been tested yet.
Users are welcome to suggest ECC tests and prioritize the below list.
The TSS is not thread safe.
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.
This section includes some frequent issues and solutions.
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.