SignVerifyTutorial.html 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192
  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.11"/>
  8. <title>Intel&reg; Enhanced Privacy ID SDK: Signing and Verification Tutorial</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. $(document).ready(initResizable);
  18. $(window).load(resizeHeight);
  19. </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&reg; Enhanced Privacy ID SDK</a>
  35. &#160;<span id="projectnumber">2.0.0</span>
  36. </div>
  37. </td>
  38. </tr>
  39. </tbody>
  40. </table>
  41. </div>
  42. <!-- end header part -->
  43. <!-- Generated by Doxygen 1.8.11 -->
  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. $(document).ready(function(){initNavTree('SignVerifyTutorial.html','');});
  57. </script>
  58. <div id="doc-content">
  59. <div class="header">
  60. <div class="headertitle">
  61. <div class="title">Signing and Verification Tutorial </div> </div>
  62. </div><!--header-->
  63. <div class="contents">
  64. <div class="toc"><h3>Table of Contents</h3>
  65. <ul><li class="level1"><a href="#SignVerifyTutorial_Signmmsg">Creating an Intel&reg; EPID Signature of a Given Message</a></li>
  66. <li class="level1"><a href="#SignVerifyTutorial_Verifysig">Verifying an Intel&reg; EPID Signature</a></li>
  67. <li class="level1"><a href="#SignVerifyTutorial_Basename">Linking Intel&reg; EPID Signatures from the Same Member</a></li>
  68. <li class="level1"><a href="#SignVerifyTutorial_VerificationFailures">Expected Failures</a></li>
  69. <li class="level1"><a href="#SignVerifyTutorial_Revocation_Group">Revocation</a><ul><li class="level2"><a href="#SignVerifyTutorial_GroupRevocation">Detecting Revoked Group from Group Revocation List</a></li>
  70. <li class="level2"><a href="#SignVerifyTutorial_KeyRevocation">Detecting Revoked Member from Private Key Based Revocation List</a></li>
  71. <li class="level2"><a href="#SignVerifyTutorial_SigRevocation">Detecting Revoked Member from Signature Based Revocation List</a></li>
  72. </ul>
  73. </li>
  74. </ul>
  75. </div>
  76. <div class="textblock"><p>The Intel&reg; EPID SDK provides example tools to show you how to use the Intel&reg; EPID SDK APIs. These examples are called <em>signmsg</em> and <em>verifysig</em>.</p>
  77. <p>You can build these examples using the instructions in <a class="el" href="BuildingSdk.html">Building From Source</a>. The tutorial assumes <code>_install/epid-sdk/example</code> is the current directory.</p>
  78. <p>All command lines in this tutorial use posix command line conventions; for other systems, adjust accordingly.</p>
  79. <p>For the code used in this tutorial, refer to <a href="examples.html"><b>Examples</b></a>.</p>
  80. <dl class="section note"><dt>Note</dt><dd>The data for running this tutorial is pre-generated. Once the samples are built, the data is in the <code>_install/epid-sdk/example/data</code> directory. See <a class="el" href="IssuerMaterial.html">Sample Issuer Material</a>.</dd></dl>
  81. <h1><a class="anchor" id="SignVerifyTutorial_Signmmsg"></a>
  82. Creating an Intel® EPID Signature of a Given Message</h1>
  83. <p>The example application <em>signmsg</em> shows you how to create an Intel&reg; EPID Signature of a given message. </p><pre class="fragment">$ ./signmsg -h
  84. Usage: signmsg [OPTION]...
  85. Create Intel(R) EPID signature of message
  86. Options:
  87. --sig=FILE write signature to FILE (default: sig.dat)
  88. --msg=MESSAGE MESSAGE to sign
  89. --bsn=BASENAME BASENAME to sign with (default: random)
  90. --sigrl=FILE load signature based revocation list from FILE
  91. --gpubkey=FILE load group public key from FILE
  92. (default: pubkey.bin)
  93. --mprivkey=FILE load member private key from FILE
  94. (default: mprivkey.dat)
  95. --mprecmpi=FILE load pre-computed member data from FILE
  96. --mprecmpo=FILE write pre-computed member data to FILE
  97. --hashalg=NAME SHA-256 | SHA-384 | SHA-512 (default: SHA-512)
  98. --capubkey=FILE load IoT Issuing CA public key from FILE
  99. (default: cacert.bin)
  100. -h,--help display this help and exit
  101. -v,--verbose print status messages to stdout
  102. </pre><p>To sign a message, a group member in good standing uses the following command: </p><pre class="fragment">$ ./signmsg --msg="test0"
  103. </pre><p>The above command signs a message "test0". <em>signmsg</em> uses default options for the group public key, member private key, and hash algorithm (SHA-512). All other parameters that are not given are ignored. The command produces a signature file: <code>sig.dat</code></p>
  104. <h1><a class="anchor" id="SignVerifyTutorial_Verifysig"></a>
  105. Verifying an Intel® EPID Signature</h1>
  106. <p>The example application <em>verifysig</em> shows you how to verify that a given Intel&reg; EPID Signature is produced by a member in good standing. </p><pre class="fragment">$ ./verifysig -h
  107. Usage: verifysig [OPTION]...
  108. Verify signature was created by group member in good standing
  109. Options:
  110. --sig=FILE load signature from FILE (default: sig.dat)
  111. --msg=MESSAGE MESSAGE that was signed (default: empty)
  112. --bsn=BASENAME BASENAME used in signature (default: random)
  113. --privrl=FILE load private key based revocation list from FILE
  114. --sigrl=FILE load signature based revocation list from FILE
  115. --grprl=FILE load group revocation list from FILE
  116. (default: grprl.bin)
  117. --verifierrl=FILE load verifier revocation list from FILE
  118. --gpubkey=FILE load group public key from FILE (default: pubkey.bin)
  119. --vprecmpi=FILE load pre-computed verifier data from FILE
  120. --vprecmpo=FILE write pre-computed verifier data to FILE
  121. --hashalg=NAME SHA-256 | SHA-384 | SHA-512 (default: SHA-512)
  122. --capubkey=FILE load IoT Issuing CA public key from FILE
  123. (default: cacert.bin)
  124. -h,--help display this help and exit
  125. -v,--verbose print status messages to stdout
  126. </pre><p>To verify that a signature is from a member in good standing, the verifier uses the following command: </p><pre class="fragment">$ ./verifysig --msg="test0"
  127. signature verified successfully
  128. </pre><p>This verifies that the default signature file <code>sig.dat</code> is generated for the message "test0" by a member in good standing. <em>verifysig</em> uses default inputs for group public key and hash algorithm (SHA-512). All other parameters are ignored. The output <code>verifysig: signature verified successfully</code> denotes that the verification is successful.</p>
  129. <h1><a class="anchor" id="SignVerifyTutorial_Basename"></a>
  130. Linking Intel® EPID Signatures from the Same Member</h1>
  131. <p>A name-based signature is a type of signature that gives the verifier the ability to link Intel&reg; EPID signatures from the same member, reducing the member's privacy.</p>
  132. <p>The verifier can ask the member to sign a message with a basename that the verifier chooses. If the member uses the name-based signature option (i.e., in cases where a basename is specified), then all the signatures created by the member using the same basename are linkable by the verifier.</p>
  133. <dl class="section warning"><dt>Warning</dt><dd>The use of a name-based signature creates a platform unique pseudonymous identifier. Because it reduces the member's privacy, the user should be notified when it is used and should have control over its use.</dd></dl>
  134. <p>A name-based signature is created using the additional parameter of a basename. If the member uses the same basename, the verifier can mathematically link signatures generated by the member, showing that the signatures are from the same member.</p>
  135. <p>If basename is not provided, then the member uses a random basename and the signature generated by the member is anonymous.</p>
  136. <p>To Sign message "test0" with a basename "base0": </p><pre class="fragment">$ ./signmsg --msg="test0" --bsn="base0"
  137. </pre><p>To verify the signature: </p><pre class="fragment">$ ./verifysig --msg="test0" --bsn="base0"
  138. verifysig: signature verified successfully
  139. </pre><h1><a class="anchor" id="SignVerifyTutorial_VerificationFailures"></a>
  140. Expected Failures</h1>
  141. <p>The signature verification process fails if there is a parameter mismatch between sign and verify operations. Here are some examples.</p>
  142. <p>Verification fails if there is a mismatch in the message: </p><pre class="fragment">$ ./signmsg --msg="test0"
  143. $ ./verifysig --msg="test1"
  144. verifysig: signature verification failed: invalid signature
  145. </pre><p>Verification fails if there is a mismatch in the basename: </p><pre class="fragment">$ ./signmsg --msg="test0" --bsn="base0"
  146. $ ./verifysig --msg="test0" --bsn="base1"
  147. verifysig: signature verification failed: invalid signature
  148. </pre><p>The Intel&reg; EPID SDK supports the following hash algorithms: SHA-256, SHA-384, SHA-512. The selected hash algorithm must be the same for both sign and verify. Mismatch in hash algorithm results in verification failure: </p><pre class="fragment">$ ./signmsg --msg="test0" --hashalg=SHA-256
  149. $ ./verifysig --msg="test0" --hashalg=SHA-384
  150. verifysig: signature verification failed: invalid signature
  151. </pre><h1><a class="anchor" id="SignVerifyTutorial_Revocation_Group"></a>
  152. Revocation</h1>
  153. <p>Revocation lists are data structures used by the verifier to identify members that are no longer approved members of the group.</p>
  154. <p>The verifier obtains the member private key based revocation list (PrivRL), signature based revocation list (SigRL), and group based revocation list (GroupRL) from the issuer. The verifier can also maintain its own verifier blacklist (VerifierRL).</p>
  155. <h2><a class="anchor" id="SignVerifyTutorial_GroupRevocation"></a>
  156. Detecting Revoked Group from Group Revocation List</h2>
  157. <p>Verification of a signature fails if it is generated by a member of a group that is revoked in the group revocation list.</p>
  158. <p>For example, </p><pre class="fragment">$ ./signmsg --msg="test0" --gpubkey=data/groupb/pubkey.bin --mprivkey=data/groupb/member0/mprivkey.dat
  159. $ ./verifysig --msg="test0" --grprl=data/grprl.bin --gpubkey=data/groupb/pubkey.bin
  160. verifysig: signature verification failed: signature revoked in GroupRl
  161. </pre><p>The verification fails because <b>groupb</b> is revoked and is an entry in the group revocation list (<code>grprl.bin</code>).</p>
  162. <h2><a class="anchor" id="SignVerifyTutorial_KeyRevocation"></a>
  163. Detecting Revoked Member from Private Key Based Revocation List</h2>
  164. <p>Verification of a signature fails if it is generated by a member whose private key is revoked in a private-key based revocation list.</p>
  165. <p>For example, </p><pre class="fragment">$ ./signmsg --msg=test0 --gpubkey=data/groupa/pubkey.bin --mprivkey=data/groupa/privrevokedmember0/mprivkey.dat
  166. $ ./verifysig --msg=test0 --privrl=data/groupa/privrl.bin --gpubkey=data/groupa/pubkey.bin
  167. verifysig: signature verification failed: signature revoked in PrivRl
  168. </pre><p>The verification fails because the private key of <b>privrevokedmember0</b> is revoked and is an entry in the private key based revocation list of <b>groupa</b> (<code>privrl.bin</code>).</p>
  169. <h2><a class="anchor" id="SignVerifyTutorial_SigRevocation"></a>
  170. Detecting Revoked Member from Signature Based Revocation List</h2>
  171. <p>Verification of a signature fails if it is generated by a member whose signature is revoked in a signature based revocation list. </p><pre class="fragment">$ ./signmsg --msg="test1" --sigrl=data/groupa/sigrl.bin --gpubkey=data/groupa/pubkey.bin --mprivkey=data/groupa/sigrevokedmember0/mprivkey.dat
  172. signmsg: signature revoked in SigRL
  173. $ ./verifysig --msg="test1" --sigrl=data/groupa/sigrl.bin --gpubkey=data/groupa/pubkey.bin
  174. verifysig: signature verification failed: signature revoked in SigRl
  175. </pre><p>The message "test1" is signed by <em>signmsg</em> with a warning <code>signmsg: signature revoked in SigRL</code>. This means that the signature of <b>sigrevokedmember0</b> is revoked in the signature based revocation list. The verification fails because the signature was generated by <b>sigrevokedmember0</b>, which is revoked and is an entry in the signature based revocation list of <b>groupa</b> (<code>sigrl.bin</code>). </p>
  176. </div></div><!-- contents -->
  177. </div><!-- doc-content -->
  178. <!-- HTML footer for doxygen 1.8.10-->
  179. <!-- start footer part -->
  180. <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  181. <ul>
  182. <li class="footer">
  183. &copy; 2016 Intel Corporation
  184. </li>
  185. </ul>
  186. </div>
  187. </body>
  188. </html>