<!-- 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: Signing and Verification Tutorial</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('_sign_verify_tutorial.html','');});
/* @license-end */
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Signing and Verification Tutorial </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#tutorial_signmmsgOverview">Creating an Intel® EPID Signature of a Given Message</a><ul><li class="level2"><a href="#tutorial_signmsgList">What Do You Need to Create a Signature?</a></li>
<li class="level2"><a href="#tutorial_signmsgExample">Signing Example</a></li>
</ul>
</li>
<li class="level1"><a href="#tutorial_verifysigOverview">Verifying an Intel® EPID Signature</a><ul><li class="level2"><a href="#tutorial_verifyList">What Do You Need to Verify a Signature?</a></li>
<li class="level2"><a href="#tutorial_verifyExample">Verification Example</a></li>
</ul>
</li>
<li class="level1"><a href="#SignVerifyTutorial_requirements">Parameter Matching Requirements</a><ul><li class="level2"><a href="#SignVerifyTutorial_message">Message</a></li>
<li class="level2"><a href="#SignVerifyTutorial_hashalg">Hash Algorithm</a></li>
<li class="level2"><a href="#SignVerifyTutorial_SigRL">Signature Revocation List</a></li>
<li class="level2"><a href="#SignVerifyTutorial_basenames">Basenames</a></li>
</ul>
</li>
<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>
<li class="level2"><a href="#SignVerifyTutorial_KeyRevocation">Detecting Revoked Member from Private Key Based Revocation List</a></li>
<li class="level2"><a href="#SignVerifyTutorial_SigRevocation">Detecting Revoked Member from Signature Based Revocation List</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>The Intel® EPID SDK provides example tools to show you how to use the Intel® EPID SDK APIs. These examples are called <code>signmsg</code> and <code>verifysig</code>.</p>
<p>These examples use the pre-generated data described in <a class="el" href="_issuer_material.html">Test Data</a>. After you build the SDK, the data is in the <code>_install/epid-sdk/example/data</code> directory. If you don't have genuine issuer material, you can use this data for validation purposes.</p>
<p>You can follow along with the commands used in this tutorial if you first build these examples using the instructions in <a class="el" href="_building_sdk.html">Building from Source</a>. The tutorial assumes <code>_install/epid-sdk/example</code> is the current directory.</p>
<p>All command lines in this tutorial use posix command line conventions; for other systems, adjust accordingly.</p>
<p>For detailed walkthroughs of the code used in <code>signmsg</code> and <code>verifysig</code>, refer to <a class="el" href="_examples.html">Walkthroughs of Examples Showing API Usage</a>.</p>
<h1><a class="anchor" id="tutorial_signmmsgOverview"></a>
Creating an Intel® EPID Signature of a Given Message</h1>
<p>The example application <code>signmsg</code> shows you how to create an Intel® EPID signature of a given message.</p>
<h2><a class="anchor" id="tutorial_signmsgList"></a>
What Do You Need to Create a Signature?</h2>
<p>To generate a signature, you need the following items:</p>
<ul>
<li><b>Group public key:</b> You need the group public key to specify which group the member belongs to.</li>
<li><b>Member private key:</b> You need the member private key so that the member can create a signature that corresponds with the group public key.</li>
<li><b>Message:</b> You need the message because the member needs something to sign.</li>
<li><b>Hash algorithm:</b> You need the hash algorithm to encrypt the signature. If you don't specify a hash algorithm, a default hash algorithm is used.</li>
<li><b>Signature based revocation list (SigRL):</b> You need the SigRL so that the member can create non-revoked proofs for each entry on the list. For more information, see <a class="el" href="_revocation.html">In-Depth Explanation of Revocation</a>.</li>
<li><b>Member precomputation blob:</b> The precomputation blob is an optional parameter that you can use to improve performance when generating signatures repeatedly with the same member private key.</li>
<li><b>Basename:</b> A basename is a parameter that is only provided when the member is generating a name based signature. If no basename is specified, a random value is chosen as the basename. For more information, see <a class="el" href="_basenames.html">In-Depth Explanation of Basenames</a>.</li>
<li><b>Random number generator:</b> You need a cryptographically secure random number generator to ensure that signatures generated by the same member with the same message are different. The SDK provides the <a class="el" href="group___epid_common.html#ga6119a2c0323a3fca9e502b24bc378c2c" title="Generates random data. ">BitSupplier</a> function prototype that specifies the interface for your random number generator implementation.</li>
</ul>
<h2><a class="anchor" id="tutorial_signmsgExample"></a>
Signing Example</h2>
<p>The signmsg command can be passed a number of options: </p><pre class="fragment">$ ./signmsg -h
Usage: signmsg [OPTION]...
Verify signature was created by group member in good standing
Options:
--sig=FILE write signature to FILE (default: sig.dat)
--msg=MESSAGE MESSAGE to sign
--msgfile=FILE FILE containing message to sign
--bsn=BASENAME BASENAME to sign with (default: random)
--bsnfile=FILE FILE containing basename to sign with
--sigrl=FILE load signature based revocation list from FILE
--gpubkey=FILE load group public key from FILE (default: pubkey.bin)
--mprivkey=FILE load member private key from FILE (default: mprivkey.dat)
--mprecmpi=FILE load pre-computed member data from FILE
--capubkey=FILE load IoT Issuing CA public key from FILE (default: cacert.bin)
--hashalg={SHA-256 | SHA-384 | SHA-512 | SHA-512/256} use specified hash algorithm (default: SHA-512)
--help display this help and exit
-v, --verbose print status messages to stdout
</pre><p>To sign a message, a group member in good standing uses the following command: </p><pre class="fragment">$ ./signmsg --msg="test0"
</pre><p>The above command signs a message "test0". <code>signmsg</code> uses default options for the group public key, member private key, hash algorithm and IoT Issuing CA public key. All other parameters that are not given are ignored. The command produces a signature file: <code>sig.dat</code></p>
<h1><a class="anchor" id="tutorial_verifysigOverview"></a>
Verifying an Intel® EPID Signature</h1>
<p>The example application <code>verifysig</code> shows you how to verify that a given Intel® EPID signature is produced by a member in good standing.</p>
<h2><a class="anchor" id="tutorial_verifyList"></a>
What Do You Need to Verify a Signature?</h2>
<p>To verify a signature, you need the following items:</p>
<ul>
<li><b>Signature:</b> You need the signature that you want to verify.</li>
<li><b>CA certificate:</b> You need the CA certificate to verify the authenticity of the issuer material before you use it. Depending on how your issuer protects its data, you may not need a CA certificate. For more information on issuer material, refer to <a class="el" href="_provisioning.html">Preparing a Device</a> and <a class="el" href="_issuer_material.html">Test Data</a>.</li>
<li><b>Group certificate:</b> The group certificate comes from the issuer and contains the group public key. You need the group public key to determine if the signature came from a member of this group. The group public key corresponds to the member private key used to generate the signature.</li>
<li><b>Message:</b> In order for verification to succeed, you need to specify the message that was signed.</li>
<li><b>Hash algorithm:</b> In order for verification to succeed, you need to specify the hash algorithm that was used to sign the message. If you don't specify a hash algorithm, a default hash algorithm is used.</li>
<li><b>Group based revocation list (GroupRL):</b> You need the GroupRL to ensure the member does not belong to a revoked group. The GroupRL comes from the issuer.</li>
<li><b>Private key based revocation list (PrivRL):</b> You need the PrivRL to ensure that the member private key has not been revoked. The PrivRL comes from the issuer.</li>
<li><b>Signature based revocation list (SigRL):</b> You need to compare the SigRL with non-revoked proofs from the member to ensure that the member did not create any revoked signaures. The SigRL comes from the issuer.</li>
<li><b>Verifier revocation list:</b> The VerRL is optional. The verifier uses the VerRL to ensure that the member did not create any signatures that were revoked by the verifier. You can only use the VerRL if the signature is a name based signature. The VerRL comes from the verifier. For more information, refer to <a class="el" href="_revocation.html">In-Depth Explanation of Revocation</a> and <a class="el" href="_basenames.html">In-Depth Explanation of Basenames</a>.</li>
<li><b>Verifier precomputation blob:</b> The verifier precomputation blob is optional. You can use the precomputation blob to increase performance when verifying signatures repeatedly with the same group public key.</li>
<li><b>Basename:</b> A basename is a parameter that is only provided in instances where Intel® EPID uses name based signatures. If a basename is used, the member and verifier have to use the same basename. If a basename is not specified, a random number is chosen as the basename. Because name-based signatures decrease the member's privacy, they must only be used with the knowledge and consent of the member. For more information, refer to <a class="el" href="_basenames.html">In-Depth Explanation of Basenames</a>.</li>
<li><b>Precomputation blob:</b> You can optionally provide a precomputation blob to greatly speed up <a class="el" href="group___epid_verifier_module.html#ga1d116daaee5466a1485d26ebc4e3ab70" title="Creates a new verifier context. ">EpidVerifierCreate</a>. If you don't use one, the precomputation blob can be stored for use in a future session to verify membership in the same group using <a class="el" href="group___epid_verifier_module.html#ga92df4d00ea4ee59d7bfd35b23da03392" title="Serializes the pre-computed verifier settings. ">EpidVerifierWritePrecomp</a>.</li>
</ul>
<h2><a class="anchor" id="tutorial_verifyExample"></a>
Verification Example</h2>
<p>The verifysig command can be passed a number of options: </p><pre class="fragment">$ ./verifysig -h
Usage: verifysig [OPTION]...
Create Intel(R) EPID signature of message
Options:
--sig=FILE load signature from FILE (default: sig.dat)
--msg=MESSAGE MESSAGE that was signed (default: empty)
--msgfile=FILE FILE containing message that was signed
--bsn=BASENAME BASENAME used in signature (default: random)
--bsnfile=FILE FILE containing basename used in signature
--privrl=FILE load private key revocation list from FILE
--sigrl=FILE load signature based revocation list from FILE
--grprl=FILE load group revocation list from FILE (default: grprl.bin)
--verifierrl=FILE load verifier revocation list from FILE
--gpubkey=FILE load group public key from FILE (default: pubkey.bin)
--vprecmpi=FILE load pre-computed verifier data from FILE
--vprecmpo=FILE write pre-computed verifier data to FILE
--capubkey=FILE load IoT Issuing CA public key from FILE (default: cacert.bin)
--hashalg={SHA-256 | SHA-384 | SHA-512 | SHA-512/256} use specified hash algorithm for 2.0 groups (default: SHA-512)
--help display this help and exit
-v, --verbose print status messages to stdout
</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"
signature verified successfully
</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. The <code>verifysig</code> example uses default inputs for group public key, hash algorithm, and IoT Issuing CA public key. All other parameters are ignored. The output <code>verifysig: signature verified successfully</code> denotes that the verification is successful.</p>
<h1><a class="anchor" id="SignVerifyTutorial_requirements"></a>
Parameter Matching Requirements</h1>
<p>To successfully create and verify a signature, the member and verifier have to use the same message, hash algorithm, signature revocation list, and basename.</p>
<p>The signature verification process fails if there is a parameter mismatch between sign and verify operations. The mechanism for avoiding a parameter mismatch is outside the scope of the SDK.</p>
<h2><a class="anchor" id="SignVerifyTutorial_message"></a>
Message</h2>
<p>The member needs the message to generate the signature using the member private key. In order for verification to succeed, the verifier needs to use the same message that the member used.</p>
<p>This comparison allows the verifier to determine if the signature fulfills the verifier's basic expectations of what a signature from a valid member should look like, given the original message and the group public key.</p>
<p>Verification fails if the signing and verification operations don't use the same message: </p><pre class="fragment">$ ./signmsg --msg="test0"
$ ./verifysig --msg="test1"
verifysig: signature verification failed: invalid signature
</pre><h2><a class="anchor" id="SignVerifyTutorial_hashalg"></a>
Hash Algorithm</h2>
<p>The member needs to encrypt the signature with the hash algorithm. The verifier needs to use the same hash algorithm that the member used.</p>
<p>If you don't specify a hash algorithm, a default hash algorithm is used.</p>
<p>The Intel® EPID SDK supports the following hash algorithms: SHA-256, SHA-384, SHA-512.</p>
<p>Verification fails if the signing and verification operations don't use the same hash algorithm: </p><pre class="fragment">$ ./signmsg --msg="test0" --hashalg=SHA-256
$ ./verifysig --msg="test0" --hashalg=SHA-384
verifysig: signature verification failed: invalid signature
</pre><h2><a class="anchor" id="SignVerifyTutorial_SigRL"></a>
Signature Revocation List</h2>
<p>The member needs the signature based revocation list (SigRL) to create non-revoked proofs for each entry on the SigRL. The verifier needs to use the same SigRL to check the proofs.</p>
<p>Verification fails if the signing and verification operations don't use the same SigRL. </p><pre class="fragment">$ ./signmsg --msg="test0" --sigrl=data\groupa\sigrl.bin
$ ./verifysig --msg="test0" --sigrl=sigrl.bin
verifysig: signature verification failed: bad arguments
</pre><h2><a class="anchor" id="SignVerifyTutorial_basenames"></a>
Basenames</h2>
<p>For a verifier to be able to know that multiple signatures were generated by the same member, the verifier has to use the same basename that the member used for each name based signature. For more information, refer to <a class="el" href="_basenames.html">In-Depth Explanation of Basenames</a>.</p>
<p>If a basename is not provided to the member, then the member uses a random basename and the signature generated by the member is anonymous.</p>
<p>If a basename is not provided to the verifier, then the verifier does not check for a basename and it will verify the signature successfully without linking it to other signatures.</p>
<p>To sign message "test0" with a basename "base0": </p><pre class="fragment">$ ./signmsg --msg="test0" --bsn="base0"
</pre><p>To verify the signature: </p><pre class="fragment">$ ./verifysig --msg="test0" --bsn="base0"
verifysig: signature verified successfully
</pre><p>Verification fails if the signing and verification operations use different basenames: </p><pre class="fragment">$ ./signmsg --msg="test0" --bsn="base0"
$ ./verifysig --msg="test0" --bsn="base1"
verifysig: signature verification failed: invalid signature
</pre><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>
<h1><a class="anchor" id="SignVerifyTutorial_Revocation_Group"></a>
Revocation</h1>
<p>Revocation lists are data structures used by the verifier to identify members that are no longer approved members of the group.</p>
<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>
<h2><a class="anchor" id="SignVerifyTutorial_GroupRevocation"></a>
Detecting Revoked Group from Group Revocation List</h2>
<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>
<p>For example, </p><pre class="fragment">$ ./signmsg --msg="test0" --gpubkey=data/groupb/pubkey.bin --mprivkey=data/groupb/member0/mprivkey.dat
$ ./verifysig --msg="test0" --grprl=data/grprl.bin --gpubkey=data/groupb/pubkey.bin
verifysig: signature verification failed: signature revoked in GroupRl
</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>
<h2><a class="anchor" id="SignVerifyTutorial_KeyRevocation"></a>
Detecting Revoked Member from Private Key Based Revocation List</h2>
<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>
<p>For example, </p><pre class="fragment">$ ./signmsg --msg=test0 --gpubkey=data/groupa/pubkey.bin --mprivkey=data/groupa/privrevokedmember0/mprivkey.dat
$ ./verifysig --msg=test0 --privrl=data/groupa/privrl.bin --gpubkey=data/groupa/pubkey.bin
verifysig: signature verification failed: signature revoked in PrivRl
</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>
<h2><a class="anchor" id="SignVerifyTutorial_SigRevocation"></a>
Detecting Revoked Member from Signature Based Revocation List</h2>
<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
signmsg: signature revoked in SigRL
$ ./verifysig --msg="test1" --sigrl=data/groupa/sigrl.bin --gpubkey=data/groupa/pubkey.bin
verifysig: signature verification failed: signature revoked in SigRl
</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>
</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>