1<!-- HTML header for doxygen 1.8.10--> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4<head> 5<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 6<meta http-equiv="X-UA-Compatible" content="IE=9"/> 7<meta name="generator" content="Doxygen 1.8.14"/> 8<title>Intel® Enhanced Privacy ID SDK: Implementation Notes</title> 9<link href="tabs.css" rel="stylesheet" type="text/css"/> 10<script type="text/javascript" src="jquery.js"></script> 11<script type="text/javascript" src="dynsections.js"></script> 12<link href="navtree.css" rel="stylesheet" type="text/css"/> 13<script type="text/javascript" src="resize.js"></script> 14<script type="text/javascript" src="navtreedata.js"></script> 15<script type="text/javascript" src="navtree.js"></script> 16<script type="text/javascript"> 17/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 18 $(document).ready(initResizable); 19/* @license-end */</script> 20<link href="doxygen.css" rel="stylesheet" type="text/css" /> 21<link href="epidstyle.css" rel="stylesheet" type="text/css"/> 22</head> 23<body> 24<div id="top"><!-- do not remove this div, it is closed by doxygen! --> 25<div id="titlearea"> 26<table cellspacing="0" cellpadding="0"> 27 <tbody> 28 <tr style="height: 56px;"> 29 <td id="projectalign" style="padding-left: 0.5em;"> 30 <div id="projectname"><a 31 onclick="storeLink('index.html')" 32 id="projectlink" 33 class="index.html" 34 href="index.html">Intel® Enhanced Privacy ID SDK</a> 35 <span id="projectnumber">6.0.1</span> 36</div> 37 </td> 38 </tr> 39 </tbody> 40</table> 41</div> 42<!-- end header part --> 43<!-- Generated by Doxygen 1.8.14 --> 44</div><!-- top --> 45<div id="side-nav" class="ui-resizable side-nav-resizable"> 46 <div id="nav-tree"> 47 <div id="nav-tree-contents"> 48 <div id="nav-sync" class="sync"></div> 49 </div> 50 </div> 51 <div id="splitbar" style="-moz-user-select:none;" 52 class="ui-resizable-handle"> 53 </div> 54</div> 55<script type="text/javascript"> 56/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 57$(document).ready(function(){initNavTree('_implementation_notes.html','');}); 58/* @license-end */ 59</script> 60<div id="doc-content"> 61<div class="header"> 62 <div class="headertitle"> 63<div class="title">Implementation Notes </div> </div> 64</div><!--header--> 65<div class="contents"> 66<div class="toc"><h3>Table of Contents</h3> 67<ul><li class="level1"><a href="#implementationNotes_Members">Member Implementations</a></li> 68<li class="level1"><a href="#ImplementationNotes_Prng">Random Number Generation</a></li> 69<li class="level1"><a href="#ImplementationNotes_ProtectingSecrets">Protecting Secrets</a></li> 70<li class="level1"><a href="#ImplementationNotes_MathPrimitives">Replacing Math Primitives</a></li> 71<li class="level1"><a href="#ImplementationNotes_SerializedTypes">Octstring/Buffer Types</a></li> 72<li class="level1"><a href="#ImplementationNotes_FlexibleArrays">Flexible Arrays</a></li> 73</ul> 74</div> 75<div class="textblock"><h1><a class="anchor" id="implementationNotes_Members"></a> 76Member Implementations</h1> 77<p>There are three member implementations. You can use a specific compilation option to select the implementation that will be used at compile time. The implementations are:</p> 78<ol type="1"> 79<li><b>Reference:</b> This default implementation gives guidance on partitioning member operations between highly sensitive ones that use the <code>f</code> value of the member private key, and less sensitive ones that can be performed in a host environment. To build in default mode, refer to <a class="el" href="_building_sdk.html">Building from Source</a>.</li> 80<li><b>TPM:</b> This TPM member implementation uses the TPM for signing by linking to the IBM TSS. To build in TPM mode, refer to <a class="el" href="_tpm_considerations.html#TpmConsiderations_BuildingTpmMode">Building the SDK in TPM Mode</a>.</li> 81<li><b>Tiny:</b> This tiny implementation builds the SDK with a substantially reduced code size. To build in tiny mode, refer to <a class="el" href="_building_sdk.html#BuildingSdk_Tiny">Optimizing for Code Size</a>.</li> 82</ol> 83<h1><a class="anchor" id="ImplementationNotes_Prng"></a> 84Random Number Generation</h1> 85<p>Some SDK APIs require a random number data source. A <a class="el" href="group___epid_common.html#ga6119a2c0323a3fca9e502b24bc378c2c" title="Generates random data. ">BitSupplier</a> provides a source of random data. This function should be a cryptographically secure random number generator.</p> 86<dl class="section warning"><dt>Warning</dt><dd>The pseudo-random number generator provided with the examples is for sample use only and is not suitable for cryptographically secure applications.</dd></dl> 87<h1><a class="anchor" id="ImplementationNotes_ProtectingSecrets"></a> 88Protecting Secrets</h1> 89<p>Member code works with private keys, so member code must be run in a trusted environment. The member component contains a TPM subcomponent which contains the most sensitive operations performed by the member.</p> 90<dl class="section warning"><dt>Warning</dt><dd>If member memory is available to an untrusted source, the member private key could be exposed.</dd></dl> 91<p>The <code>EpidZeroMemory</code> function is used by the memory allocation routines <code>EpidAlloc</code>, <code>EpidRealloc</code> and <code>EpidFree</code> to wipe the memory as memory is freed.</p> 92<dl class="section warning"><dt>Warning</dt><dd>The <code>EpidZeroMemory</code> function may be optimized away by some compilers. If it is, you should consider using a compiler or operating system specific memory sanitization function (e.g. <code>memcpy_s</code> or <code>SecureZeroMemory</code>).</dd></dl> 93<h1><a class="anchor" id="ImplementationNotes_MathPrimitives"></a> 94Replacing Math Primitives</h1> 95<p>SDK math primitives are designed to be replaced with your own implementation if you need to rely on custom hardware for performance. The SDK is designed to simplify this process by isolating implementation details behind a clearly defined interface, defined by the non-internal headers in the <code>epid/common/math</code> directory. Math functionality has detailed tests to ease validation.</p> 96<h1><a class="anchor" id="ImplementationNotes_SerializedTypes"></a> 97Octstring/Buffer Types</h1> 98<p>Serialized information in the SDK is passed in fixed size buffer types whenever possible. Collectively these fixed size buffer types are called Octstrings.</p> 99<p>In <a class="el" href="types_8h.html" title="SDK data types. ">epid/common/types.h</a>, there are a large number of packed structs that contain other packed structs, which eventually contain OctStr* types. Normally these are named *Str and are refered to as Str types.</p> 100<p>OctStr* types are buffers that hold N bits, where N is the number at the end of the type name. These types usually represent numbers in a Big Endian format (buffer[0] is the most significant value).</p> 101<p>Str types generally represent fixed size groups of numbers such as a point or vector.</p> 102<p>OctStr* and Str types are usually populated by reading a buffer from a file or other storage, or by calling a serialize function. OctStr* and Str types must be packed so that the compiler does not insert padding. In the current code, this is done using pragmas.</p> 103<div class="fragment"><div class="line"><span class="preprocessor">#pragma pack(1)</span></div><div class="line"></div><div class="line"><span class="comment">// OctStr* type holding 256 bits</span></div><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct_oct_str256.html">OctStr256</a> {</div><div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> <a class="code" href="struct_oct_str256.html#a359781bb84f5717a16094583a00ef14e">data</a>[256 / CHAR_BIT]; </div><div class="line">} <a class="code" href="struct_oct_str256.html">OctStr256</a>;</div><div class="line"></div><div class="line"><span class="comment">// Str type consisting of a single 256 bit number</span></div><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct_fq_elem_str.html">FqElemStr</a> {</div><div class="line"> <a class="code" href="struct_oct_str256.html">OctStr256</a> <a class="code" href="struct_fq_elem_str.html#aac1a876b51a8d2c6d1510e4df2fd3f14">data</a>; </div><div class="line">} <a class="code" href="struct_fq_elem_str.html">FqElemStr</a>;</div><div class="line"></div><div class="line"><span class="comment">// Str type consisting of a two other Str types</span></div><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct_g1_elem_str.html">G1ElemStr</a> {</div><div class="line"> <a class="code" href="struct_fq_elem_str.html">FqElemStr</a> <a class="code" href="struct_g1_elem_str.html#a3b0e658d6e5697763ad9c633c11d4ec4">x</a>; </div><div class="line"> <a class="code" href="struct_fq_elem_str.html">FqElemStr</a> <a class="code" href="struct_g1_elem_str.html#a8f2455ca314e885ea180dadf84bf27c3">y</a>; </div><div class="line">} <a class="code" href="struct_g1_elem_str.html">G1ElemStr</a>;</div></div><!-- fragment --><p>Many APIs use void* parameters where OctStr* types are expected. If more than one size is allowed, a size parameter is usually also required.</p> 104<h1><a class="anchor" id="ImplementationNotes_FlexibleArrays"></a> 105Flexible Arrays</h1> 106<p>A common idiom in the SDK is the use of flexible array types. These types are structs with the last element being an array of size 1 of some type. Flexible array types always have a size value embedded in the struct. The name of the count and array fields differs between flexible array types.</p> 107<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>Sample {</div><div class="line"> <a class="code" href="struct_oct_str32.html">OctStr32</a> data; </div><div class="line"> <a class="code" href="struct_oct_str32.html">OctStr32</a> count; </div><div class="line"> <a class="code" href="struct_g1_elem_str.html">G1ElemStr</a> array[1]; </div><div class="line">} Sample;</div></div><!-- fragment --><p>Flexible array types are expected to be in a buffer of size <code>sizeof(FA) + ((N-1) * sizeof(E))</code> where FA is the flexible array type, N is the number of elements in the array and E is the type of each element. Note that this may be smaller than <code>sizeof(FA)</code> if N is 0, in which case referencing any element is an error.</p> 108<div class="fragment"><div class="line">Sample* AllocSample(<span class="keywordtype">size_t</span> count) {</div><div class="line"> <span class="keywordflow">return</span> (Sample*)malloc(<span class="keyword">sizeof</span>(Sample)</div><div class="line"> + (count * <span class="keyword">sizeof</span>(<a class="code" href="struct_g1_elem_str.html">G1ElemStr</a>))</div><div class="line"> - <span class="keyword">sizeof</span>(<a class="code" href="struct_g1_elem_str.html">G1ElemStr</a>));</div><div class="line">}</div></div><!-- fragment --><p>In many cases, functions that accept flexible array types will also expect a buffer size that is compared against the computed size of the array as a sanity check.</p> 109<p>*Other names and brands may be claimed as the property of others. </p> 110</div></div><!-- contents --> 111</div><!-- doc-content --> 112<!-- HTML footer for doxygen 1.8.10--> 113<!-- start footer part --> 114<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> 115 <ul> 116 <li class="footer"> 117 © 2016-2017 Intel Corporation 118 </li> 119 </ul> 120</div> 121</body> 122</html> 123