|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | - | - |
| .ci/ | | 23-Nov-2023 | - | 253 | 152 |
| dist/ | | 23-Nov-2023 | - | 114 | 106 |
| doc/ | | 23-Nov-2023 | - | 3,579 | 3,419 |
| include/tss2/ | | 23-Nov-2023 | - | 10,683 | 8,617 |
| lib/ | | 23-Nov-2023 | - | 2,428 | 2,396 |
| m4/ | | 23-Nov-2023 | - | 122 | 115 |
| man/ | | 23-Nov-2023 | - | 687 | 627 |
| script/ | | 23-Nov-2023 | - | 1,379 | 1,031 |
| sphinx/ | | 23-Nov-2023 | - | 302 | 47 |
| src/ | | 23-Nov-2023 | - | 118,799 | 72,051 |
| test/ | | 23-Nov-2023 | - | 53,673 | 41,699 |
| .appveyor.yml | D | 23-Nov-2023 | 246 | 16 | 15 |
| .cirrus.yml | D | 23-Nov-2023 | 1.1 KiB | 27 | 26 |
| .codecov.yml | D | 23-Nov-2023 | 116 | 12 | 9 |
| .dockerignore | D | 23-Nov-2023 | 18 | 2 | 1 |
| .gitattributes | D | 23-Nov-2023 | 529 | 20 | 16 |
| .lgtm.yml | D | 23-Nov-2023 | 67 | 5 | 4 |
| .readthedocs.yml | D | 23-Nov-2023 | 178 | 7 | 4 |
| .travis.yml | D | 23-Nov-2023 | 2.1 KiB | 58 | 42 |
| Android.bp | D | 23-Nov-2023 | 3.5 KiB | 160 | 150 |
| CHANGELOG.md | D | 23-Nov-2023 | 38.7 KiB | 857 | 814 |
| CONTRIBUTING.md | D | 23-Nov-2023 | 2 KiB | 39 | 33 |
| Dockerfile | D | 23-Nov-2023 | 788 | 37 | 32 |
| Doxyfile.in | D | 23-Nov-2023 | 112.5 KiB | 2,538 | 1,986 |
| INSTALL.md | D | 23-Nov-2023 | 7.1 KiB | 214 | 174 |
| LICENSE | D | 23-Nov-2023 | 1.2 KiB | 22 | 18 |
| MAINTAINERS | D | 23-Nov-2023 | 131 | 4 | 3 |
| METADATA | D | 23-Nov-2023 | 425 | 20 | 19 |
| MODULE_LICENSE_BSD | D | 23-Nov-2023 | 0 | | |
| Makefile-fuzz.am | D | 23-Nov-2023 | 1.7 KiB | 51 | 40 |
| Makefile-test.am | D | 23-Nov-2023 | 86 KiB | 1,701 | 1,465 |
| Makefile.am | D | 23-Nov-2023 | 20.9 KiB | 605 | 500 |
| OWNERS | D | 23-Nov-2023 | 22 | 2 | 1 |
| README.md | D | 23-Nov-2023 | 12.3 KiB | 209 | 174 |
| RELEASE.md | D | 23-Nov-2023 | 5.4 KiB | 89 | 72 |
| bootstrap | D | 23-Nov-2023 | 2.7 KiB | 90 | 66 |
| configure.ac | D | 23-Nov-2023 | 18.3 KiB | 471 | 415 |
| git.mk | D | 23-Nov-2023 | 12.4 KiB | 402 | 294 |
| tpm2-tss.sln | D | 23-Nov-2023 | 6.9 KiB | 109 | 107 |
README.md
1[![Linux Build Status](https://travis-ci.org/tpm2-software/tpm2-tss.svg?branch=master)](https://travis-ci.org/tpm2-software/tpm2-tss)
2[![Windows Build status](https://ci.appveyor.com/api/projects/status/2rdmyn1ndkiavngn?svg=true)](https://ci.appveyor.com/project/tpm2-software/tpm2-tss)
3[![FreeBSD Build status](https://api.cirrus-ci.com/github/tpm2-software/tpm2-tss.svg?branch=master)](https://cirrus-ci.com/github/tpm2-software/tpm2-tss)
4[![Coverity Scan](https://img.shields.io/coverity/scan/3997.svg)](https://scan.coverity.com/projects/tpm2-tss)
5[![Coverage Status](https://codecov.io/gh/tpm2-software/tpm2-tss/branch/master/graph/badge.svg)](https://codecov.io/gh/tpm2-software/tpm2-tss)
6[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2332/badge)](https://bestpractices.coreinfrastructure.org/projects/2332)
7[![Total alerts](https://img.shields.io/lgtm/alerts/g/tpm2-software/tpm2-tss.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/tpm2-software/tpm2-tss/alerts/)
8[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/tpm2-software/tpm2-tss.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/tpm2-software/tpm2-tss/context:cpp)
9[![Documentation Status](https://readthedocs.org/projects/tpm2-tss/badge/?version=latest)](https://tpm2-tss.readthedocs.io/en/latest/?badge=latest)
10[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/tpm2-tss.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:tpm2-tss)
11[![Gitter](https://badges.gitter.im/tpm2-software/community.svg)](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 [![Gitter](https://badges.gitter.im/tpm2-software/community.svg)](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![Architecture Block Diagram](doc/TSS_block_diagram.png)
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