SoftwareDesign
/
csu3_am335x


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>tpm2-tss: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">tpm2-tss
   &#160;<span id="projectnumber">3.2.0</span>
   </div>
   <div id="projectbrief">TPM Software stack 2.0 TCG spec compliant implementation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">tpm2-tss Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a href="https://github.com/tpm2-software/tpm2-tss/actions"></a> <a href="https://ci.appveyor.com/project/williamcroberts/tpm2-tss"></a> <a href="https://cirrus-ci.com/github/tpm2-software/tpm2-tss"></a> <a href="https://scan.coverity.com/projects/tpm2-tss"></a> <a href="https://codecov.io/gh/tpm2-software/tpm2-tss"></a> <a href="https://bestpractices.coreinfrastructure.org/projects/2332"></a> <a href="https://lgtm.com/projects/g/tpm2-software/tpm2-tss/alerts/"></a> <a href="https://lgtm.com/projects/g/tpm2-software/tpm2-tss/context:cpp"></a> <a href="https://tpm2-tss.readthedocs.io/en/latest/?badge=latest"></a> <a href="https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&amp;can=1&amp;q=proj:tpm2-tss"></a> <a href="https://gitter.im/tpm2-software/community?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge"></a></p>
<h1>Overview</h1>
<p>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:</p>
<ul>
<li>Feature API (FAPI) as described in the <a href="https://trustedcomputinggroup.org/wp-content/uploads/TSS_FAPI_v0p94_r09_pub.pdf">TCG Feature API (FAPI) Specification</a> along with <a href="https://trustedcomputinggroup.org/wp-content/uploads/TSS_JSON_Policy_v0p7_r08_pub.pdf">TCG TSS 2.0 JSON Data Types and Policy Language Specification</a> 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.</li>
<li>Enhanced System API (ESAPI) as described in the <a href="https://trustedcomputinggroup.org/wp-content/uploads/TSS_ESAPI_v1p0_r08_pub.pdf">TCG TSS 2.0 Enhanced System API (ESAPI) Specification</a> 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.</li>
<li>System API (SAPI) as described in the <a href="https://trustedcomputinggroup.org/wp-content/uploads/TSS_SAPI_v1p1_r29_pub_20190806.pdf">TCG TSS 2.0 System Level API (SAPI) Specification</a> 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.</li>
<li>Marshaling/Unmarshaling (MU) as described in the <a href="https://trustedcomputinggroup.org/wp-content/uploads/TCG_TSS_Marshaling_Unmarshaling_API_v1p0_r07_pub.pdf">TCG TSS 2.0 Marshaling/Unmarshaling API Specification</a> 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.</li>
<li>TPM Command Transmission Interface (TCTI) as described in the <a href="https://trustedcomputinggroup.org/wp-content/uploads/TCG_TSS_TCTI_v1p0_r18_pub.pdf">TCG TSS 2.0 TPM Command Transmission Interface (TCTI) API Specification</a>. 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 several TCTI implementations: libtss2-tcti-device, libtss2-tcti-tbs (for Windows), libtss2-tcti-swtpm 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.</li>
<li>The <a href="https://trustedcomputinggroup.org/wp-content/uploads/TCG_TSS_Overview_Common_Structures_v0.9_r03_published.pdf">TCG TSS 2.0 Overview and Common Structures Specification</a> forms the basis for all implementations in this project. NOTE: We deviate from this 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.</li>
</ul>
<h1>Build and Installation Instructions:</h1>
<p>Instructions to build and install tpm2-tss are available in the INSTALL file.</p>
<h1>Getting in Touch:</h1>
<p>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: <a href="https://lists.01.org/postorius/lists/tpm2.lists.01.org/">https://lists.01.org/postorius/lists/tpm2.lists.01.org/</a>. We also have an IRC channel set up on <a href="https://freenode.net/">FreeNode</a> called #tpm2.0-tss. You can also try Gitter <a href="https://gitter.im/tpm2-software/community?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge"></a></p>
<p>You can join a weekly online call at <a href="https://developers.tpm.dev/events/tpmdev-online-call">TPM.dev</a>, where we are discussing the tpm2-tss stack, the tpm2-pkcs11 project and other Linux TPM2 &amp; TSS2-Software.</p>
<p>In case you want to contribute to the project, please also have a look at the Contribution Guidelines.</p>
<h1>Documentation</h1>
<p>The doxygen documentation can either be built by oneself (see the INSTALL file) or browsed directly on <a href="https://tpm2-tss.readthedocs.io/">tpm2-tss.readthedocs.io</a>.</p>
<h1>Test Suite</h1>
<p>This repository contains a test suite intended to exercise the TCTI, SAPI and ESAPI code. This test suite is <em>not</em> 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.</p>
<h2>Simulator</h2>
<p>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 <a href="https://www.microsoft.com/en-us/download/details.aspx?id=52507">here</a>.</p>
<p>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.</p>
<h3>Software TPM</h3>
<p>The Software TPM is an open-source TPM emulator with different front-end interfaces such as socket and character device. Its code is hosted <a href="https://github.com/stefanberger/swtpm">on GitHub</a> and building is faciliated by the GNU Autotools. The TCTI module for using this simulator is called <em>swtpm</em>.</p>
<p>Since tpm2-tss v3.0 swtpm is the default simulator used by this project.</p>
<h3>IBM's Software Simulator</h3>
<p>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 obtained <a href="https://downloads.sourceforge.net/project/ibmswtpm2/ibmtpm974.tar.gz">on SourceForge</a>. 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 called <em>mssim</em>.</p>
<h2>Testing</h2>
<p>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. </p><div class="fragment"><div class="line">$ ./configure --enable-unit --enable-integration</div><div class="line">$ make -j$(nproc) check</div></div><!-- fragment --><p> This will generate a file called "test-suite.log" in the root of the build directory.</p>
<p>Please report failures in a Github 'issue' with a full log of the test run.</p>
<p>NOTE: The unit and integration tests can be enabled independently. The &ndash;enable-unit option controls unit tests, and &ndash;enable-integration controls the integration tests.</p>
<h3>Running tests on physical TPM device</h3>
<p>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 &ndash;with-device and it is used to point to the TPM device interface exposed by the OS, for example:</p>
<div class="fragment"><div class="line">$ ./configure  --with-device=/dev/tpm0</div></div><!-- fragment --><p> The second option, &ndash;with-devicetests, enables a "class" of test. There are three classes:</p><ol type="1">
<li>destructive - these tests can affect TPM capability or lifespan</li>
<li>mandatory - these tests check all the functionality that is mandatory per the TCG specification (default).</li>
<li>optional - these tests are for functionality that is optional per the TCG specification.</li>
</ol>
<p>For example to enable both mandatory and optional test cases during configure one needs to set this flag as follows:</p>
<div class="fragment"><div class="line">$ ./configure --with-devicetests=&quot;mandatory,optional&quot;</div></div><!-- fragment --><p> 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 &ndash;enable-integration flag.</p>
<p>After that the following command is used to run the test on the configured TPM device:</p>
<div class="fragment"><div class="line">$ sudo make check-device</div></div><!-- fragment --><p> or </p><div class="fragment"><div class="line">$ sudo make check -j 1</div></div><!-- fragment --><p>Note: The tests can not be run in paralel.</p>
<h3>Running valgrind check</h3>
<p>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:</p>
<p>$ make check-valgrind</p>
<p>This command will enable all valgrind "tools" and kick off as many test as they support. It is possible to enable different valgrind tools (checks) in more granularity. This can be controlled by invoking different tools separately using check-valgrind-&lt;tool&gt;, for instance:</p>
<div class="fragment"><div class="line">$ make check-valgrind-memcheck</div></div><!-- fragment --><p> or </p><div class="fragment"><div class="line">$ make check-valgrind-drd</div></div><!-- fragment --><p>Currently the the following tools are supported:</p>
<p>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.</p>
<p>Note that the valgring tool can also be invoked manually using the standard libtool:</p>
<div class="fragment"><div class="line">$ libtool exec valgrind --tool=memcheck --leak-check=full \</div><div class="line">  test/integration/esys-auto-session-flags.int</div></div><!-- fragment --><p>This allows for more control on what checks are performed.</p>
<h3>Logging</h3>
<p>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 <a class="el" href="md_doc_logging.html">logging</a> file.</p>
<h3>Fuzzing</h3>
<p>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.</p>
<h1>Architecture/Block Diagram</h1>
<p>SAPI library, TAB/RM, and Test Code Block Diagram: </p><div class="image">
<img src="TSS_block_diagram.png" alt="TSS_block_diagram.png"/>
<div class="caption">
Architecture Block Diagram</div></div>
 <h1>Project Layout</h1>
<div class="fragment"><div class="line">|-- doc     : various bits of documentation\</div><div class="line">|-- include : header files installed in $(includedir)\</div><div class="line">|   +-- tss2      : all public headers for this project\</div><div class="line">|-- lib     : data files used by the build or installed into $(libdir)\</div><div class="line">|-- m4      : autoconf support macros\</div><div class="line">|-- man     : man pages\</div><div class="line">|-- script  : scripts used by the build or CI\</div><div class="line">|-- src     : all source files\</div><div class="line">|   |-- tss2-esys : enhanced system API (ESAPI) implementation\</div><div class="line">|   |   +-- api   : ESAPI TPM API implementation\</div><div class="line">|   |-- tss2-mu   : TPM2 type marshaling/unmarshaling (MU) API implementation\</div><div class="line">|   |-- tss2-sys  : system API (SAPI) implementation\</div><div class="line">|   |   +-- api   : SAPI public API implementation\</div><div class="line">|   |-- tss2-tcti : TCTI implementations for device and mssim\</div><div class="line">|   +-- util      : Internal utility library (e.g. logging framework)\</div><div class="line">+-- test    : test code\</div><div class="line">    |-- integration : integration test harness and test cases\</div><div class="line">    |-- tpmclient   : monolithic, legacy test application\</div><div class="line">    +-- unit        : unit tests</div></div><!-- fragment --> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
  </ul>
</div>
</body>
</html>