Repository files navigation

This repository hosts source code implementing the Trusted Computing Group's (TCG) TPM2 Software Stack (TSS).This stack consists of the following layers from top to bottom:

[1] We currently deviate from the specification by increasing the value ofTPM2_NUM_PCR_BANKS from 3 to 16 to ensure compatibility with TPM2 implementations that have enabled a larger than typical number of PCR banks. This is expected to be included in a future revision of the specification.

Instructions to build and install tpm2-tss are available in theINSTALL file.

If you're looking to discuss the source code in this project or get some questions answered you should join the TPM2 mailing list:

• https://lore.kernel.org/tpm2/
• To subscribe write an email totpm2+subscribe@lists.linux.dev see alsohere
• The old listhttps://lists.linuxfoundation.org/mailman/listinfo/tpm2 was decomissioned by Linux

We also have an IRC channel set up onFreeNode called #tpm2.0-tss.You can also try Gitter

You can join a weekly online call atTPM.dev, where we are discussing the tpm2-tss stack, the tpm2-pkcs11 project and other Linux TPM2 & TSS2-Software.

In case you want to contribute to the project, please also have a look at theContribution Guidelines.

The doxygen documentation can either be built by oneself (see theINSTALL file) or browsed directly ontpm2-tss.readthedocs.io.

This repository contains a test suite intended to exercise the TCTI, SAPI and ESAPI code.This test suite isnot intended to test a TPM implementation, so this test suite should only be run against a TPM simulator.If this test suite is executed against a TPM other than the software simulator it may cause damage to the TPM (NV storage wear out, etc.).You have been warned.

The TPM library specification contains reference code sufficient to construct a software TPM 2.0 simulator.This code was provided by Microsoft and they provide a binary download for Windowshere.

There are two implementations that enable building and running this code on Linux.Issues building or running the simulator should be reported to respective project.

The Software TPM is an open-source TPM emulator with different front-end interfaces such as socket and character device. Its code is hostedon GitHub and building is faciliated by the GNU Autotools.The TCTI module for using this simulator is calledswtpm.

Since tpm2-tss v3.0 swtpm is the default simulator used by this project.

IBM has also repackaged this code with a few Makefiles so that the Microsoft code can be built and run on Linux systems.The Linux version of the Microsoft TPM 2.0 simulator can be obtainedon SourceForge.Once you've downloaded and successfully built and execute the simulator it will, by default, be accepting connections on the localhost, TCP ports 2321 and 2322.The TCTI module for using this simulator is calledmssim.

To test the various TCTI, SAPI and ESAPI api calls, unit and integration tests canbe run by configuring the build to enable unit testing and running the "check"build target. It is recommended to use a simulator for testing, and thesimulator will be automatically launched by the tests. Please review thedependency list inINSTALL for dependencies when buildingthe test suite.

$ ./configure --enable-unit --enable-integration$ make -j$(nproc) check

This will generate a file called "test-suite.log" in the root of the builddirectory.

Please report failures in a Github 'issue' with a full log of the test run.

NOTE: The unit and integration tests can be enabled independently.The --enable-unit option controls unit tests, and --enable-integrationcontrols the integration tests.

To run integration tests on a physical TPM device, including a TPM hardwareor a software TPM implemented in platform firmware the configure scriptprovides two options.The first option is called --with-device and it is used to point to the TPMdevice interface exposed by the OS, for example:

  $ ./configure  --with-device=/dev/tpm0

The second option, --with-devicetests, enables a "class" of test.There are three classes:

1. destructive - these tests can affect TPM capability or lifespan
2. mandatory - these tests check all the functionality that is mandatoryper the TCG specification (default).
3. optional - these tests are for functionality that is optional per theTCG specification.

For example to enable both mandatory and optional test cases during configureone needs to set this flag as follows:

  $ ./configure --with-devicetests="mandatory,optional"

Tht default value for the flag is "mandatory"Any combination of the three is valid.The two flags are only valid when the integration tests are enabled with--enable-integration flag.

After that the following command is used to run the test on the configuredTPM device:

  $ sudo make check-device

or

  $ sudo make check -j 1

Note: The tests can not be run in paralel.

The unit and integration tests can be run under the valgrind tool, whichperforms additional checks on the library and test code, such as memoryleak checks etc. The following command is used to run the tests undervalgrind:

$ make check-valgrind

This command will enable all valgrind "tools" and kick off as many testas they support. It is possible to enable different valgrindtools (checks) in more granularity. This can be controlled by invokingdifferent tools separately using check-valgrind-<tool>, for instance:

  $ make check-valgrind-memcheck

or

  $ make check-valgrind-drd

Currently the the following tools are supported:

memcheck - Performs memory related checks. This is the default tool.helgrind - Performs synchronization errors checks.drd - Performs thread related checks.sgcheck - Performs stack overrun related checks.

Note that the valgring tool can also be invoked manually using the standardlibtool:

  $ libtool exec valgrind --tool=memcheck --leak-check=full \    test/integration/esys-auto-session-flags.int

This allows for more control on what checks are performed.

While investigating issues it might be helpful to enable extra debug/traceoutput. It can be enabled separately for different components.The description how to do this can be found in thelogging file.

All system API function calls can be tested using a fuzzing library.The description how to do this can be found in thefuzzing file.

SAPI library, TAB/RM, and Test Code Block Diagram:

|-- doc     : various bits of documentation\|-- include : header files installed in $(includedir)\|   +-- tss2      : all public headers for this project\|-- lib     : data files used by the build or installed into $(libdir)\|-- m4      : autoconf support macros\|-- man     : man pages\|-- script  : scripts used by the build or CI\|-- src     : all source files\|   |-- tss2-esys : enhanced system API (ESAPI) implementation\|   |   +-- api   : ESAPI TPM API implementation\|   |-- tss2-mu   : TPM2 type marshaling/unmarshaling (MU) API implementation\|   |-- tss2-sys  : system API (SAPI) implementation\|   |   +-- api   : SAPI public API implementation\|   |-- tss2-tcti : TCTI implementations for device and mssim\|   +-- util      : Internal utility library (e.g. logging framework)\+-- test    : test code\    |-- integration : integration test harness and test cases\    |-- tpmclient   : monolithic, legacy test application\    +-- unit        : unit tests