| <!-- HTML header for doxygen 1.8.10--> |
| <!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.14"/> |
| <title>Intel® Enhanced Privacy ID SDK: Considerations for TPM</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"> |
| /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ |
| $(document).ready(initResizable); |
| /* @license-end */</script> |
| <link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| <link href="epidstyle.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"><a |
| onclick="storeLink('index.html')" |
| id="projectlink" |
| class="index.html" |
| href="index.html">Intel® Enhanced Privacy ID SDK</a> |
|  <span id="projectnumber">6.0.1</span> |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <!-- end header part --> |
| <!-- Generated by Doxygen 1.8.14 --> |
| </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"> |
| /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ |
| $(document).ready(function(){initNavTree('_tpm_considerations.html','');}); |
| /* @license-end */ |
| </script> |
| <div id="doc-content"> |
| <div class="header"> |
| <div class="headertitle"> |
| <div class="title">Considerations for TPM </div> </div> |
| </div><!--header--> |
| <div class="contents"> |
| <div class="toc"><h3>Table of Contents</h3> |
| <ul><li class="level1"><a href="#TPM_compatibility">Compatibility</a></li> |
| <li class="level1"><a href="#TpmConsiderations_Manufacturers">Considerations for TPM Manufacturers</a><ul><li class="level2"><a href="#TPM_provisioning">Provisioning TPM with Intel® EPID Key Material</a></li> |
| <li class="level2"><a href="#TpmConsiderations_Mapping">Mapping TPM Commands to Intel® EPID</a></li> |
| </ul> |
| </li> |
| <li class="level1"><a href="#TpmConsiderations_Applications">Considerations for TPM Applications</a></li> |
| <li class="level1"><a href="#TpmConsiderations_Architecture">SDK Member Architecture</a></li> |
| <li class="level1"><a href="#TpmConsiderations_Building">Building the SDK to Take Advantage of TPM</a><ul><li class="level2"><a href="#TpmConsiderations_Prereqs">Prerequisites to Build the SDK in TPM Mode</a></li> |
| <li class="level2"><a href="#TpmConsiderations_BuildingTpmMode">Building the SDK in TPM Mode</a></li> |
| <li class="level2"><a href="#TpmConsiderations_Signing">Intel® EPID Signing and Verification with a TPM</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <div class="textblock"><p>Intel® EPID is compatible with TPM (Trusted Platform Modules) and is designed to take advantage of the security features of TPM. This section describes integrating a TPM device and Intel® EPID functionality.</p> |
| <p>Intel® EPID is a technology for securely and anonymously identifying a device, and TPM is a technology for protecting secrets on a device. Therefore it is desirable to protect the most secret part of the member private key on an Intel® EPID TPM device.</p> |
| <h1><a class="anchor" id="TPM_compatibility"></a> |
| Compatibility</h1> |
| <p>The SDK is compatible with the Trusted Computing Group's TPM 2.0 spec. The most recent version of the TPM 2.0 specification (Level 00, Revision 01.38) includes the use of a nonce, which is incompatible with the current version of the Intel® EPID scheme. Therefore, this implementation of Intel® EPID APIs is compatible with an earlier version, which is the TPM 2.0 specification Level 00, Revision 1.16.</p> |
| <h1><a class="anchor" id="TpmConsiderations_Manufacturers"></a> |
| Considerations for TPM Manufacturers</h1> |
| <p>This section explains what manufacturers have to do with the SDK in order to have their TPMs recognized to a service provider:</p> |
| <ul> |
| <li>Provisioning TPM devices with crypto secrets</li> |
| <li>Adapting SDK code to specific TSS functionality</li> |
| </ul> |
| <p>This SDK was tested on the IBM TPM and TSS (Trusted Computing Group Software Stack). Device manufacturers should replace specific items with their own TPM functionality.</p> |
| <h2><a class="anchor" id="TPM_provisioning"></a> |
| Provisioning TPM with Intel® EPID Key Material</h2> |
| <p>For TPM use with Intel® EPID, members and verifiers need to be provisioned with crypto material to enable security function.</p> |
| <p>In order to ensure that the <code>f</code> value only exists in the volatile memory of the TPM, TPM manufacturers need to provision the TPM with an EPS (Endorsement Primary Seed), from which the <code>f</code> value of the member private key is derived.</p> |
| <p>Typically, bulk provisioning is more efficient than dynamic provisioning in a manufacturing environment. However, bulk provisioning is not viable for TPM devices for the following reasons:</p> |
| <ul> |
| <li>In bulk provisioning, the issuer provides <code>f</code> as part of each member private key, but it is intentionally difficult to derive EPS from <code>f</code>.</li> |
| <li>The issuer cannot provide EPS to manufacturers because the translation from EPS to <code>f</code> is dependent upon an implementation specific, deterministic random number generator.</li> |
| </ul> |
| <p>Therefore, in order to provision the TPM with EPS, Intel supports a variation on typical <a class="el" href="_provisioning.html#Provisioning_JoinProvisioning">dynamic provisioning</a> in which manufacturers provide their own EPS.</p> |
| <p>In this variation on dynamic provisioning, which we call <b>bulk-join</b>, some steps are performed in bulk and credentials for many devices can be generated at the same time. This process allows TPM devices to be provisioned during manufacturing.</p> |
| <p>For bulk-join, TPM device manufacturers need to do the following:</p> |
| <ol type="1"> |
| <li><b>Generate a set of EPS</b>, because EPS are the seeds from which the <code>f</code> values of the member private keys are generated.</li> |
| <li><b>Derive a set of <code>f</code> values</b> from the EPS values.</li> |
| <li><b>Request a set of nonces from the issuer</b> which will be used to generate join requests.</li> |
| <li><b>Generate a set of join requests</b> using the <code>f</code> values and nonces and send them to the issuer. The issuer will respond to the bulk join requests by sending membership credentials to the manufacturer in bulk.</li> |
| <li><b>Provision the membership credentials in silicon,</b> mapping each membership credential to the corresponding EPS value.</li> |
| </ol> |
| <p>The following graphic shows how the issuer, manufacturer, TPM, and member interact during the time of key generation, device manufacturing, and signing:</p> |
| <div class="image"> |
| <img src="uml_sequence.png" alt="uml_sequence.png"/> |
| </div> |
| <h2><a class="anchor" id="TpmConsiderations_Mapping"></a> |
| Mapping TPM Commands to Intel® EPID</h2> |
| <p>APIs</p> |
| <p>The <code>tpm2</code> module in the <code>member</code> section of the API reference contains internal functions that map to TPM commands. This code is provided as sample code for manufacturers who will use it to write their own implementation of Intel® EPID APIs for TPM.</p> |
| <table class="markdownTable"> |
| <tr class="markdownTableHead"> |
| <th class="markdownTableHeadNone">Intel® EPID Function </th><th class="markdownTableHeadNone">Corresponding TPM 2.0 Command </th></tr> |
| <tr class="markdownTableBody" class="markdownTableRowOdd"> |
| <td class="markdownTableBodyNone">Tpm2Commit </td><td class="markdownTableBodyNone">TPM2_Commit </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowEven"> |
| <td class="markdownTableBodyNone">Tpm2CreateContext </td><td class="markdownTableBodyNone">N/A </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowOdd"> |
| <td class="markdownTableBodyNone">Tpm2DeleteContext </td><td class="markdownTableBodyNone">N/A </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowEven"> |
| <td class="markdownTableBodyNone">Tpm2GetRandom </td><td class="markdownTableBodyNone">TPM2_GetRandom </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowOdd"> |
| <td class="markdownTableBodyNone">Tpm2LoadExternal </td><td class="markdownTableBodyNone">TPM2_LoadExternal </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowEven"> |
| <td class="markdownTableBodyNone">Tpm2NvDefineSpace </td><td class="markdownTableBodyNone">TPM2_NV_DefineSpace </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowOdd"> |
| <td class="markdownTableBodyNone">Tpm2NvUndefineSpace </td><td class="markdownTableBodyNone">TPM2_NV_UndefineSpace </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowEven"> |
| <td class="markdownTableBodyNone">Tpm2NvWrite </td><td class="markdownTableBodyNone">TPM2_NV_Write </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowOdd"> |
| <td class="markdownTableBodyNone">Tpm2NvRead </td><td class="markdownTableBodyNone">TPM2_NV_Read </td></tr> |
| <tr class="markdownTableBody" class="markdownTableRowEven"> |
| <td class="markdownTableBodyNone">Tpm2Sign </td><td class="markdownTableBodyNone">TPM2_Sign </td></tr> |
| </table> |
| <h1><a class="anchor" id="TpmConsiderations_Applications"></a> |
| Considerations for TPM Applications</h1> |
| <p>Unlike non-TPM device manufacturers, TPM manufacturers cannot use <a class="el" href="group___epid_member_module.html#ga07094399c1e040b95ae3e58a74e7c302" title="Provisions a member context from a private key. ">EpidProvisionKey</a>. TPMs are designed to protect secret values from access even by the programs that use them. Dynamic provisioning is specifically designed to allow this use case.</p> |
| <p>To get a TPM device running, TPM applications can use the following steps to join a group using a TPM protected secret:</p> |
| <ol type="1"> |
| <li>Use <a class="el" href="group___epid_member_module.html#ga2b3c0cc1d8d4e50190ca94656fa36e24" title="Computes the size in bytes required for a member context. ">EpidMemberGetSize</a> and <a class="el" href="group___epid_member_module.html#ga35273b8e75d51e312f0d2fd3aa094efb" title="Initializes a new member context. ">EpidMemberInit</a> to create a new member context. Those functions take the parameter <a class="el" href="struct_member_params.html" title="Software only specific member parameters. ">MemberParams</a>. You will pass NULL to this struct instead of the <code>f</code> value, which indicates that <code>f</code> needs to be derived from the EPS within the TPM.</li> |
| <li>Use <a class="el" href="group___epid_member_module.html#gac10008d8c9ba7bc5e5be899ed03c61c3" title="Creates a request to join a group. ">EpidCreateJoinRequest</a> to generate join requests using the <code>f</code> derived from EPS within the TPM. Then send the join request to the issuer to request a membership credential.</li> |
| <li>After receiving the membership credential (A, x), use <a class="el" href="group___epid_member_module.html#ga788ebc9d1ba6153c637b762484ca1140" title="Provisions a member context from a membership credential. ">EpidProvisionCredential</a> to provision it into the non-volatile memory of the TPM device.</li> |
| </ol> |
| <p>After the TPM device is provisioned with <a class="el" href="group___epid_member_module.html#ga788ebc9d1ba6153c637b762484ca1140" title="Provisions a member context from a membership credential. ">EpidProvisionCredential</a>, the simplest way to get the device running is:</p> |
| <ol type="1"> |
| <li><a class="el" href="group___epid_member_module.html#ga2b3c0cc1d8d4e50190ca94656fa36e24" title="Computes the size in bytes required for a member context. ">EpidMemberGetSize</a>,</li> |
| <li><a class="el" href="group___epid_member_module.html#ga35273b8e75d51e312f0d2fd3aa094efb" title="Initializes a new member context. ">EpidMemberInit</a>,</li> |
| <li><a class="el" href="group___epid_member_module.html#gaa2c85b1f0ea17a11ac5d297b21aa30f6" title="Change member from setup state to normal operation. ">EpidMemberStartup</a>, and</li> |
| <li><a class="el" href="group___epid_member_module.html#ga74d1409a816cb52633564b793072da5f" title="Writes an Intel(R) EPID signature. ">EpidSign</a>.</li> |
| </ol> |
| <h1><a class="anchor" id="TpmConsiderations_Architecture"></a> |
| SDK Member Architecture</h1> |
| <p>In the SDK, the Tpm2 module exposes commands that can be mapped to real TSS commands.</p> |
| <div class="image"> |
| <img src="member_host.png" alt="member_host.png"/> |
| </div> |
| <p>The <b>Member Host</b> (<code>member/src</code>) implements Intel® EPID signing in terms of TPM2 commands.</p> |
| <p>The <b>TPM module</b> (<code>member/tpm2</code>) implements TPM2 commands.</p> |
| <p>There are two implementations of TPM functionality:</p> |
| <ul> |
| <li><b>BM TSS dispatcher implementation</b> (<code>member/tpm2/ibm_tss</code>), which calls the IBM TSS, which calls the IBM TPM simulator (in this implementation). It is invoked when building in TPM mode.</li> |
| <li><b>TPM SDK software implementation</b> (<code>member/tpm2/src</code>) implements sufficient TPM functionality for Intel® EPID. It is invoked when building in non-TPM mode.</li> |
| </ul> |
| <h1><a class="anchor" id="TpmConsiderations_Building"></a> |
| Building the SDK to Take Advantage of TPM</h1> |
| <p>This section describes:</p> |
| <ul> |
| <li>Prerequisites to building the SDK to take advantage of TPM</li> |
| <li>Building the SDK in TPM mode</li> |
| <li>Running signing and verification operations with TPM</li> |
| </ul> |
| <h2><a class="anchor" id="TpmConsiderations_Prereqs"></a> |
| Prerequisites to Build the SDK in TPM Mode</h2> |
| <ol type="1"> |
| <li>Download <a href="https://sourceforge.net/projects/ibmtpm20tss/files/?source=navbar">IBM TSS</a> version <a href="https://sourceforge.net/projects/ibmtpm20tss/files/ibmtss996.tar.gz/download">966</a>. (The SDK was tested on version 966. Newer versions may also work, but we do not guarantee it.)</li> |
| <li>Download <a href="https://sourceforge.net/projects/ibmswtpm2/files/?source=navbar">IBM TPM</a> version <a href="https://sourceforge.net/projects/ibmswtpm2/files/ibmtpm532.tar/download">532</a>. (The SDK was tested on version 532 and does not work on newer versions.)</li> |
| <li>Build the IBM TSS in accordance with the build steps from the package. Copy <code>tss.lib</code> and <code>tss.dll</code> from <code>ibmtss\tpmutils\Release</code> to <code>ibmtss\utils</code>.</li> |
| </ol> |
| <h2><a class="anchor" id="TpmConsiderations_BuildingTpmMode"></a> |
| Building the SDK in TPM Mode</h2> |
| <p>Set the TSSROOT environment variable to the <code>..\ibmtss\utils\</code> folder. Make sure this folder contains the <code>\tss2</code> folder, <code>tss.lib</code> and <code>tss.dll</code>. Example of the command for Windows: </p><pre class="fragment">> set TSSROOT=C:\ibmtss\utils\ |
| </pre><p>To build the SDK in TPM mode, go to the SDK folder and build the SDK with the following command: </p><pre class="fragment">> scons --target=x86 --use-tss |
| </pre><p><br /> |
| </p> |
| <p>To build the SDK in TPM mode using <code>make</code> command, go to the SDK folder and build the SDK with the following commands: </p><pre class="fragment">> ./configure CFLAGS=-m32 --with-tss |
| > make all |
| > make utest |
| > make install |
| </pre><p>Because the IBM TSS only supports x86 targets, you must build in x86.</p> |
| <h2><a class="anchor" id="TpmConsiderations_Signing"></a> |
| Intel® EPID Signing and Verification with a TPM</h2> |
| <ol type="1"> |
| <li>Build the IBM TSS (see above).</li> |
| <li>Build the IBM TPM (see above).</li> |
| <li>Build the Intel® EPID SDK with <code>--target=86 --use-tss</code> (see above).</li> |
| <li>Copy <code>tss.dll</code> from <code>_install/epid-sdk/test</code> to <code>_install/epid-sdk/example</code>.</li> |
| <li>Go to the <code>ibmtpm</code> folder and run the <code>tpm_server</code> executable. Note: if you built the TPM server with the MS Visual Studio debug mode, go to the <code>..\ibmtpm\tpmvstudio\tpm_server\Debug\</code> folder.</li> |
| <li>You need to run both the TPM server and the <code>powerup</code> and <code>startup</code> executables on IBM TSS. Go to <code>..\ibmtss\tpmutils\Debug\</code> or <code>..\ibmtss\tpmutils\Release\</code> and run <code>powerup</code> and <code>startup</code> executables.</li> |
| </ol> |
| <p>Then you can run:</p> |
| <pre class="fragment">> signmsg --hashalg=SHA-256 --msg="test" |
| </pre><dl class="section note"><dt>Note</dt><dd>In TPM mode samples have to be used with <code>--hashalg=SHA-256</code>.</dd></dl> |
| <p>If signing succeeds, nothing is returned.</p> |
| <p>Then run:</p> |
| <pre class="fragment">> verifysig --hashalg=SHA-256 --msg="test" |
| -signature verified successfully |
| </pre><dl class="section warning"><dt>Warning</dt><dd>The samples use <code>LoadExternal</code> to load keys into the TPM. In a real TPM use case, <code>CreatePrimary</code> should be used, and the SDK implementation provides functions for this use case. </dd></dl> |
| </div></div><!-- contents --> |
| </div><!-- doc-content --> |
| <!-- HTML footer for doxygen 1.8.10--> |
| <!-- start footer part --> |
| <div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> |
| <ul> |
| <li class="footer"> |
| © 2016-2017 Intel Corporation |
| </li> |
| </ul> |
| </div> |
| </body> |
| </html> |
