1[](https://travis-ci.org/tpm2-software/tpm2-tss) 2[](https://ci.appveyor.com/project/tpm2-software/tpm2-tss) 3[](https://cirrus-ci.com/github/tpm2-software/tpm2-tss) 4[](https://scan.coverity.com/projects/tpm2-tss) 5[](https://codecov.io/gh/tpm2-software/tpm2-tss) 6[](https://bestpractices.coreinfrastructure.org/projects/2332) 7[](https://lgtm.com/projects/g/tpm2-software/tpm2-tss/alerts/) 8[](https://lgtm.com/projects/g/tpm2-software/tpm2-tss/context:cpp) 9[](https://tpm2-tss.readthedocs.io/en/latest/?badge=latest) 10[](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:tpm2-tss) 11[](https://gitter.im/tpm2-software/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) 12 13# Overview 14This repository hosts source code implementing the Trusted Computing Group's (TCG) TPM2 Software Stack (TSS). 15This stack consists of the following layers from top to bottom: 16 17* Feature API (FAPI) as described in the [TSS 2.0 Feature API Specification](https://trustedcomputinggroup.org/wp-content/uploads/TSS_FAPI_v0.94_r04_pubrev.pdf) 18along with [TSS 2.0 JSON Data Types and Policy Language Specification](https://trustedcomputinggroup.org/wp-content/uploads/TSS_JSON_Policy_v0.7_r04_pubrev.pdf) 19This API is designed to be very high-level API, intended to make programming with the TPM as simple as possible. 20The API functions are exposed through a single library: libtss2-fapi. 21* Enhanced System API (ESAPI) as described in the [TSS 2.0 Enhanced System API (ESAPI) Specification](https://trustedcomputinggroup.org/wp-content/uploads/TSS_ESAPI_Version-0.9_Revision-04_reviewEND030918.pdf). 22This API is a 1-to-1 mapping of the TPM2 commands documented in Part 3 of the TPM2 specification. 23Additionally there are asynchronous versions of each command. 24In addition to SAPI, the ESAPI performs tracking of meta data for TPM object and automatic calculation of session based authorization and encryption values. 25Both the synchronous and asynchronous API are exposed through a single library: libtss2-esys. 26* System API (SAPI) as described in the [system level API and TPM command transmission interface specification](http://www.trustedcomputinggroup.org/resources/tss_system_level_api_and_tpm_command_transmission_interface_specification). 27This API is a 1-to-1 mapping of the TPM2 commands documented in Part 3 of the TPM2 specification. 28Additionally there are asynchronous versions of each command. 29These asynchronous variants may be useful for integration into event-driven programming environments. 30Both the synchronous and asynchronous API are exposed through a single library: libtss2-sys. 31* Marshaling/Unmarshaling (MU) as described in the [TCG TSS 2.0 Marshaling/Unmarshaling API Specification](https://trustedcomputinggroup.org/wp-content/uploads/TSS_Marshaling_Unmarshaling_API_Version-1.0_Revision-04_review_ENDS030918.pdf). 32This API provides a set of marshaling and unmarshaling functions for all data types define by the TPM library specification. 33The Marshaling/Unmarshaling API is exposed through a library called libtss2-mu. 34* TPM Command Transmission Interface (TCTI) that is described in the same specification. 35This API provides a standard interface to transmit / receive TPM command / response buffers. 36It is expected that any number of libraries implementing the TCTI API will be implemented as a way to abstract various platform specific IPC mechanisms. 37Currently this repository provides two TCTI implementations: libtss2-tcti-device and libtss2-tcti-mssim. 38The former should be used for direct access to the TPM through the Linux kernel driver. 39The latter implements the protocol exposed by the Microsoft software TPM2 simulator. 40* The [TCG TSS 2.0 Overview and Common Structures Specification](https://trustedcomputinggroup.org/wp-content/uploads/TSS_Overview_Common_Structures_Version-0.9_Revision-03_Review_030918.pdf) forms the basis for all implementations in this project. NOTE: We deviate from this draft of the specification by increasing the value of TPM2_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 larger value for TPM2_NUM_PCR_BANKS is expected to be included in a future revision of the specification. 41 42# Build and Installation Instructions: 43Instructions to build and install tpm2-tss are available in the [INSTALL](INSTALL.md) file. 44 45# Getting in Touch: 46If you're looking to discuss the source code in this project or get some questions answered you should join the 01.org TPM2 mailing list: https://lists.01.org/postorius/lists/tpm2.lists.01.org/. 47We also have an IRC channel set up on [FreeNode](https://freenode.net/) called \#tpm2.0-tss. 48You can also try Gitter [](https://gitter.im/tpm2-software/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) 49 50In case you want to contribute to the project, please also have a look at the [Contribution Guidelines](CONTRIBUTING.md). 51 52# Documentation 53 54The doxygen documentation can either be built by oneself (see the [INSTALL](INSTALL.md) file) or browsed directly on [tpm2-tss.readthedocs.io](https://tpm2-tss.readthedocs.io/). 55 56# Test Suite 57This repository contains a test suite intended to exercise the TCTI, SAPI and ESAPI code. 58This test suite is *not* intended to test a TPM implementation, so this test suite should only be run against a TPM simulator. 59If 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.). 60You have been warned. 61 62## Simulator 63The TPM library specification contains reference code sufficient to construct a software TPM 2.0 simulator. 64This code was provided by Microsoft and they provide a binary download for Windows [here](https://www.microsoft.com/en-us/download/details.aspx?id=52507). 65IBM has repackaged this code with a few Makefiles so that the Microsoft code can be built and run on Linux systems. 66The Linux version of the Microsoft TPM 2.0 simulator can be obtained [here](https://downloads.sourceforge.net/project/ibmswtpm2/ibmtpm974.tar.gz). 67Once 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. 68 69Issues building or running the simulator should be reported to the IBM software TPM2 project. 70 71NOTE: The Intel TCG TSS is currently tested against version 974 of the simulator. 72Compatibility with later versions has not yet been tested. 73 74## Testing 75To test the various TCTI, SAPI and ESAPI api calls, unit and integration tests can 76be run by configuring the build to enable unit testing and running the "check" 77build target. It is recommended to use a simulator for testing, and the 78simulator will be automatically launched by the tests. Please review the 79dependency list in [INSTALL](INSTALL.md) for dependencies when building 80the test suite. 81``` 82$ ./configure --enable-unit --enable-integration 83$ make -j$(nproc) check 84``` 85This will generate a file called "test-suite.log" in the root of the build 86directory. 87 88Please report failures in a Github 'issue' with a full log of the test run. 89 90NOTE: The unit and integration tests can be enabled independently. 91The --enable-unit option controls unit tests, and --enable-integration 92controls the integration tests. 93 94### Running tests on physical TPM device 95To run integration tests on a physical TPM device, including a TPM hardware 96or a software TPM implemented in platform firmware the configure script 97provides two options. 98The first option is called --with-ptpm and it is used to point to the TPM 99device interface exposed by the OS, for example: 100 101``` 102 $ ./configure --with-ptpm=/dev/tpm0 103``` 104The second option, --with-ptpmtests, enables a "class" of test. 105There are three classes: 1061. destructive - these tests can affect TPM capability or lifespan 1072. mandatory - these tests check all the functionality that is mandatory 108 per the TCG specification (default). 1093. optional - these tests are for functionality that is optional per the 110 TCG specification. 111 112For example to enable both mandatory and optional test cases during configure 113one needs to set this flag as follows: 114 115``` 116 $ ./configure --with-ptpmtests="mandatory,optional" 117``` 118Tht default value for the flag is "mandatory" 119Any combination of the three is valid. 120The two flags are only valid when the integration tests are enabled with 121--enable-integration flag. 122 123After that the following command is used to run the test on the configured 124TPM device: 125 126``` 127 $ sudo make check-ptpm 128``` 129 or 130``` 131 $ sudo make check -j 1 132``` 133 134Note: The tests can not be run in paralel. 135 136### Running valgrind check 137The unit and integration tests can be run under the valgrind tool, which 138performs additional checks on the library and test code, such as memory 139leak checks etc. The following command is used to run the tests under 140valgrind: 141 142 $ make check-valgrind 143 144This command will enable all valgrind "tools" and kick off as many test 145as many tools it supports. It is possible to enable different valgrind 146tools (checks) in more granularity. This can be controlled by invoking 147different tools separately using check-valgrind-<tool>, for instance: 148 149``` 150 $ make check-valgrind-memcheck 151``` 152 or 153``` 154 $ make check-valgrind-drd 155``` 156 157Currently the the following tools are supported: 158 159memcheck - Performs memory related checks. This is the default tool. 160helgrind - Performs synchronization errors checks. 161drd - Performs thread related checks. 162sgcheck - Performs stack overrun related checks. 163 164Note that the valgring tool can also be invoked manually using the standard 165libtool: 166 167``` 168 $ libtool exec valgrind --tool=memcheck --leak-check=full \ 169 test/integration/esys-auto-session-flags.int 170``` 171 172This allows for more control on what checks are performed. 173 174### Logging 175While investigating issues it might be helpful to enable extra debug/trace 176output. It can be enabled separately for different components. 177The description how to do this can be found in the [logging](doc/logging.md) file. 178 179### Fuzzing 180All system API function calls can be tested using a fuzzing library. 181The description how to do this can be found in the [fuzzing](doc/fuzzing.md) file. 182 183# Architecture/Block Diagram 184SAPI library, TAB/RM, and Test Code Block Diagram: 185 186 187# Project Layout 188``` 189├── doc : various bits of documentation\ 190├── include : header files installed in $(includedir)\ 191│ └── tss2 : all public headers for this project\ 192├── lib : data files used by the build or installed into $(libdir)\ 193├── m4 : autoconf support macros\ 194├── man : man pages\ 195├── script : scripts used by the build or CI\ 196├── src : all source files\ 197│ ├── tss2-esys : enhanced system API (ESAPI) implementation\ 198│ │ └── api : ESAPI TPM API implementation\ 199│ ├── tss2-mu : TPM2 type marshaling/unmarshaling (MU) API implementation\ 200│ ├── tss2-sys : system API (SAPI) implementation\ 201│ │ └── api : SAPI public API implementation\ 202│ ├── tss2-tcti : TCTI implementations for device and mssim\ 203│ └── util : Internal utility library (e.g. logging framework)\ 204└── test : test code\ 205 ├── integration : integration test harness and test cases\ 206 ├── tpmclient : monolithic, legacy test application\ 207 └── unit : unit tests 208``` 209
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
