Bug: 150635486

Clone this repo:
  1. 1267e07 Merge sc-mainline-prod by Xin Li · 1 year, 8 months ago android13-dev android13-frc-adbd-release android13-frc-art-release android13-frc-cellbroadcast-release android13-frc-conscrypt-release android13-frc-documentsui-release android13-frc-extservices-release android13-frc-ipsec-release android13-frc-media-release android13-frc-media-swcodec-release android13-frc-networking-release android13-frc-neuralnetworks-release android13-frc-os-statsd-release android13-frc-permission-release android13-frc-resolv-release android13-frc-scheduling-release android13-mainline-adservices-release android13-mainline-appsearch-release android13-mainline-go-adbd-release android13-mainline-go-adservices-release android13-mainline-go-appsearch-release android13-mainline-go-art-release android13-mainline-go-cellbroadcast-release android13-mainline-go-conscrypt-release android13-mainline-go-documentsui-release android13-mainline-go-extservices-release android13-mainline-go-ipsec-release android13-mainline-go-media-release android13-mainline-go-media-swcodec-release android13-mainline-go-mediaprovider-release android13-mainline-go-networking-release android13-mainline-go-neuralnetworks-release android13-mainline-go-odp-release android13-mainline-go-os-statsd-release android13-mainline-go-permission-release android13-mainline-go-resolv-release android13-mainline-go-scheduling-release android13-mainline-go-sdkext-release android13-mainline-go-tethering-release android13-mainline-go-tzdata4-release android13-mainline-go-uwb-release android13-mainline-go-wifi-release android13-mainline-tzdata4-release android13-mainline-uwb-release android13-qpr1-release android13-qpr1-s1-release android13-qpr1-s2-release android13-qpr1-s3-release android13-qpr1-s4-release android13-qpr1-s5-release main-16k main-16k-with-phones master aml_ads_331131000 aml_ase_331011020 aml_ase_331112000 aml_go_adb_330913000 aml_go_ads_330913000 aml_go_art_330913000 aml_go_ase_330913000 aml_go_cbr_330912000 aml_go_con_330913000 aml_go_doc_330912000 aml_go_ext_330912000 aml_go_ips_330911000 aml_go_med_330913000 aml_go_mpr_330912000 aml_go_net_330913000 aml_go_neu_330912000 aml_go_odp_330912000 aml_go_per_330912000 aml_go_res_330912000 aml_go_sch_330911000 aml_go_sdk_330810000 aml_go_sta_330911000 aml_go_swc_330913000 aml_go_tet_330914010 aml_go_tz4_330912000 aml_go_uwb_330912000 aml_go_wif_330911000 aml_tz4_331012000 aml_tz4_331012040 aml_tz4_331012050 aml_tz4_331314010 aml_uwb_330810010 aml_uwb_331015040 aml_uwb_331115000 aml_uwb_331310030 android-13.0.0_r16 android-13.0.0_r17 android-13.0.0_r18 android-13.0.0_r19 android-13.0.0_r20 android-13.0.0_r21 android-13.0.0_r22 android-13.0.0_r23 android-13.0.0_r24 t_frc_adb_330444000 t_frc_art_330443060 t_frc_ase_330444010 t_frc_cbr_330443000 t_frc_con_330443020 t_frc_doc_330443000 t_frc_doc_330443060 t_frc_doc_330543000 t_frc_ext_330443000 t_frc_ips_330443010 t_frc_med_330443030 t_frc_net_330443000 t_frc_neu_330443000 t_frc_neu_330443030 t_frc_odp_330442000 t_frc_per_330444010 t_frc_res_330443000 t_frc_sch_330443010 t_frc_sch_330443040 t_frc_sta_330443010 t_frc_swc_330443010 t_frc_swc_330443040 t_frc_tz4_330443010
  2. 51ef71c [LSC] Add LOCAL_LICENSE_KINDS to external/tpm2-tss am: d76eac9f45 am: 9121942948 am: cdc8abb1a6 am: 4eb21869e7 by Bob Badour · 2 years ago android12-mainline-adbd-release android12-mainline-art-release android12-mainline-captiveportallogin-release android12-mainline-cellbroadcast-release android12-mainline-conscrypt-release android12-mainline-documentsui-release android12-mainline-extservices-release android12-mainline-ipsec-release android12-mainline-media-release android12-mainline-media-swcodec-release android12-mainline-mediaprovider-release android12-mainline-networkstack-release android12-mainline-neuralnetworks-release android12-mainline-permission-release android12-mainline-resolv-release android12-mainline-sdkext-release android12-mainline-statsd-release android12-mainline-tethering-release android12-mainline-wifi-release aml_doc_310851020 aml_mpr_311911090 aml_sdk_311710000 aml_tet_311811050 aml_tz3_311312010 aml_wif_311811030 android-mainline-12.0.0_r1 android-mainline-12.0.0_r10 android-mainline-12.0.0_r100 android-mainline-12.0.0_r101 android-mainline-12.0.0_r102 android-mainline-12.0.0_r103 android-mainline-12.0.0_r104 android-mainline-12.0.0_r105 android-mainline-12.0.0_r106 android-mainline-12.0.0_r107 android-mainline-12.0.0_r108 android-mainline-12.0.0_r109 android-mainline-12.0.0_r11 android-mainline-12.0.0_r110 android-mainline-12.0.0_r113 android-mainline-12.0.0_r114 android-mainline-12.0.0_r115 android-mainline-12.0.0_r116 android-mainline-12.0.0_r117 android-mainline-12.0.0_r118 android-mainline-12.0.0_r119 android-mainline-12.0.0_r12 android-mainline-12.0.0_r120 android-mainline-12.0.0_r121 android-mainline-12.0.0_r122 android-mainline-12.0.0_r123 android-mainline-12.0.0_r124 android-mainline-12.0.0_r125 android-mainline-12.0.0_r126 android-mainline-12.0.0_r13 android-mainline-12.0.0_r14 android-mainline-12.0.0_r15 android-mainline-12.0.0_r16 android-mainline-12.0.0_r17 android-mainline-12.0.0_r18 android-mainline-12.0.0_r19 android-mainline-12.0.0_r2 android-mainline-12.0.0_r20 android-mainline-12.0.0_r21 android-mainline-12.0.0_r22 android-mainline-12.0.0_r23 android-mainline-12.0.0_r24 android-mainline-12.0.0_r25 android-mainline-12.0.0_r26 android-mainline-12.0.0_r27 android-mainline-12.0.0_r28 android-mainline-12.0.0_r29 android-mainline-12.0.0_r3 android-mainline-12.0.0_r30 android-mainline-12.0.0_r31 android-mainline-12.0.0_r32 android-mainline-12.0.0_r33 android-mainline-12.0.0_r34 android-mainline-12.0.0_r35 android-mainline-12.0.0_r37 android-mainline-12.0.0_r38 android-mainline-12.0.0_r39 android-mainline-12.0.0_r40 android-mainline-12.0.0_r41 android-mainline-12.0.0_r42 android-mainline-12.0.0_r43 android-mainline-12.0.0_r44 android-mainline-12.0.0_r45 android-mainline-12.0.0_r46 android-mainline-12.0.0_r47 android-mainline-12.0.0_r48 android-mainline-12.0.0_r49 android-mainline-12.0.0_r5 android-mainline-12.0.0_r50 android-mainline-12.0.0_r51 android-mainline-12.0.0_r52 android-mainline-12.0.0_r53 android-mainline-12.0.0_r56 android-mainline-12.0.0_r57 android-mainline-12.0.0_r58 android-mainline-12.0.0_r59 android-mainline-12.0.0_r6 android-mainline-12.0.0_r60 android-mainline-12.0.0_r61 android-mainline-12.0.0_r62 android-mainline-12.0.0_r63 android-mainline-12.0.0_r64 android-mainline-12.0.0_r65 android-mainline-12.0.0_r66 android-mainline-12.0.0_r67 android-mainline-12.0.0_r68 android-mainline-12.0.0_r69 android-mainline-12.0.0_r7 android-mainline-12.0.0_r70 android-mainline-12.0.0_r71 android-mainline-12.0.0_r72 android-mainline-12.0.0_r73 android-mainline-12.0.0_r74 android-mainline-12.0.0_r75 android-mainline-12.0.0_r76 android-mainline-12.0.0_r77 android-mainline-12.0.0_r78 android-mainline-12.0.0_r79 android-mainline-12.0.0_r8 android-mainline-12.0.0_r80 android-mainline-12.0.0_r81 android-mainline-12.0.0_r82 android-mainline-12.0.0_r83 android-mainline-12.0.0_r84 android-mainline-12.0.0_r85 android-mainline-12.0.0_r86 android-mainline-12.0.0_r87 android-mainline-12.0.0_r88 android-mainline-12.0.0_r89 android-mainline-12.0.0_r9 android-mainline-12.0.0_r90 android-mainline-12.0.0_r91 android-mainline-12.0.0_r92 android-mainline-12.0.0_r93 android-mainline-12.0.0_r94 android-mainline-12.0.0_r95 android-mainline-12.0.0_r96 android-mainline-12.0.0_r97 android-mainline-12.0.0_r98 android-mainline-12.0.0_r99
  3. 1c5d1c8 [LSC] Add LOCAL_LICENSE_KINDS to external/tpm2-tss am: d76eac9f45 am: 9121942948 am: cdc8abb1a6 am: 4eb21869e7 by Bob Badour · 2 years ago
  4. 4eb2186 [LSC] Add LOCAL_LICENSE_KINDS to external/tpm2-tss am: d76eac9f45 am: 9121942948 am: cdc8abb1a6 by Bob Badour · 2 years ago android-s-qpr3-beta-1 android-s-v2-beta-3 android-s-v2-preview-1 android-t-preview-1 android12--mainline-release android12-dev android12-qpr1-d-release android12-qpr1-d-s1-release android12-qpr1-d-s2-release android12-qpr1-d-s3-release android12-qpr1-release android12-qpr3-release android12-qpr3-s1-release android12-qpr3-s2-release android12-qpr3-s3-release android12-qpr3-s4-release android12-qpr3-s5-release android12-qpr3-s6-release android12-qpr3-s7-release android12L-d2-release android12L-d2-s1-release android12L-d2-s2-release android12L-d2-s3-release android12L-d2-s4-release android12L-d2-s5-release android12L-d2-s6-release android12L-d2-s7-release android12L-d2-s8-release android12L-dev android-12.0.0_r16 android-12.0.0_r18 android-12.0.0_r19 android-12.0.0_r20 android-12.0.0_r21 android-12.0.0_r26 android-12.0.0_r27 android-12.0.0_r28 android-12.0.0_r29 android-12.0.0_r32 android-12.1.0_r10 android-12.1.0_r11 android-12.1.0_r12 android-12.1.0_r13 android-12.1.0_r14 android-12.1.0_r15 android-12.1.0_r16 android-12.1.0_r17 android-12.1.0_r18 android-12.1.0_r19 android-12.1.0_r20 android-12.1.0_r21 android-12.1.0_r22 android-12.1.0_r23 android-12.1.0_r24 android-12.1.0_r25 android-12.1.0_r26 android-12.1.0_r7 android-12.1.0_r8 android-12.1.0_r9 android-mainline-12.0.0_r36 android-mainline-12.0.0_r4 android-s-qpr3-beta-1 android-s-v2-beta-2 android-s-v2-beta-3 android-s-v2-preview-1 android-s-v2-preview-2 android-t-beta-3 android-t-preview-1 android-t-preview-2
  5. cdc8abb [LSC] Add LOCAL_LICENSE_KINDS to external/tpm2-tss am: d76eac9f45 am: 9121942948 by Bob Badour · 2 years ago

Linux Build Status Windows Build status FreeBSD Build status Coverity Scan Coverage Status CII Best Practices Total alerts Language grade: C/C++ Documentation Status Fuzzing Status Gitter

Overview

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:

  • Feature API (FAPI) as described in the TSS 2.0 Feature API Specification along with TSS 2.0 JSON Data Types and Policy Language Specification This API is designed to be very high-level API, intended to make programming with the TPM as simple as possible. The API functions are exposed through a single library: libtss2-fapi.
  • Enhanced System API (ESAPI) as described in the TSS 2.0 Enhanced System API (ESAPI) Specification. This API is a 1-to-1 mapping of the TPM2 commands documented in Part 3 of the TPM2 specification. Additionally there are asynchronous versions of each command. In addition to SAPI, the ESAPI performs tracking of meta data for TPM object and automatic calculation of session based authorization and encryption values. Both the synchronous and asynchronous API are exposed through a single library: libtss2-esys.
  • System API (SAPI) as described in the system level API and TPM command transmission interface specification. This API is a 1-to-1 mapping of the TPM2 commands documented in Part 3 of the TPM2 specification. Additionally there are asynchronous versions of each command. These asynchronous variants may be useful for integration into event-driven programming environments. Both the synchronous and asynchronous API are exposed through a single library: libtss2-sys.
  • Marshaling/Unmarshaling (MU) as described in the TCG TSS 2.0 Marshaling/Unmarshaling API Specification. This API provides a set of marshaling and unmarshaling functions for all data types define by the TPM library specification. The Marshaling/Unmarshaling API is exposed through a library called libtss2-mu.
  • TPM Command Transmission Interface (TCTI) that is described in the same specification. This API provides a standard interface to transmit / receive TPM command / response buffers. It is expected that any number of libraries implementing the TCTI API will be implemented as a way to abstract various platform specific IPC mechanisms. Currently this repository provides two TCTI implementations: libtss2-tcti-device and libtss2-tcti-mssim. The former should be used for direct access to the TPM through the Linux kernel driver. The latter implements the protocol exposed by the Microsoft software TPM2 simulator.
  • The TCG TSS 2.0 Overview and Common Structures Specification 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.

Build and Installation Instructions:

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

Getting in Touch:

If 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/. We also have an IRC channel set up on FreeNode called #tpm2.0-tss. You can also try Gitter Gitter

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

Documentation

The doxygen documentation can either be built by oneself (see the INSTALL file) or browsed directly on tpm2-tss.readthedocs.io.

Test Suite

This repository contains a test suite intended to exercise the TCTI, SAPI and ESAPI code. This test suite is not 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.

Simulator

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 Windows here. IBM has 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 obtained here. 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.

Issues building or running the simulator should be reported to the IBM software TPM2 project.

NOTE: The Intel TCG TSS is currently tested against version 974 of the simulator. Compatibility with later versions has not yet been tested.

Testing

To test the various TCTI, SAPI and ESAPI api calls, unit and integration tests can be 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 the simulator will be automatically launched by the tests. Please review the dependency list in INSTALL for dependencies when building the 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 build directory.

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-integration controls the integration tests.

Running tests on physical TPM device

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

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

The second option, --with-ptpmtests, 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 mandatory per the TCG specification (default).
  3. optional - these tests are for functionality that is optional per the TCG specification.

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

  $ ./configure --with-ptpmtests="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 configured TPM device:

  $ sudo make check-ptpm

or

  $ sudo make check -j 1

Note: The tests can not be run in paralel.

Running valgrind check

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

$ make check-valgrind

This command will enable all valgrind “tools” and kick off as many test as many tools it supports. It is possible to enable different valgrind tools (checks) in more granularity. This can be controlled by invoking different 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 standard libtool:

  $ 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.

Logging

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

Fuzzing

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

Architecture/Block Diagram

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

Project Layout

├── 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