ibmtss.html

<p>April 2, 2023</p>
<p><a href="#_Toc35934217">1. Introduction 5</a></p>
<p><a href="#features">2. Features 6</a></p>
<p><a href="#api">3. API 7</a></p>
<p><a href="#tss_execute">3.1. TSS_Execute() 7</a></p>
<p><a href="#tss_create">3.2. TSS_Create() 7</a></p>
<p><a href="#tss_delete">3.3. TSS_Delete() 8</a></p>
<p><a href="#optional-customization">3.4. Optional Customization 9</a></p>
<p><a href="#property-example">3.4.1. Property Example 9</a></p>
<p><a href="#properties">3.4.2. Properties 9</a></p>
<p><a href="#tss_setproperty">3.4.3. TSS_SetProperty() 12</a></p>
<p><a href="#extra-parameter">3.5. Extra Parameter 13</a></p>
<p><a href="#other-apis-and-headers">3.6. Other APIs and Headers 13</a></p>
<p><a href="#application-notes">4. Application Notes 15</a></p>
<p><a href="#tpm-simulator">4.1. TPM Simulator 15</a></p>
<p><a href="#parameter-encryption">4.2. Parameter Encryption 15</a></p>
<p><a href="#session-salt">4.3. Session Salt 15</a></p>
<p><a href="#session-bind">4.4. Session Bind 15</a></p>
<p><a href="#nv">4.5. NV 16</a></p>
<p><a href="#rationale">4.5.1. Rationale 16</a></p>
<p><a href="#nv-pre-provisioning">4.5.2. NV Pre-provisioning 17</a></p>
<p><a href="#tpm2_loadexternal">4.6. TPM2_LoadExternal 17</a></p>
<p><a href="#connecting-to-resource-managers">4.7. Connecting to Resource Managers 17</a></p>
<p><a href="#endorsement-key-ek-certificates">4.8. Endorsement Key (EK) Certificates 18</a></p>
<p><a href="#nuvoton">4.8.1. Nuvoton 19</a></p>
<p><a href="#st-micro">4.8.2. St Micro 19</a></p>
<p><a href="#infineon">4.8.3. Infineon 20</a></p>
<p><a href="#nationz">4.8.4. NationZ 20</a></p>
<p><a href="#intel">4.8.5. Intel 20</a></p>
<p><a href="#intel-ek-certificate-download">4.8.5.1. Intel EK Certificate Download 20</a></p>
<p><a href="#command-line-utilities">4.9. Command Line Utilities 21</a></p>
<p><a href="#tss-for-tpm-1.2">4.10. TSS for TPM 1.2 22</a></p>
<p><a href="#examples">5. Examples 23</a></p>
<p><a href="#signapp.c">5.1. signapp.c 23</a></p>
<p><a href="#writeapp.c">5.2. writeapp.c 23</a></p>
<p><a href="#utility-tools">6. Utility tools 25</a></p>
<p><a href="#debugging-aids">6.1. Debugging Aids 25</a></p>
<p><a href="#reponsecode">6.1.1. reponsecode 25</a></p>
<p><a href="#printattr">6.1.2. printattr 25</a></p>
<p><a href="#timepacket">6.1.3. timepacket 25</a></p>
<p><a href="#policy-aids">6.2. Policy Aids 25</a></p>
<p><a href="#policymaker">6.2.1. policymaker 26</a></p>
<p><a href="#policymakerpcr">6.2.2. policymakerpcr 26</a></p>
<p><a href="#publicname">6.2.3. publicname 26</a></p>
<p><a href="#key-manipulation">6.3. Key Manipulation 26</a></p>
<p><a href="#createek">6.3.1. createek 26</a></p>
<p><a href="#createekcert">6.3.2. createekcert 27</a></p>
<p><a href="#tpm2pem">6.3.3. tpm2pem 27</a></p>
<p><a href="#event-logs">6.4. Event Logs 27</a></p>
<p><a href="#eventextend">6.4.1. eventextend 27</a></p>
<p><a href="#imaextend">6.4.2. imaextend 27</a></p>
<p><a href="#build">7. Build 28</a></p>
<p><a href="#build-options">7.1. Build Options 28</a></p>
<p><a href="#tpm_tpm20-and-tpm_tpm12">7.1.1. TPM_TPM20 and TPM_TPM12 28</a></p>
<p><a href="#tpm_posix-or-tpm_windows">7.1.2. TPM_POSIX or TPM_WINDOWS 28</a></p>
<p><a href="#tpm_windows_tbsi">7.1.3. TPM_WINDOWS_TBSI 28</a></p>
<p><a href="#tpm_tss_nofile">7.1.4. TPM_TSS_NOFILE 28</a></p>
<p><a href="#tpm_tss_nocrypto">7.1.5. TPM_TSS_NOCRYPTO 29</a></p>
<p><a href="#tpm_tss_no_print">7.1.6. TPM_TSS_NO_PRINT 29</a></p>
<p><a href="#tpm_tss_noecc">7.1.7. TPM_TSS_NOECC 29</a></p>
<p><a href="#tpm_tss_norsa">7.1.8. TPM_TSS_NORSA 29</a></p>
<p><a href="#tpm_tss_noenv">7.1.9. TPM_TSS_NOENV 29</a></p>
<p><a href="#tpm_nosocket">7.1.10. TPM_NOSOCKET 29</a></p>
<p><a href="#tpm_tss_nocmdcheck">7.1.11. TPM_TSS_NOCMDCHECK 30</a></p>
<p><a href="#tpm_tss_nodeprecated">7.1.12. TPM_TSS_NODEPRECATED 30</a></p>
<p><a href="#tpm_tss_nodeprecatedalgs">7.1.13. TPM_TSS_NUVOTON 30</a></p>
<p><a href="#directories">7.2. Directories 30</a></p>
<p><a href="#linux">7.3. Linux 31</a></p>
<p><a href="#windows">7.4. Windows 31</a></p>
<p><a href="#windows-gcc">7.4.1. Windows gcc 33</a></p>
<p><a href="#windows-visual-studio">7.4.2. Windows Visual Studio 33</a></p>
<p><a href="#section-1">7.4.3. Windows Tbsi 34</a></p>
<p><a href="#mac">7.5. Mac 34</a></p>
<p><a href="#aix">7.6. AIX 35</a></p>
<p><a href="#fedora">8. Fedora 36</a></p>
<p><a href="#local-install">8.1. Local Install 36</a></p>
<p><a href="#alternative-local-install">8.2. Alternative Local Install 36</a></p>
<p><a href="#repository-install">8.3. Repository Install 37</a></p>
<p><a href="#install-test">8.4. Install Test 37</a></p>
<p><a href="#source-rpms">8.5. Source rpms 37</a></p>
<p><a href="#status">9. Status 39</a></p>
<p><a href="#utilities">9.1. Utilities 39</a></p>
<p><a href="#bugs">9.2. Bugs 39</a></p>
<p><a href="#untested">9.3. Untested 39</a></p>
<p><a href="#threading">10. Threading 40</a></p>
<p><a href="#troubleshooting">11. Troubleshooting 41</a></p>
<p><a href="#environment-variables">11.1. Environment Variables 41</a></p>
<p><a href="#command-line-utilities-fail-on-windows-10">11.2. Command line utilities fail on Windows 10 41</a></p>
<p><a href="#openssl-linking-on-windows">11.3. OpenSSL Linking on Windows 41</a></p>
<p><a href="#loaded-objects-keys-disappear">11.4. Loaded objects (keys) disappear 41</a></p>
<h1 id="introduction">Introduction</h1>
<p>The IBM TSS is designed for:</p>
<ul>
<li><p>ease of understanding</p></li>
<li><p>ease of use</p></li>
<li><p>ease of implementation</p></li>
<li><p>maximum code reuse</p></li>
</ul>
<p>The package is upstreamed to</p>
<ul>
<li><p>Fedora</p></li>
<li><p>Debian</p></li>
<li><p>RHEL 7.4 and up</p></li>
<li><p>SLES 12 SP3 and up</p></li>
<li><p>Ubuntu 17.10 and up</p></li>
</ul>
<h1 id="features">Features</h1>
<p>The TSS handles the following, completely hidden from the caller:</p>
<ul>
<li><p>HMAC, password and policy sessions</p></li>
<li><p>Session and HMAC key calculations, including bind and salt sessions</p></li>
<li><p>HMAC generation and verification (including cpHash and rpHash)</p></li>
<li><p>Parameter encryption and decryption, XOR and AES</p></li>
<li><p>Nonces and nonce rolling</p></li>
<li><p>Session continue flag</p></li>
<li><p>TPM 2.0 "Name" and bind session tracking</p></li>
<li><p>Different session hash algorithms</p></li>
<li><p>Marshaling, unmarshaling, and communication with the TPM</p></li>
</ul>
<p>and almost hidden from the caller:</p>
<ul>
<li><p>bind password</p></li>
</ul>
<h1 id="api">API</h1>
<p>The API consists of the following calls:</p>
<h2 id="tss_execute">TSS_Execute()</h2>
<p>#include &lt;ibmtss/tss.h&gt;</p>
<p>TPM_RC TSS_Execute(TSS_CONTEXT *tssContext,</p>
<blockquote>
<p>RESPONSE_PARAMETERS *out,</p>
</blockquote>
<p>COMMAND_PARAMETERS *in,</p>
<p>EXTRA_PARAMETERS *extra,</p>
<p>TPM_CC commandCode,</p>
<p>...);</p>
<p>This is the primary TSS function.</p>
<p>tssContext: Opaque object</p>
<p>out: The standard TPM2 Part 3 response parameter</p>
<p>in: The standard TPM2 Part 3 command parameter</p>
<p>extra: Some commands (only two so far) require extra parameter s.</p>
<p>commandCode: The standard TPM2 Part 2 command code.</p>
<p>. . . : A list of session 3-tuples , of the form</p>
<p>TPMI_SH_AUTH_SESSION sessionHandle,</p>
<p>const char *password,</p>
<p>unsigned int sessionAttributes</p>
<p>The list is terminated with (TPM_RH_NULL, NULL, 0)</p>
<h2 id="tss_create">TSS_Create()</h2>
<p>#include &lt;ibmtss/tss.h&gt;</p>
<p>TPM_RC TSS_Create(TSS_CONTEXT **tssContext);</p>
<p>This creates the TSS_CONTEXT used in the TSS_Execute() function. It is initialized with the default configuration, which can be then changed using 3.4.3 TSS_SetProperty().</p>
<p>Returns an error if the context cannot be allocated, or if the properties cannot be initialized, typically due to an invalid environment variable.</p>
<p>See 3.3 TSS_Delete().</p>
<p>It does not immediately open a connection, so that the connection properties can be changed from the default first.</p>
<h2 id="tss_delete">TSS_Delete()</h2>
<p>#include &lt;ibmtss/tss.h&gt;</p>
<p>TPM_RC TSS_Delete(TSS_CONTEXT *tssContext);</p>
<p>The deletes the opaque context created using 3.2 TSS_Create().</p>
<p>It closes an open connection.</p>
<p>Returns an error if the connection close fails.</p>
<h2 id="optional-customization">Optional Customization</h2>
<p>The TSS is designed to work by default with no configuration.</p>
<blockquote>
<p>The current default connects to the Microsoft format socket simulation. This will eventually change to connect to the resource manager.</p>
</blockquote>
<p>There are three ways to customize the configuration:</p>
<ol type="1">
<li><p>At compile time, with a compiler flag</p></li>
<li><p>At program start, using an environment variable</p></li>
<li><p>During run time, using the 3.4.3 TSS_SetProperty() function.</p></li>
</ol>
<p>The environment variables and TSS_SetProperty property use the same names. The makefile flag uses the name with _DEFAULT appended.</p>
<p>The environment variable overrides the compiler flag, and the TSS_SetProperty() function overrides both the compiler flag and the environment variable.</p>
<h3 id="property-example">Property Example</h3>
<p>To change the default TPM interface to the TPM device driver:</p>
<ul>
<li><p>With a makefile:</p></li>
</ul>
<p>-DTPM_INTERFACE_TYPE_DEFAULT="\"dev\""</p>
<ul>
<li><p>With an environment variable:</p></li>
</ul>
<p>&gt; setenv TPM_INTERFACE_TYPE dev</p>
<ul>
<li><p>With the TSS_SetProperty() function:</p></li>
</ul>
<p>rc = TSS_SetProperty(tssContext, TPM_INTERFACE_TYPE, "dev");</p>
<h3 id="properties">Properties</h3>
<p>(Remember that the makefile compiler flag requires _DEFAULT to be added, and that the quotes must be escaped.).</p>
<p>The property and legal values are:</p>
<h4 id="tpm_trace_level">TPM_TRACE_LEVEL</h4>
<p>default - 0</p>
<p>0 - no tracing</p>
<p>1 - trace errors</p>
<p>2 - trace errors and execution flow</p>
<h4 id="tpm_data_dir">TPM_DATA_DIR</h4>
<p>default - current directory</p>
<p>set the directory where the TSS can store persistent data</p>
<h4 id="tpm_interface_type">TPM_INTERFACE_TYPE</h4>
<p>default - socsim</p>
<p>socsim - the socket simulator</p>
<blockquote>
<p>see</p>
<p>TPM_SERVER_NAME</p>
<p>TPM_SERVER_TYPE</p>
<p>TPM_COMMAND_PORT</p>
<p>TPM_PLATFORM_PORT</p>
</blockquote>
<p>dev - TPM device driver</p>
<blockquote>
<p>see</p>
<p>TPM_DEVICE</p>
</blockquote>
<h4 id="tpm_server_name">TPM_SERVER_NAME</h4>
<p>default - localhost</p>
<p>set the socket server name (full host name or dotted decimal)</p>
<h4 id="tpm_server_type">TPM_SERVER_TYPE</h4>
<p>Used with TPM_INTERFACE_TYPE = socsim</p>
<p>default - mssim</p>
<p>mssim - send packets in the Microsoft simulator format (header and footer)</p>
<p>raw - send packets in the raw TPM 2.0 specification Part 3 format</p>
<p>rawsingle - same as raw but opens and closes the connection for each command</p>
<p>(useful with the IBM SW TPM 1.2 simulator)</p>
<h4 id="tpm_command_port">TPM_COMMAND_PORT</h4>
<p>default - 2321</p>
<p>set the socket port for TPM commands</p>
<h4 id="tpm_platform_port">TPM_PLATFORM_PORT</h4>
<p>default - 2322</p>
<p>set the socket port for TPM simulator platform commands</p>
<h4 id="tpm_device">TPM_DEVICE</h4>
<p>Unix/Linux default - /dev/tpm0 (single user)</p>
<p>Windows default - Windows 7,8,10 Tbsi</p>
<p>For Unix, sets the TPM device name</p>
<p>/dev/tpmrm0 is the multi-user kernel resource manager</p>
<p>Once the kernel resource manager is upstreamed, this</p>
<p>may become the default.</p>
<p>For Windows, not currently used, only Tbsi supported</p>
<h4 id="tpm_encrypt_sessions">TPM_ENCRYPT_SESSIONS</h4>
<p>default 1</p>
<p>1 - Session state is saved encrypted</p>
<p>0 - Session state is saved in plaintext</p>
<p>Since session state can potentially hold secrets, it should normally be encrypted. When the process terminates, the ephemeral encryption key is lost.</p>
<p>See 4.9 Command Line Utilities for the special case of using the command line utilities. That section is not applicable when using the TSS library in programs.</p>
<h4 id="tpm_transmit_locality">TPM_TRANSMIT_LOCALITY</h4>
<p>default 0</p>
<p>set the locality for transmitting a command.</p>
<p>This property only affects the TPM_INTERFACE_TYPET socsim and TPM_SERVER_TYPE mssim. That is, the SW TPM packet format permits a locality specifier. HW TPM locality requires hardware support and cannot typically be set by an OS level application.</p>
<p>The main use case for this property is to send TPM2_Startup at a different locality to simulate the UEFI event EV_NO_ACTION, which sets PCR 0 to the startup locality.</p>
<h3 id="tss_setproperty">TSS_SetProperty()</h3>
<p>#include &lt;ibmtss/tss.h&gt;</p>
<p>TPM_RC TSS_SetProperty(TSS_CONTEXT *tssContext,</p>
<blockquote>
<p>int property,</p>
<p>const char *value);</p>
</blockquote>
<p>The TSS_SetProperty() function overrides the defaults and environment variables programmatically.</p>
<p>If the property is related to the connection, an open connection is closed before the property is processed.</p>
<blockquote>
<p>NOTE: The close occurs even if the new value is the same as the old value. This can be used to close a connection without deleting the context.</p>
<p>Question: Is it good to mandate this behavior? It offers functionality and makes the implementation easier, but perhaps it's too clever?</p>
</blockquote>
<p>NOTE: The value parameter is always a string. For simplicity, the 'value' pointer is stored. The input should be a constant string.</p>
<p>NOTE: For the property TPM_TRACE_LEVEL, tssContext is ignored. The trace level is per process, not per context.</p>
<h2 id="extra-parameter">Extra Parameter</h2>
<p>The extra parameter is a catch-all for any parameters that TSS_Execute() requires beyond the normal TPM command and response parameters.</p>
<p>TPM2_StartAuthSession needs the bind password so that it can calculate the session key.</p>
<h2 id="other-apis-and-headers">Other APIs and Headers</h2>
<p>Headers are in the …/utils/ibmtss directory.</p>
<p>#include &lt;ibmtss/tss.h&gt;</p>
<p>The utility / demo applications cheat a bit, in that they call into TSS utility functions. These are less likely to be stable than the official API above.</p>
<ul>
<li><p>tss.h: The official API</p></li>
<li><p>tsserror.h: Included by tss.h for convenience. Error codes may be added.</p></li>
<li><p>tssmarshal.h: Marshal structures to arrays. These are likely to be stable. They are similar to the TPM side functions but return errors.</p></li>
<li><p>Unmarshal_fp.h: Unmarshal arrays to structures.</p></li>
</ul>
<blockquote>
<p>The functions without the TSS_ prefix are deprecated. They were borrowed from the TPM side but used a signed value for the size. The functions prefixed TSS_ use an unsigned value for the size.</p>
</blockquote>
<ul>
<li><p>tssresponsecode.h: Response code to text. Useful for debugging. The API should be stable, but the actual output may change.</p></li>
<li><p>tssprint.h: Functions to print structures. Useful for debugging. The API should be stable. Functions may be added, and the output is likely to change.</p></li>
<li><p>tssprintcmd.h: Functions to print command parameters. Used in TSS verbose tracing. The API should be stable, but the actual output may change.</p></li>
<li><p>tssutils.h: Demo helper functions. These are useful for rapid prototyping but are not recommended for production code.</p></li>
<li><p>tssfile.h: Demo helper functions. These are useful for rapid prototyping but are not recommended for production code.</p></li>
<li><p>tsscrypto.h: Sample crypto code. These are useful for rapid prototyping but are not recommended for production code.</p></li>
<li><p>Any of the lower layer TSS functions are for TSS internal use. They should not be called.</p></li>
</ul>
<h1 id="application-notes">Application Notes</h1>
<p>Several areas have non-obvious usage. They are described here.</p>
<h2 id="tpm-simulator">TPM Simulator</h2>
<p>A typical cause of a hang when sending the first command to the TPM simulator is that it has not received a simulated "powered up." The IBM TPM simulator does not require this, but others may. Send this command:</p>
<p>&gt; powerup</p>
<p>The platform firmware initializes a hardware TPM. The TPM simulator requires this command:</p>
<p>&gt; startup</p>
<h2 id="parameter-encryption">Parameter Encryption</h2>
<p>The caller does NOT perform parameter encryption. Simply set the session attribute to either or both of TPMA_SESSION_ENCRYPT or TPMA_SESSION_DECRYPT.</p>
<h2 id="session-salt">Session Salt</h2>
<p>To salt, the caller should set tpmKey (the handle of a loaded decrypt key) in TPM2_StartAuthSession. The key must be an RSA 2048-bit key or ECC NIST P256 key with sign clear and decrypt set.</p>
<p>The caller must supply the extra parameter as a StartAuthSession_Extra structure.</p>
<p>The caller does NOT supply the HMAC salt. The encryptedSalt parameter is ignored, as the TSS generates the salt.</p>
<h2 id="session-bind">Session Bind</h2>
<p>To bind, the caller should set bind (the bind entity handle) in TPM2_StartAuthSession. The caller must supply the extra parameter as a StartAuthSession_Extra structure and set the bindPassword member to the bind handle password.</p>
<h2 id="nv">NV</h2>
<p>For applications that do not share an NV index and don't use global locks or transient locks or written status that change after a reboot, the following details are unnecessary. Just issue the TPM2_NV_DefineSpace and everything works, including HMAC sessions.</p>
<p>For applications that do not satisfy the above criteria, the application must issue TPM2_NV_ReadPublic and validate that the public area is as expected, including the locks.</p>
<p>This will not typically occur in real applications. The transient locks and written status permit low level firmware to perform pre-OS operations. By the time post-OS applications are running, the locks and written status should be restored.</p>
<h3 id="rationale">Rationale</h3>
<p>Why? For authorization, the TSS includes the Name (a hash of the public NV metadata) in the HMAC calculation. This ensures that the NV index has not been replaced with a different version with untrusted metadata.</p>
<p>Normally, the TSS tracks the Name, even when the application changes the written or lock attributes. However, if the attributes (and therefore the Name) change outside the application, the TSS is unable to track the change. In those cases, the application must read the public data and validate it.</p>
<p>Why doesn't the TSS automatically issue the TPM2_NV_ReadPublic? If it did that, it would encourage the application developer to blindly trust the index. The application is expected to examine the TPM2_NV_ReadPublic return (e.g., the policy, the attributes) and decide whether the index is trusted. The TSS cannot enforce this, but it does at least encourage it.</p>
<p>The index Name can change as the metadata changes. These changes include the "written" bit and the read and write locks. The TSS automatically tracks the changes performed on a single index by the application. It does not track:</p>
<ol type="1">
<li><p>Changes "out of band", by a different application, including an attacker.</p></li>
</ol>
<p>This will surface as an HMAC failure. The application should reissue TPM2_NV_ReadPublic and decide if the index is still trusted.</p>
<ol start="2" type="1">
<li><p>Changes to transient lock status due to a reboot.</p></li>
</ol>
<p>If the application is aware of the reboot, it can reissue TPM2_NV_ReadPublic and re-evaluate the return. Otherwise, it can wait for the potential HMAC failure and handle it as above.</p>
<ol start="3" type="1">
<li><p>Locks due to a global lock, because it's hard and because global lock is expected to be used only at provisioning, if ever.</p></li>
</ol>
<p>This case will probably never occur in practice. If it does, handle the HMAC failure as above.</p>
<h3 id="nv-pre-provisioning">NV Pre-provisioning</h3>
<p>This is the case where some other application has used TPM2_NV_DefineSpace to pre-provision an index. As an alternative to the application evaluating the TPM2_NV_ReadPublic response, the NV metadata and Name can be pre-provisioned when the application is installed. Two files are required:</p>
<p>[01nnnnnn] is the hex value of the NV index.</p>
<ol type="1">
<li><p>h[01nnnnnn].bin - The Name, a binary hash of the public data</p></li>
<li><p>nvp[01nnnnnn].bin - The marshaled TPMS_NV_Public</p></li>
</ol>
<h2 id="tpm2_loadexternal">TPM2_LoadExternal</h2>
<p>This command is unique, in that it has an optional parameter, TPM2B_SENSITIVE <em>inPrivate</em>. The caller should use the size as a flag: 0 for not present, and non-zero for present.</p>
<p>Rationale:</p>
<p>The TPM uses the <em>inPrivate.size</em> zero to indicate that the parameter is not present and uses the correct marshaled size to indicate that the parameter is present. This TSS uses that design pattern, but, as with other TPM2B's that wrap structures, it does not require the caller to marshal the structure and determine the correct size.</p>
<h2 id="connecting-to-resource-managers">Connecting to Resource Managers</h2>
<p>An issue arises when using the TSS utilities (not the TSS itself) on a platform with a resource manager. Windows 10 has a resource manager called TBS and Linux as of 4.12 uses /dev/tpmrm0.</p>
<p>A resource manager flushes all resources (objects like keys, and sessions) when a connection closes. Since the utilities are standalone processes, the connection closes after each invocation. Thus, for example, a utility can load a key, but, when the "load" command terminates, the resource manager will flush the key.</p>
<p>This is not an issue for a complete application using the TSS because the TSS keeps the connection open through multiple TPM commands. For prototyping using the utilities, the Linux solution is to bypass the resource manager using /dev/tpm0. For Windows 10, use a proxy to simulate this persistent connection behavior.</p>
<p>The "tpmproxy" program connects as a socket server on one side and a TPM device driver on the other. Once the proxy starts, the Windows resource manager sees one persistent connection, as desired. The utilities use the socket interface to the proxy.</p>
<p>Both the TSS and the proxy support both a raw packet format and the Microsoft simulator wrapped format.</p>
<p>The default, using the wrapped format, can also be specified on the TSS side with</p>
<p>&gt; TPM_INTERFACE_TYPE=socsim</p>
<p>&gt; TPM_SERVER_TYPE=mssim</p>
<p>and the tpmproxy with -mssim.</p>
<p>The raw format can be specified with</p>
<p>&gt; TPM_INTERFACE_TYPE=socsim</p>
<p>&gt; TPM_SERVER_TYPE=raw</p>
<p>and the tpmproxy with -raw.</p>
<h2 id="endorsement-key-ek-certificates">Endorsement Key (EK) Certificates</h2>
<p>The TSS includes several TPM vendor EK root certificates for convenience.</p>
<p>There is no reason for a user to trust these certificates. Obtain production certificates directly from the TPM vendor.</p>
<p>These URLs are provided for convenience. Observe that some URLs are http. I encourage all readers to ask the TPM vendors to offer these certificates over a secured web page, since they form the root of trust for TPM authenticity.</p>
<p>Utilities such as "createek" that take a -root argument require a list of EK root certificates in a file. The utilities include a sample file …/utils/certificates/rootcerts.txt. The file MUST be edited, since the file names must have a complete path to your install directory.</p>
<p>The file must have a Unix newline (only LF, 0x0a), not a DOS newline, even on Windows platforms.</p>
<p>Certificates must be in PEM format. To convert from DER format (.cer, .crt) to PEM using openssl:</p>
<p>&gt; openssl x509 -in cert.cer -inform DER -out cert.pem</p>
<h3 id="nuvoton">Nuvoton</h3>
<p><a href="https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton%20TPM%20Root%20CA%202110.cer">https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton%20TPM%20Root%20CA%202110.cer</a></p>
<p><a href="https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton%20TPM%20Root%20CA%201110.cer">https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton%20TPM%20Root%20CA%201110.cer</a></p>
<p>https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton%20TPM%20Root%20CA%202111.cer</p>
<p>https://www.nuvoton.com/security/NTC-TPM-EK-Cert/NuvotonTPMRootCA1210.cer</p>
<p>https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton TPM Root CA 2112.cer</p>
<p>https://www.nuvoton.com/security/NTC-TPM-EK-Cert/Nuvoton TPM Root CA 1111.cer</p>
<h3 id="st-micro">St Micro</h3>
<p>This list was extracted from http://www.st.com/resource/en/data_brief/stsw-tpmcert1.pdf</p>
<p>GlobalSign Trusted Computing CA</p>
<p>http://secure.globalsign.com/cacert/gstpmroot.crt</p>
<p>ST TPM Root certificate</p>
<p>http://secure.globalsign.com/cacert/stmtpmekroot.crt</p>
<p>ST Intermediate CA 01</p>
<p>http://secure.globalsign.com/cacert/stmtpmekint01.crt</p>
<p>ST Intermediate CA 02</p>
<p>http://secure.globalsign.com/cacert/stmtpmekint02.crt</p>
<p>ST Intermediate CA 03</p>
<p>http://secure.globalsign.com/cacert/stmtpmekint03.crt</p>
<p>ST Intermediate CA 04</p>
<p>http://secure.globalsign.com/cacert/stmtpmekint04.crt</p>
<p>ST Intermediate CA 05</p>
<p>http://secure.globalsign.com/cacert/stmtpmekint05.crt</p>
<p>GlobalSign Trusted Platform Module ECC</p>
<p>Root CA</p>
<p>http://secure.globalsign.com/cacert/tpmeccroot.crt</p>
<p>STM TPM ECC Root CA 01</p>
<p>http://secure.globalsign.com/stmtpmeccroot01.crt</p>
<p>STM TPM ECC Intermediate CA 01</p>
<p>http://secure.globalsign.com/stmtpmeccint01.crt</p>
<h3 id="infineon">Infineon</h3>
<p><a href="https://www.infineon.com/cms/en/product/promopages/optiga_tpm_certificates">https://www.infineon.com/cms/en/product/promopages/optiga_tpm_certificates</a></p>
<h3 id="nationz">NationZ</h3>
<p>Root</p>
<p>https://pki.nationz.com.cn/EkRootCA/EkRootCA.crt</p>
<p>Intermediate certificates</p>
<p>https://pki.nationz.com.cn/EkMfrCA001/EkMfrCA001.crt</p>
<p>https://pki.nationz.com.cn/EkMfrCA002/EkMfrCA002.crt</p>
<p>https://pki.nationz.com.cn/EkMfrCA003/EkMfrCA003.crt</p>
<h3 id="intel">Intel</h3>
<p>PTT EK Root Certificate</p>
<p>https://upgrades.intel.com/content/CRL/ekcert/EKRootPublicKey.cer</p>
<p>PTT EK Intermediate Certificate</p>
<p><a href="http://upgrades.intel.com/content/CRL/ekcert/SPTHEPIDPROD_EK_Platform_Public_Key.cer">http://upgrades.intel.com/content/CRL/ekcert/SPTHEPIDPROD_EK_Platform_Public_Key.cer</a></p>
<h3 id="intel-ek-certificate-download">Intel EK Certificate Download</h3>
<p>As of June 2017, the Intel PTT did not come provisioned with EK certificates. They must be downloaded using this procedure.</p>
<ul>
<li><p>Read the EK public key</p></li>
<li><p>Construct digest data</p>
<ul>
<li><p>For RSA, concatenate the public modulus to the default exponent 010001, all in binary.</p></li>
<li><p>For ECC, this step is currently undocumented.</p></li>
</ul></li>
<li><p>Calculate a SHA-256 digest of the digest data</p></li>
<li><p>Base64 encode the digest</p></li>
<li><p>Convert the base64 to URL base64 by changing = to %3D, + to -, and / to _.</p></li>
<li><p>Prepend <a href="https://ekop.intel.com/ekcertservice/">https://ekop.intel.com/ekcertservice/</a> to form the certificate URL.</p></li>
<li><p>Use a browser to display the certificate (or use wget and edit in a text editor)</p></li>
<li><p>Extract the text between the &lt;certificate&gt; and &lt;/certificate&gt; to a text editor.</p></li>
<li><p>Convert the URL base64 to base64 by changing %3D to =, - to +, and _ to /. Remove all newlines.</p></li>
<li><p>Base64 decode to create the DER certificate.</p></li>
</ul>
<h2 id="command-line-utilities">Command Line Utilities</h2>
<p>See also section 4.7 Connecting to Resource Managers.</p>
<p>As stated in section 3.4.2 Properties, the default is to build the TSS library to encrypt session state with an ephemeral encryption key that is lost when the application exits.</p>
<p>This behavior would preclude using the command line utilities with sessions, since the encryption key would change. There are two facilities to remedy this.</p>
<ol type="1">
<li><p>For stand-alone debugging, save session state in plaintext. For example, use an environment variable:</p></li>
</ol>
<p>&gt; setenv TPM_ENCRYPT_SESSIONS 0 (csh, tcsh)</p>
<p>&gt; export TPM_ENCRYPT_SESSIONS=0 (bash)</p>
<p>&gt; set TPM_ENCRYPT_SESSIONS=0 (windows)</p>
<p>or the equivalent compile time flag</p>
<p>-DTPM_ENCRYPT_SESSIONS_DEFAULT="\"0\""</p>
<ol start="2" type="1">
<li><p>For using the command line utilities securely, either stand-alone or in scripts, a fixed encryption key can be specified.</p></li>
</ol>
<p>In the script:</p>
<p>TPM_SESSION_ENCKEY=`./getrandom -by 16 -ns`</p>
<p>On the command line:</p>
<p>&gt; setenv TPM_SESSION_ENCKEY `./getrandom -by 16 -ns`</p>
<h2 id="tss-for-tpm-1.2">TSS for TPM 1.2</h2>
<p>This is new code in 2018. The TSS for TPM 1.2 uses the identical API as in section 3 API, but with TPM 1.2 structures and ordinals.</p>
<p>There is currently support for about 20 TPM 1.2 commands, specifically those commands that are required to implement an attestation client. It also includes support commands to create a SW TPM EK certificate and the activate identity blob, and to extend firmware and IMA event logs into a TPM for testing. More commands can be easily added upon user request.</p>
<p>To build a combined TPM 2.0 and TPM 1.2 TSS:</p>
<p>&gt; make -f makefiletpmc clean all</p>
<p>To build a TPM 2.0 only TSS</p>
<p>&gt; make -f makefiletpm20 clean all</p>
<p>To build a TPM 1.2 only TSS</p>
<p>&gt; make -f makefiletpm12 clean all</p>
<p>The utilities and a basic regression test (reg.sh) are in the ../utils12 directory.</p>
<p>The regression test requires a software TPM 1.2 that is 'straight from the factory' - with no TPM state. The reason is that creating the standard TCG EK certificate requires an unlocked TPM. Once NV is locked, it can never be unlocked. Before running the regression test, remove the state and restart the TPM.</p>
<p>The standard TPM 1.2 is opt-in and is shipped disabled and deactivated. While the IBM software TPM comes with tools to enable and activate the TPM, users may find it less of a nuisance to use 'makefile-en-ac' to build a TPM that is already enabled and activated at its first start.</p>
<h1 id="examples">Examples</h1>
<p>Each standalone utility serves as an example for a single command.</p>
<p>There are also two examples that show how several commands can be chained together to form an application</p>
<h2 id="signapp.c">signapp.c</h2>
<p>The signapp.c source demonstrates how the TSS handles bind and salt sessions. It uses sample code to create an EK. It uses a policy session to authorize the EK. It authorizes a signing key using both HMAC and policy sessions, where the policy can be policy password or policy authvalue. The signing key policy also has an AND term for the command code 'sign'.</p>
<ul>
<li><p>Create an EK for the salt</p></li>
<li><p>Start an authorization policy session, salt with the EK</p></li>
<li><p>Use policysecret to authorize the EK</p></li>
<li><p>Create a signing key under the EK, permit password and policy authorization</p></li>
<li><p>Restart the policy session</p></li>
<li><p>Use policysecret to authorize the EK</p></li>
<li><p>Load the signing key under the EK, using the session</p></li>
<li><p>Create an HMAC session, salt with the EK, bind with the signing key</p></li>
<li><p>Sign a digest, using the HMAC</p></li>
<li><p>Verify the signature</p></li>
<li><p>Restart the policy session</p></li>
<li><p>Use policy command code and policy authvalue to authorize the signing key</p></li>
<li><p>Sign a digest</p></li>
<li><p>Verify the signature</p></li>
<li><p>Flush the policy and HMAC sessions</p></li>
<li><p>Flush the EK primary key</p></li>
<li><p>Flush the signing key</p></li>
</ul>
<h2 id="writeapp.c">writeapp.c</h2>
<p>The writeapp.c source demonstrates how the TSS handles bind and salted session, and tracks entity Name changes without application coding.</p>
<ul>
<li><p>Create an EK for the salt</p></li>
<li><p>Start a session, salt with EK</p></li>
<li><p>Define an NV index, salted session</p></li>
<li><p>Flush the session</p></li>
<li><p>Start a session, salt with EK, bind to unwritten NV index</p></li>
<li><p>Write NV, changes the Name, bound, salt, encrypt session</p></li>
<li><p>Start a session, salt with EK, bind to written NV index</p></li>
<li><p>Write NV, bound, salt, encrypt session</p></li>
<li><p>Undefine NV index</p></li>
<li><p>Flush EK</p></li>
</ul>
<h1 id="utility-tools">Utility tools</h1>
<p>In addition to the command line tools for each TPM command, there are several utilities that are useful for development.</p>
<p>They accept various digest and asymmetric algorithms and other options as applicable. Use -h for details.</p>
<h2 id="debugging-aids">Debugging Aids</h2>
<h3 id="reponsecode">reponsecode</h3>
<p>Prints a TPM or TSS hex response code as text.</p>
<h3 id="printattr">printattr</h3>
<p>Prints a TPM hex attribute as text.</p>
<p>It supports object, session, startup, and NV attributes.</p>
<h3 id="timepacket">timepacket</h3>
<p>This is useful for profiling - timing the duration of a single command.</p>
<p>It is occasionally useful to debug a command packet obtained from a source other than the TSS.</p>
<p>It takes a hex ascii input command string so that TSS processing is excluded. The string can be obtained by running the command first with -v and capturing the TSS trace.</p>
<p>This tool is restricted to commands that:</p>
<ul>
<li><p>can be run repeatedly. I.e., it cannot use policy sessions.</p></li>
<li><p>do not include varying data. E.g., it cannot have an HMAC with rolling nonces.</p></li>
</ul>
<h2 id="policy-aids">Policy Aids</h2>
<p>These tools provide primitive aids to calculating and debugging policies. The regression test script comments explain how the tools were used to calculate the test policies. The utils/policies directory holds both the 'source' hexascii and binary policies.</p>
<h3 id="policymaker">policymaker</h3>
<p>This tool accepts a set of hex ascii AND terms, one per line, and calculates the resulting policy. An empty policyRef is represented by a blank line.</p>
<p>The result can be traced and/or output in binary in a format directly usable as a utility input.</p>
<p>-v traces the intermediate terms. In combination with policygetdigest, it can be used to debug a policy term by term.</p>
<p>-ns (no white space) traces the output in a format that can be used as input to a policy OR (which is just a concatenation of AND terms).</p>
<p>-nz calculates the hash without the normal 'extend starting with zeros', useful for calculating an 'aHash' such as a cpHash.</p>
<h3 id="policymakerpcr">policymakerpcr</h3>
<p>This tool calculates a policypcr AND term in a format suitable for input to policymaker. It accepts a bit mask of selected PCRs and a white list of PCR values, one per line.</p>
<h3 id="publicname">publicname</h3>
<p>This tool calculates a TPM Name from a TPM object or NV public structure, or from a PEM or DER format public key.</p>
<p>This is useful for constructing policies at times that the TPM is not available to calculate the Name.</p>
<h2 id="key-manipulation">Key Manipulation</h2>
<h3 id="createek">createek</h3>
<p>This tools aggregates several EK manipulation tasks:</p>
<ul>
<li><p>Creates an EK primary key based on TCG standards.</p></li>
<li><p>Prints an EK template or nonce if provisioned.</p></li>
<li><p>Prints an EK certificate. This function is also integrated into nvread.</p></li>
<li><p>Validates an EK certificate against the TPM vendor root certificates.</p></li>
</ul>
<h3 id="createekcert">createekcert</h3>
<p>This tools provisions an EK certificate in TPM NV for testing.</p>
<p>The EK is generated based on TCG standards.</p>
<h3 id="tpm2pem">tpm2pem</h3>
<p>This tools converts an existing TPM format public key to PEM format.</p>
<p>This function is also integrated into several tools, such as create, createprimary, createloaded, and readpublic.</p>
<h2 id="event-logs">Event Logs</h2>
<p>The package has sample functions for parsing pre-OS and post-OS (IMA) event logs. These tools aggregate some of these functions.</p>
<h3 id="eventextend">eventextend</h3>
<p>This tool parses a pre-OS (BIOS, UEFI) event log. It can:</p>
<ul>
<li><p>Extend the events into a TPM, simulating pre-OS firmware.</p></li>
<li><p>Calculate expected TPM PCR values.</p></li>
<li><p>Calculate a boot aggregate.</p></li>
</ul>
<h3 id="imaextend">imaextend</h3>
<p>This tool parses a post-OS Linux IMA log. It can:</p>
<ul>
<li><p>Extend the events into a TPM, simulating post-OS IMA software.</p></li>
<li><p>Calculate expected TPM PCR values.</p></li>
</ul>
<p>To permit scripting a test platform, it can accept beginning and ending events.</p>
<h1 id="build">Build</h1>
<p>The builds for Linux and Windows create the TSS shared object / dll and about 110 command line programs. The command line programs can be used in a script for rapid prototyping or as sample usage code.</p>
<p>There are currently makefiles for common build options, listed later.</p>
<p>The build files clear TPM_ENCRYPT_SESSIONS, which is useful for prototyping and regression testing. This should be removed for production applications.</p>
<h2 id="build-options">Build Options</h2>
<p>Several compile time macros permit building a variation of the TSS library. Features may be lost, but the tradeoff may be important in some environments.</p>
<p><strong>Since the regression test does not function against all builds, some variations are very lightly tested. Please report bugs.</strong></p>
<h3 id="tpm_tpm20-and-tpm_tpm12">TPM_TPM20 and TPM_TPM12</h3>
<p>Define one or both of these for a TSS that supports TPM 2.0 and/or TPM 1.2.</p>
<p>TPM 1.2 support is incomplete. See section 4.10 TSS for TPM 1.2.</p>
<h3 id="tpm_posix-or-tpm_windows">TPM_POSIX or TPM_WINDOWS</h3>
<p>Define one of these for a POSIX (Linux, AIX, Raspian, zLinux, etc.) or Windows TSS.</p>
<h3 id="tpm_windows_tbsi">TPM_WINDOWS_TBSI</h3>
<p>For Windows, compiles in hardware TPM support.</p>
<p>This was useful to remove hardware TPM support for Windows 7, where the TPM 2.0 install required several hacks. Since Windows 10 supports TPM 2.0, there is little reason not to define this macro.</p>
<h3 id="tpm_tss_nofile">TPM_TSS_NOFILE</h3>
<p>Defining this macro builds a TSS library that does not use files for temporary and persistent state. All state is stored in the TSS context and is lost when the context is deleted.</p>
<p>Drawbacks:</p>
<ul>
<li><p>Scripting, which requires state to persist between processes, does not work.</p></li>
<li><p>Names and public keys of persistent entities do not persist, so the entities must be reread (and revalidated) at each connection.</p></li>
<li><p>Context save and load are not implemented yet.</p></li>
<li><p>There are currently some fixed size arrays for transient object and session state.</p></li>
</ul>
<h3 id="tpm_tss_nocrypto">TPM_TSS_NOCRYPTO</h3>
<p>Defining this macro builds a TSS library that does not depend on a crypto library.</p>
<p>Drawbacks:</p>
<ul>
<li><p>Salted sessions do not work.</p></li>
<li><p>HMAC sessions do not work, including policies that require HMAC.</p></li>
<li><p>Encrypt and decrypt sessions do not work.</p></li>
</ul>
<h3 id="tpm_tss_no_print">TPM_TSS_NO_PRINT</h3>
<p>Defining this macro builds a TSS that does no tracing and compiles out all print functions.</p>
<h3 id="tpm_tss_noecc">TPM_TSS_NOECC</h3>
<p>Defining this macro builds a TSS that does not require crypto library elliptic curve support.</p>
<h3 id="tpm_tss_norsa">TPM_TSS_NORSA</h3>
<p>Defining this macro builds a TSS that does not require crypto library RSA support.</p>
<h3 id="tpm_tss_noenv">TPM_TSS_NOENV</h3>
<p>Defining this macro builds a TSS that does not call the getenv() function. This supports platforms that do not implement environment variables.</p>
<p>The TSS properties still use defaults that can be changed at build time, and it still supports the TSS_SetProperty() function.</p>
<h3 id="tpm_nosocket">TPM_NOSOCKET</h3>
<p>Defining this macro builds a TSS that does not include the socket interface. This supports platforms that do not implement sockets.</p>
<p>When this macro is defined, TPM_INTERFACE_TYPE defaults to dev, not socsim.</p>
<h3 id="tpm_tss_nodev">TPM_TSS_NODEV</h3>
<p>Defining this macro builds a TSS that does not include the TPM device driver interface.</p>
<p>The main use for this macro is a Windows platform using mingw. mingw does not apparently support the Tbsi interface.</p>
<h3 id="tpm_tss_nocmdcheck">TPM_TSS_NOCMDCHECK</h3>
<p>Defining this macro builds a TSS that does not implement input parameter checking. The commands are sent as-is to the TPM, which will presumably do its own check.</p>
<p>This two main use cases of this macro are:</p>
<ul>
<li><p>to reduce the size of the TSS library by about 10%.</p></li>
<li><p>to permit the TSS to send error cases for TPM testing.</p></li>
</ul>
<p>The main disadvantage of this macro is that debugging is harder. Rather setting breakpoints in the TSS to debug, the developer must rely on the TPM return codes.</p>
<h3 id="tpm_tss_nodeprecated">TPM_TSS_NODEPRECATED</h3>
<p>Defining this macro removes deprecated TPM functions. This slightly reduces the library size in cases where the application is not using the functions.</p>
<p>To skip those algorithms in the regression test, set the environment variable TPM_TSS_NODEPRECATEDALGS.</p>
<h3 id="tpm_tss_nodeprecatedalgs">TPM_TSS_NODEPRECATEDALGS</h3>
<p>Defining this macro removes deprecated crypto algorithms from both the TSS and the command line utilities. If the algorithm is used, the TSS returns an error.</p>
<p>Currently, the only algorithm removed is SHA-1.</p>
<h3 id="tpm_tss_nuvoton">TPM_TSS_NUVOTON</h3>
<p>Defining this macro adds TSS support for the Nuvoton proprietary TPM configuration commands.</p>
<h3 id="section"></h3>
<h2 id="directories">Directories</h2>
<p>The TSS ships with these directories:</p>
<p>…/utils TSS for both TPM 1.2 and TPM 2.0.</p>
<blockquote>
<p>TPM 2.0 utility / demo applications</p>
</blockquote>
<p>…/utils/regtests TSS for TPM 2.0 regression tests</p>
<p>…/utils/policies TSS for TPM 2.0 regression test policies and miscellaneous files</p>
<p>…/utils/certificates TPM for TPM 2.0 and TPM 1.2 vendor EK root certificates</p>
<p>…/utils12 TPM 1.2 utility / demo applications</p>
<blockquote>
<p>TSS for TPM 1.2 regression test</p>
</blockquote>
<p>…/demo TSS for TPM 2.0 demo web pages</p>
<p>…/tpmutils TSS for TPM 2.0 Visual Studio files</p>
<p>To extract the tarball</p>
<p>&gt; cd …</p>
<p>&gt; tar xvf ibmtssnnn.tar .</p>
<h2 id="linux">Linux</h2>
<p>These are the mainstream TPM 2.0 instructions. For the new TPM 1.2 support, see the application note in 4.10 TSS for TPM 1.2.</p>
<p>Install OpenSSL 1.0.x or 1.1.x.</p>
<p>Note: OpenSSL 1.1.x cannot validate early TPM 1.2 EK certificates. Newer TPM 1.2 certificates and TPM 2.0 certificates validate.</p>
<p>&gt; cd …/utils</p>
<p>&gt; make -f makefiletpmc</p>
<p>Note: Linux builds must have TPM_POSIX defined.</p>
<p>After building, run the regression test against a running simulator. -h gives help. The Linux version takes about 1 minute.</p>
<p>&gt; ./reg.sh -a</p>
<p>The regression test can run against a <strong>software</strong> TPM at /dev/tpm0. It will skip the power up sequence. However, it uses the environment variable TPM_INTERFACE_TYPE as the determination. If the default TPM_INTERFACE_TYPE was changed at compile time, the regression test will try the power up sequence unless the environment variable is also set.</p>
<p><strong>The regression test does not run against a hardware TPM</strong>, since the platform firmware will have set the platform authorization. There are likely to be other errors due to protected or unsupported TPM features.</p>
<p><strong>Use the regression test for TSS verification, not as a TPM test tool.</strong></p>
<p>The TPM device driver normally does not permit non-root access. Either</p>
<p>&gt; chmod 777 /dev/tpm0</p>
<p>or run as root or sudo.</p>
<h2 id="windows">Windows</h2>
<p>Read all of this. It’s tricky.</p>
<p>Install OpenSSL 3.1 64-bit. Install Win64 OpenSSL, not the "Light" versions, which I believe do not contain the development files. The usual place to get OpenSSL binaries for Windows is:</p>
<p>http://slproweb.com/products/Win32OpenSSL.html</p>
<p>Recent Shining Light installs point to</p>
<p>C:\OpenSSL-Win364</p>
<p>Change this to</p>
<p>C:\Program Files\OpenSSL</p>
<p>If you chose not to install OpenSSL in this location, you must fix the build paths. In other words, use the recommended location.</p>
<p>This directory should be added to the Path environment variable if it's not already there:</p>
<p>c:\Program Files\OpenSSL\bin</p>
<p>Note: Windows builds must have TPM_WINDOWS defined.</p>
<p>After building, run the regression test against a running simulator. The Windows version takes about 15 minutes.</p>
<blockquote>
<p>The Windows script assumes that typical command line tools such as touch and diff are installed. A typical download location is</p>
</blockquote>
<p><a href="http://gnuwin32.sourceforge.net/packages.html">http://gnuwin32.sourceforge.net/packages.html</a></p>
<p>See CoreUtils and DiffUtils.</p>
<p>&gt; reg.bat</p>
<p>The regression test script defaults to the executables being in the same directory as the script, …/tpm2/utils. This is correct for the gcc build, but not for the Visual Studio build. To point to those executables, set this environment variable. <strong>Do not omit the trailing slash</strong>.</p>
<p>&gt; set TPM_EXE_PATH=..\tpmutils\x64\Debug\</p>
<p>&gt; set TPM_EXE_PATH=..\tpmutils\x64\Release\</p>
<h3 id="windows-gcc">Windows gcc</h3>
<p>A mingw (Minimalist GNU for Windows) makefile.mak is included.</p>
<p>Issues:</p>
<ul>
<li></li>
<li><p>mingw does not seem compatible with the Windows 10 TBSI. Thus, the build does not have hardware TPM support.</p></li>
</ul>
<p>For these reasons, the Visual Studio project is recommended.</p>
<p>Contributions to fix this is welcome. </p>
<p>&gt; cd …/utils</p>
<p>&gt; make -f makefile.mak</p>
<h3 id="windows-visual-studio">Windows Visual Studio</h3>
<p>VS solution and project files are supplied. The Visual Studio 2022 Solution is …/tpmutils/tpmutils.sln.</p>
<p>The default is to connect to the socket simulator using the Microsoft simulator packet format. To change the default from a SW TPM to a HW TPM, add the preprocessor definition:</p>
<p>TPM_INTERFACE_TYPE_DEFAULT="dev"</p>
<h3 id="section-1"></h3>
<ol type="1">
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
</ol>
<h2 id="mac">Mac</h2>
<p>This is a contribution. I did not test it.</p>
<ul>
<li><p>install homebrew</p></li>
<li><p>install openssl -&gt; brew install openssl</p></li>
<li><p>install gawk -&gt; brew install gawk</p></li>
<li><p>set PATH of shell (terminal):</p></li>
</ul>
<blockquote>
<p>PATH=/usr/local/Cellar/openssl/1.0.2m/bin/:$PATH</p>
<p>PATH=/usr/local/Cellar/gawk/4.2.0/bin/:$PATH</p>
<p>Make this permanent by adding to a profile.</p>
</blockquote>
<ul>
<li><p>Build using makefile.mac</p></li>
</ul>
<h2 id="aix">AIX</h2>
<p>Use gnu make (gmake), not make.</p>
<p>&gt; cd …/utils</p>
<p>&gt; gmake -f makefile.aix</p>
<p>After building, run the regression test against a running Microsoft simulator. -h gives help. Since the TPM simulator does not run on AIX yet, set the TPM_SERVER_NAME environment variable.</p>
<p>&gt; reg.sh -a</p>
<h1 id="fedora">Fedora</h1>
<p>This section is only relevant to a Fedora rpm install. It is a work in progress and may not be 100% correct yet.</p>
<p>Prerequisite:</p>
<p># yum install rpm-build</p>
<h2 id="local-install">Local Install</h2>
<p>Download the rpms:</p>
<p>TBD</p>
<ol type="1">
<li><p>Install binaries:</p></li>
</ol>
<ul>
<li><p>the libraries - /usr/lib64/libibmtss.so.0.1and the link /usr/lib64/libibmtss.so.0</p></li>
<li><p>the utilities - /usr/bin/tssxxx. Note that the installed utilities are namespaced with the 'tss' prefix.</p></li>
<li><p>the license - /usr/share/doc/ibmtss-nnn/LICENSE</p></li>
</ul>
<p># rpm -ivh ibmtss-nnn-1.el6.x86_64.rpm</p>
<ol start="2" type="1">
<li><p>Install development headers:</p></li>
</ol>
<ul>
<li><p>the headers - /usr/include/ibmtss</p></li>
<li><p>the library - link /usr/lib64/libibmtss.so</p></li>
<li><p>this documentation - /usr/share/doc/ibmtss-devel-nnn/ibmtss.doc</p></li>
</ul>
<p># rpm -ivh ibmtss-devel-nnn-1.el6.x86_64.rpm</p>
<ol start="3" type="1">
<li><p>Install debug source and support</p></li>
</ol>
<p># rpm -ivh ibmtss-debuginfo-nnn-1.el6.x86_64.rpm</p>
<h2 id="alternative-local-install">Alternative Local Install</h2>
<p>Erase an old version as needed:</p>
<p># yum erase ibmtss-devel-nnn-1.el6.x86_64</p>
<p># yum erase ibmtss-nnn-1.el6.x86_64</p>
<p># yum erase ibmtss-debuginfo-nnn-1.el6.x86_64</p>
<p>Install (new method)</p>
<p># dnf install ./ibmtss-nnn-1.el6.x86_64.rpm</p>
<p># dnf install ./ibmtss-devel-nnn-1.el6.x86_64.rpm</p>
<p># dnf install ./ibmtss-debuginfo-nnn-1.el6.x86_64.rpm</p>
<p>Install (old method)</p>
<p># yum install ./ibmtss-nnn-1.el6.x86_64.rpm</p>
<p># yum install ./ibmtss-devel-nnn-1.el6.x86_64.rpm</p>
<p># yum install ./ibmtss-debuginfo-nnn-1.el6.x86_64.rpm</p>
<h2 id="repository-install">Repository Install</h2>
<p>Once the packages have been upstreamed, use this process.</p>
<p># dnf install ibmtss</p>
<h2 id="install-test">Install Test</h2>
<p>This assumes that the SW TPM has been installed, see this link:</p>
<p><a href="https://sourceforge.net/projects/ibmtpm20tss/?source=navbar">https://sourceforge.net/projects/ibmtpm20tss/?source=navbar</a></p>
<p>It also assumes that the regression test has been installed. See Section 8.5.</p>
<p>In reg.sh, change the utility prefix variable to tss.</p>
<p>PREFIX=tss</p>
<p>Run the regression test:</p>
<p>&gt; cd ~/rpmbuild/BUILD/ibmtss-nnn/utils</p>
<p>&gt; ./reg.sh</p>
<h2 id="source-rpms">Source rpms</h2>
<p>Install source (as non-root user)</p>
<p>&gt; rpm -ivh ibmtss-nnn-1.el6.src.rpm</p>
<p>The src rpm has a tarball and spec file.</p>
<h1 id="status">Status</h1>
<h2 id="utilities">Utilities</h2>
<p>The utilities serve several purposes:</p>
<ul>
<li><p>The utilities are called by a Unix shell or bat script to form the regression test.</p></li>
<li><p>The utilities are sample code on how to use the TSS.</p></li>
<li><p>The utilities can be used in a script for rapid prototyping.</p></li>
<li><p>The regression test scripts are sample code for how to use the utilities and the TPM to perform multi-step tasks.</p></li>
</ul>
<p>NOTE: The utility command line arguments are not stable. They change occasionally to improve consistency among utilities or to add features</p>
<p>The utilities currently do not permit all TPM command options. Let me know what needs enhancement.</p>
<h2 id="bugs">Bugs</h2>
<p>Please report bugs.</p>
<h2 id="untested">Untested</h2>
<p>These may "just work" but they have not been tested yet.</p>
<p>Users are welcome to suggest ECC tests and prioritize the below list.</p>
<ul>
<li><p>ECC commands - ECDH_KeyGen, ECDH_ZGen</p></li>
<li><p>PolicyLocality</p></li>
<li><p>TestParams</p></li>
</ul>
<h1 id="threading">Threading</h1>
<p>The TSS is not thread safe.</p>
<p>There are many issues with making a TSS thread safe, because the TPM is inherently single threaded. For example:</p>
<ul>
<li><p>There is only one channel to a TPM. Two threads writing bytes to a socket to a resource manager or simulator, or writing bytes to the device driver, will fail.</p></li>
<li><p>The TPM has session state that has to be coordinated with an application. For example, if a thread begins to calculate an HMAC for a session, and another thread uses the session, the rolling nonces will cause the first thread HMAC to fail.</p></li>
<li><p>Applications have state at a higher level. For example, if a thread begins to use a key and another thread saves the key context and flushes the key, the first thread's application will fail.</p></li>
</ul>
<p>I think the best we can do is provide a common "TSS lock semaphore" mechanism, so that threads can coordinate access to the TSS using a common API.</p>
<h1 id="troubleshooting">Troubleshooting</h1>
<p>This section includes some frequent issues and solutions.</p>
<h2 id="environment-variables">Environment Variables</h2>
<p>The instructions in 3.4 Optional Customization and elsewhere are often specific to one Unix shell. See your shell documentation for variations. Windows uses yet another syntax.</p>
<p>Settings are local to one process (to one window). When the process exits (when the windows is closed), the setting is lost. To create a persistent setting, use a dotfile (Unix) or a control panel setting (Windows.)</p>
<h2 id="command-line-utilities-fail-on-windows-10">Command line utilities fail on Windows 10</h2>
<p>Windows blocks executables with the strings setup, install, update, and patch in the name. Thus, TPM utilities like sequenceupdate.exe will not run.</p>
<p>One work around is to run the commands shell as administrator. Right click "Command Prompt" and select "Run as administrator".</p>
<h2 id="openssl-linking-on-windows">OpenSSL Linking on Windows</h2>
<p>A failure linking with OpenSSL on Windows is very often caused by multiple versions of OpenSSL installed on the platform. The easiest solution is to run the uninstaller, delete all the OpenSSL directories, and then install just once.</p>
<p>The Windows 10 crypto library has function names that clash with OpenSSL, particularly in the area of X.509 support. Visual Studio includes it by default when using. To remove those headers, define WIN32_LEAN_AND_MEAN. Use the command line utilities as samples.</p>
<h2 id="loaded-objects-keys-disappear">Loaded objects (keys) disappear</h2>
<p>If an object such as a key is loaded successfully in a script but then seems to disappear, it is likely the interaction with the resource manager. The resource manager detects that the process (one line of the script) exits and then frees all allocated resources.</p>
<p>This occurs with a hardware TPM - always on Windows and with Linux when connecting to /dev/tpmrm0. It will not occur when connecting directly with a software TPM or a hardware TPM at /dev/tpm0, which bypasses the resource manager. It will also not occur once the prototyping script is replaced by an executable that does not close the connection after each TPM command.</p>
<p>The solution is to use a proxy, which keeps the TPM connection alive. See section 4.7 Connecting to Resource Managers.</p>