From 1115c195cd60d5ab2b80c12d07e21663e5aa8030 Mon Sep 17 00:00:00 2001
From: "Li, Xun"
Intel(R) SGX Tools
New configurations specific to SGX technology. You may see the configurations for the project by clicking to the down arrow of button
usually found at the top of the Eclipse window:
New configurations specific to Intel(R) SGX technology. You may see the configurations for the project by clicking to the down arrow of button
usually found at the top of the Eclipse window:
|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
Epid 1.1 issuer material parsing utilities. +More...
+#include <stddef.h>#include "epid/common/1.1/types.h"#include "epid/common/errors.h"#include "epid/common/file_parser.h"+Functions | |
| EpidStatus | Epid11ParseGroupPubKeyFile (void const *buf, size_t len, EpidCaCertificate const *cert, Epid11GroupPubKey *pubkey) |
| Extracts group public key from buffer in issuer binary format. More... | |
| EpidStatus | Epid11ParsePrivRlFile (void const *buf, size_t len, EpidCaCertificate const *cert, Epid11PrivRl *rl, size_t *rl_len) |
| Extracts private key revocation list from buffer in issuer binary format. More... | |
| EpidStatus | Epid11ParseSigRlFile (void const *buf, size_t len, EpidCaCertificate const *cert, Epid11SigRl *rl, size_t *rl_len) |
| Extracts signature revocation list from buffer in issuer binary format. More... | |
| EpidStatus | Epid11ParseGroupRlFile (void const *buf, size_t len, EpidCaCertificate const *cert, Epid11GroupRl *rl, size_t *rl_len) |
| Extracts group revocation list from buffer in issuer binary format. More... | |
Epid 1.1 issuer material parsing utilities.
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
SDK data types for Intel(R) EPID 1.1. +More...
++Data Structures | |
| struct | OctStr80 |
| 80 bit octet string More... | |
| struct | OctStr600 |
| 600 bit octet string More... | |
| struct | OctStr768 |
| 768 bit octet string More... | |
| struct | Fq3ElemStr |
| Serialized Fq3 element. More... | |
| struct | Epid11G2ElemStr |
| Serialized Intel(R) EPID 1.1 G2 element. More... | |
| struct | Epid11GtElemStr |
| Serialized Intel(R) EPID 1.1 GT element. More... | |
| struct | Epid11Params |
| Intel(R) EPID 1.1 Parameters. More... | |
| struct | Epid11GroupPubKey |
| Intel(R) EPID 1.1 group public key. More... | |
| struct | Epid11BasicSignature |
| Intel(R) EPID 1.1 basic signature. More... | |
| struct | Epid11NrProof |
| Intel(R) EPID 1.1 non-revoked Proof. More... | |
| struct | Epid11Signature |
| Intel(R) EPID 1.1 Signature. More... | |
| struct | Epid11PrivRl |
| Intel(R) EPID 1.1 private-key based revocation list. More... | |
| struct | Epid11SigRlEntry |
| Intel(R) EPID 1.1 entry in SigRL (B,K) More... | |
| struct | Epid11SigRl |
| Intel(R) EPID 1.1 signature based revocation list. More... | |
| struct | Epid11GroupRl |
| Intel(R) EPID 1.1 group revocation list. More... | |
+Typedefs | |
| +typedef G1ElemStr | Epid11G1ElemStr |
| Serialized Intel(R) EPID 1.1 G1 element. | |
| +typedef G1ElemStr | Epid11G3ElemStr |
| Serialized Intel(R) EPID 1.1 G3 element. | |
| +typedef OctStr32 | Epid11GroupId |
| Intel(R) EPID 1.1 group ID. | |
SDK data types for Intel(R) EPID 1.1.
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
This in-depth explanation covers the use of basenames in the Intel® EPID scheme. It provides detail on name based signatures, random base signatures and how and when they are used.
+
+
By default, members sign using a random basename that is not shared with the verifier. This signing method is also referred to as signing using random base. Signing using random base provides the strongest privacy properties for the signer. If a member signs using random base, the signature generated by the member is anonymous.
+When the signer and verifier agree to use random base, the basename is chosen at random for each signature. Two signatures using a random base cannot be linked to the same signer.
+A name based signature is a type of signature that gives the verifier the ability to link Intel® EPID signatures from the same member, reducing the member's privacy. When using name based signatures, the signer and verifier agree on an explicit basename.
+The verifier can ask the member to sign a message with a basename that the verifier chooses. If the member agrees to use a name based signature, then all the signatures created by the member using the same basename are linkable by the verifier, reducing the member's privacy.
+Reasons why a verifier might require members to use a basename when signing include the following:
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
Building SDK code out of the box requires a number of tools. This section explains how to install the following tools:
+| Prerequisite | Download Link |
|---|---|
| Python | python 2.7.12 installers |
| SCons | scons-2.4.1.zip |
| Parts | parts-0.11.0.zip |
+
To verify that Python installed correctly, run:
> python --version +
+
After Python is installed, install SCons.
+> python setup.py install +
+ To verify that SCons installed correctly, run:
> scons --version +
+
After SCons is installed, install Parts.
+> python setup.py install +
+
|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
To use the SDK in a project, the code from the SDK must be included in that project. The easiest way to do this is to link to static libraries. The SDK comes with build scripts to build static libraries for common environments.
+Building SDK code out of the box requires a number of tools. This section lists the tools used to build the SDK.
+For more information on how to install these tools, refer to Guide to Installing Build Tools.
+| Prerequisite | Notes |
|---|---|
| A C/C++ compiler | Core code in C. Unit tests need C++11 support. |
| Python | Validated with v2.7.10 |
| SCons | Validated with v2.4.1 |
| Parts | 0.10.9.2 or later |
To use the SDK, you need to build it to generate libraries compatible with your build environment.
+To build based on the default SConstruct file in the root directory of the SDK, invoke scons with no arguments.
cd <path/to/sdk-root> +scons +
By default, this performs a 64 bit release build.
+Potentially useful command line options:
+| Option | Action |
|---|---|
--cfg=debug | Build in debug mode |
--cfg=release | Build in release mode |
--target=x86 | Target x86 |
--target=x86_64 | Target x86_64 |
--tc=cl | Use MSVC to compile (Microsoft®* C/C++ Optimizing Compiler) |
--tc=gcc | Use GCC to compile (GNU* Compiler Collection) |
--tc=icl,mstools | Use Intel® C++ compiler |
build:: | Build the SDK (does not build unit tests) |
utest:: | Build unit tests |
run_utest:: | Run unit tests (builds tests if needed) |
-c | Clean the build |
Built components appear in the _install directory of the SDK root.
You can build with the make command on platforms that support Make/Autoconf.
In the root directory of the SDK, run:
./configure +make all +make check +make install +
./configure sets up the default settings:
./configure CC=/opt/intel/bin/icc CXX=/opt/intel/bin/icpc./_install. You can specify the installation directory by using ./configure --prefix=/usr/local/epid_install-m32 and -m64. For example, ./configure CFLAGS=-m32make check is optional. It builds and runs the unit tests.
Alternatively, you can use make build as a shortcut to replace make all, make check, and make install.
To clean the build, run make clean.
To remove the install directory, run make uninstall.
For higher performance, you can use the commercial version of Cryptography for Intel® Integrated Performance Primitives, available at https://software.intel.com/articles/download-ipp-cryptography-libraries.
+To build the SDK using a commercial Intel® IPP installation, the IPPROOT environment variable must be properly configured to point to the IPP installation directory, as described in Setting Environment Variables* in the Intel® IPP User's Guide (PDF link).
Once the environment is configured, you can build using commercial IPP by specifying --use-commercial-ipp as a command line option.
The SDK includes several examples that show you different aspects of how the Intel® EPID scheme works. In the SDK build, these examples are located in _install/epid-sdk/example.
| Name | Description |
|---|---|
signmsg | Create Intel® EPID signature of message |
verifysig | Verify signature is from a group member in good standing |
It is relatively straightforward to port the SDK to your build system of choice. The following dependency diagram shows the relationship between components and the sources used to build them.
+
+
+
Other names and brands may be claimed as the property of others.
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
EpidNullPtrErr now return EpidBadArgErr instead.|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
To use the Intel® EPID APIs, you need to use the following items that are created by the issuer:
+If you want to use the Intel Key Generation Facility (iKGF) as the issuer, contact info@digital-cp.com to get started.
+If you choose to use iKGF as the issuer, you can take advantage of tools included in the SDK that are designed to make it easier for you to interact with iKGF by creating requests to update revocation lists and by extracting member private keys and group public keys from iKGF files.
+The Intel® EPID SDK includes tools to help you request additions to revocation lists managed by iKGF if you are using iKGF as the issuer.
+These tools are designed to create a revocation request in the format required by iKGF. In order to update a revocation list, the requests generated by these tools must be submitted to the issuer.
+To access the tools, go to _install/epid-sdk/tools in the SDK directory.
You need to build the SDK before you can use these tools. For more information, refer to Building from Source.
+The following tools are available:
+| Tool | Purpose |
|---|---|
revokegrp | Create group revocation request |
revokekey | Create member private key revocation request |
revokesig | Create signature revocation request |
The revokegrp tool adds a group to the revocation request file.
Usage: revokegrp [OPTION]... +Revoke Intel(R) EPID group + +Options: + --gpubkey=FILE + load group public key from FILE (default: pubkey.bin) + + --capubkey=FILE + load IoT Issuing CA public key from FILE + + --reason=NUM + revocation reason (default: 0) + + --req=FILE + append group revocation request to FILE (default: grprlreq.dat) + + -h, --help + display this help and exit + + -v, --verbose + print status messages to stdout +
The revokekey tool adds a member private key to the revocation request file.
Usage: revokekey [OPTION] +Revoke Intel(R) EPID private key + +Options: + --mprivkey=FILE + load private key to revoke from FILE (default: mprivkey.dat) + + --req=FILE + append private key revocation request to FILE (default: privreq.dat) + + -h, --help + display this help and exit + + -v,--verbose + print status messages to stdout + +The following options are only needed for compressed keys: + + --gpubkey=FILE + load group public key from FILE (default: pubkey.bin) + + --capubkey=FILE + load IoT Issuing CA public key from FILE +
The revokesig tool creates a request to add a signature to the revocation request file.
revokesig only accepts valid signatures for addition to the revocation request.
Usage: revokesig [OPTION]... +Revoke Intel(R) EPID signature + +Options: + --sig=FILE + load signature to revoke from FILE (default: sig.dat) + + --msg=MESSAGE + MESSAGE used to generate signature to revoke + + --msgfile=FILE + FILE containing message used to generate signature to revoke + + --gpubkey=FILE + load group public key from FILE (default: pubkey.bin) + + --capubkey=FILE + load IoT Issuing CA public key from FILE + + --req=FILE + append signature revocation request to FILE (default: sigrlreq.dat) + + -h, --help + display this help and exit + + -v, --verbose + print status messages to stdout +
The Intel® EPID SDK includes tools to help you extract individual keys from files provided by the Intel Key Generation Facility (iKGF) if you are using iKGF as the issuer.
+To access the tools, go to _install/epid-sdk/tools in the SDK directory.
You need to build the SDK before you can use these tools. For more information, refer to Building from Source.
+The following tools are available:
+| Tool | Purpose |
|---|---|
extractgrps | Extracts group public keys |
extractkeys | Extracts member private keys |
The extractgrps tool extracts group public keys from the input file to the current directory.
Usage: extractgrps [OPTION]... [FILE] [NUM] +Extract the first NUM group certs from FILE to current directory + +Options: + -h, --help + display this help and exit + + -v, --verbose + print status messages to stdout +
The extractkeys tool extracts member private keys from the input file to the current directory.
Usage: extractkeys [OPTION]... [FILE] [NUM] +Extract the first NUM private keys from FILE to current directory. + +Options: + -c, --compressed + extract compressed keys + + -h, --help + display this help and exit + + -v, --verbose + print status messages to stdout
|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
Intel® EPID is a cryptographic protocol which enables the remote authentication of a trusted platform whilst preserving the user's privacy.
+In the Intel® EPID scheme, there are three roles: issuers, members, and verifiers.
+The entities in these roles interact with each other in such a way that a member can prove to a verifier that it is a trusted member of a group without disclosing the identity of the member. Groups are created and managed by the issuer.
+
+The issuer is responsible for managing group membership. Issuer functionality is not included in the SDK.
+The issuer manages groups by doing the following:
+
+The member is the entity that attempts to anonymously prove its group membership to the verifier.
+
+The verifier checks an Intel(R) EPID signature to establish whether it was signed by an entity or device that is a member in good standing.
+The verifier acts on behalf of a party that needs to know it is communicating with a trusted device. Verifiers obtain group certificates and revocation lists from issuers and negotiate details of signature protocol with members.
+A verifier can do the following:
+
+An Intel® EPID group represents a set of trusted entities called members. Issuers create groups and manage group membership. For each group, the issuer creates a group public key simultaneously with the corresponding issuing private key. The issuer uses the issuing private key to create unique member private keys for each group member, and makes the group public key available to verifiers.
+All groups have the following:
+If a signature based revocation list or private key based revocation list does not exist, it is assumed to be empty.
+The Intel® EPID scheme works with three types of keys: the group public key, the issuing private key, and the member private key. A group public key corresponds to the unique member private keys that are part of the group. Member private keys are generated from the issuing private key.
+Additionally, in the Intel® EPID scheme, a private key can be revoked given a signature created by that key, even if the key itself is still unknown. Group membership can be revoked and entire groups can be revoked. For more information on revocation, refer to In-Depth Explanation of Revocation.
+The group public key is the key used by the verifier to confirm that a member belongs to a group in good standing. Each member private key in a group is associated with the group's public key.
+When a group is created, the group public key and the issuing private key are simultaneously generated by the issuer. The verifier obtains the group public key from the issuer.
+The issuing private key is the key used by the issuer to generate unique private keys for each member of a given group. For every group public key, there is a corresponding issuing private key. The issuing private key remains with the issuer and is kept private.
+The member private key is the key used by the member to digitally sign a message when attempting to prove to the verifier that the member belongs to the group and is in good standing.
+Unique member private keys are generated by the issuer for each member of a given group. The same group public key corresponds to each member private key in the group.
+Each Intel® EPID member uses its Intel® EPID private key to digitally sign a message. The resulting signature is called an Intel® EPID signature.
+The Intel® EPID verifier uses the group public key to verify the correctness of an Intel® EPID signature, i.e., to verify that the signature was indeed created by a member with a valid Intel® EPID private key.
+However, the Intel® EPID signature does not convey any information about which unique private key was used to create the signature.
+
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
Several example applications are included that demonstrate how to use the SDK APIs.
+| Example Application | Concept Demonstrated |
|---|---|
signmsg | Generating an Intel® EPID Signature |
verifysig | Verifying an Intel® EPID Signature |
|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
The CA (Certificate Authority) public key contains the ECDSA public key of the issuing CA. The verifier uses this key to authenticate that information provided by the issuer is genuine.
+Direct Anonymous Attestation (DAA) is a digital signature algorithm that supports anonymity by providing a group public verification key associated with many unique private signing keys. Intel® EPID enhances DAA by enabling a private key to be revoked given a signature created by that key, even if the key itself is still unknown.
+In elliptic curve cryptography, an elliptic curve is an algebraic structure used to create a function whose output is easy to compute, but whose input is difficult to compute given the output. Elliptic curve cryptography requires smaller keys compared to non-elliptic curve cryptography (based on Galois fields) to provide equivalent security.
+An elliptic curve point is a point along an elliptic curve. The security of elliptic curve cryptography depends on the ability to compute a point multiplication and the inability to compute the multiplicand given the original and product points.
+An Intel® EPID group represents a set of trusted entities called members.
+Issuers create groups and manage group membership. For each group, the issuer creates a group public key simultaneously with the corresponding issuing private key. The issuer uses the issuing private key to create unique member private keys for each group member, and makes the group public key available to verifiers.
+All groups have the following:
+If a signature based revocation list or private key based revocation list does not exist, it is assumed to be empty.
+The group certificate contains the group public key. The group certificate is created by the issuer and obtained by the verifier. When the issuer creates groups, it generates one issuing private key and one group certificate for each group.
+The group public key is the key used by the verifier to confirm that a member belongs to a group in good standing. Each member private key in a group is associated with the group's public key.
+When a group is created, the group public key and the issuing private key are simultaneously generated by the issuer. The verifier obtains the group public key from the issuer.
+Enhanced Privacy ID (Intel® EPID) is a cryptographic protocol for attestation of a trusted platform while preserving the user's privacy. Intel® EPID can be used as a foundational building block for a multitude of security solutions.
+An Intel® EPID signature is a type of digital signature that preserves anonymity of the signer, while still proving the signer is a member of a trusted group.
+The issuer is the entity in the Intel® EPID scheme that is responsible for managing group membership. Issuer APIs are not included in the SDK. An example of an issuer is the Intel Key Generation Facility. For sample issuer material, refer to Sample Issuer Material. For tools that can help you if you choose to use iKGF as your issuer, refer to If You Choose iKGF as Your Issuer.
+The issuer manages groups by doing the following:
+The issuing private key is the key used by the issuer to generate unique private keys for each member of a given group. For every group public key, there is a corresponding issuing private key. The issuing private key remains with the issuer and is kept private.
+The member is the entity that attempts to prove its group membership to the verifier. Members are authorized by the issuer as part of a group and each group member has a unique Intel® EPID private key. The member uses its member private key to sign a message to prove group membership without revealing its identity. An example of a member is a PC with an embedded Intel® EPID member private key.
+A name-based signature is a type of signature that gives the verifier the ability to link Intel® EPID signatures from the same member, reducing the member's privacy.
+A name-based signature is created using the additional parameter of a basename. If a basename is not specified, a random number is chosen as the 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.
+The member private key is the key used by the member to digitally sign a message when attempting to prove to the verifier that the member belongs to the group and is in good standing.
+Unique member private keys are generated by the issuer for each member of a given group. The same group public key corresponds to each member private key in the group.
+A non-revoked proof is part of an Intel® EPID signature that proves that the member is not a specific revoked entity in the signature based revocation list. The member provides the signature with a number of non-revoked proofs, one per revocation list entry, to prove to the verifier that the member does not correspond to any entry in the revocation list.
+Pairing is a mathematical operation that maps two elliptic curve groups to a third multiplicative group.
+Revocation lists are data structures used by the verifier to identify members that are no longer approved members of the group.
+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). Verifier blacklist revocation only works with name based signatures.
+The verifier is the entity that checks an Intel® EPID signature to establish whether it was signed by an entity or device that is a member in good standing.
+The verifier acts on behalf of a party that needs to know it is communicating with a trusted device. Verifiers obtain group certificates and revocation lists from issuers and negotiate details of signature protocol with members.
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
Some SDK APIs require a random number data source. A BitSupplier provides a source of random data. This function should be a cryptographically secure random number generator.
+Member code works with private keys, so member code must be run in a trusted environment.
+The EpidZeroMemory function is used by the memory allocation routines EpidAlloc, EpidRealloc and EpidFree to wipe the memory as memory is freed.
EpidZeroMemory 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. memcpy_s or SecureZeroMemory).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 epid/common/math directory. Math functionality has detailed tests to ease validation.
Serialized information in the SDK is passed in fixed size buffer types whenever possible. Collectively these fixed size buffer types are called Octstrings.
+In epid/common/types.h, 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.
+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).
+Str types generally represent fixed size groups of numbers such as a point or vector.
+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.
+Many APIs use void* parameters where OctStr* types are expected. If more than one size is allowed, a size parameter is usually also required.
+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.
+Flexible array types are expected to be in a buffer of size sizeof(FA) + ((N-1) * sizeof(E)) 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 sizeof(FA) if N is 0, in which case referencing any element is an error.
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.
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
The Intel® EPID SDK does not include issuer APIs. That means you cannot generate the following items for validation:
+For validation purposes, you can use pre-generated sample data. This sample issuer material includes sample groups and revocation lists.
+Sample compressed key material is not included in the package.
+Group A (groupa) contains eight group members and sample revocation lists:
+
| Group Member | Revocation Status |
|---|---|
| groupa/member0 | Non-revoked |
| groupa/member1 | Non-revoked |
| groupa/privrevokedmember0 | Revoked in PrivRL |
| groupa/privrevokedmember1 | Revoked in PrivRL |
| groupa/privrevokedmember2 | Revoked in PrivRL |
| groupa/sigrevokedmember0 | Revoked in SigRL |
| groupa/sigrevokedmember1 | Revoked in SigRL |
| groupa/sigrevokedmember2 | Revoked in SigRL |
+
| Description | Directory Location | Revoked Members |
|---|---|---|
| Private key based revocation list | groupa/privrl.bin | privrevokedmember0, + privrevokedmember1, + privrevokedmember2 |
| Signature based revocation list | groupa/sigrl.bin | sigrevokedmember0, + sigrevokedmember1, + sigrevokedmember2 |
| Empty private key based revocation list | groupa/privrl_empty.bin | None |
| Empty signature based revocation list | groupa/sigrl_empty.bin | None |
+
Group B (groupb) contains four group members and sample revocation lists:
+
| Group Member | Revocation Status |
|---|---|
| groupb/member0 | Non-revoked |
| groupb/member1 | Non-revoked |
| groupb/privrevokedmember0 | Revoked in PrivRL |
| groupb/sigrevokedmember0 | Revoked in SigRL |
+
| Description | Directory Location | Revoked Members |
|---|---|---|
| Private key based revocation list | groupb/privrl.bin | privrevokedmember0 |
| Signature based revocation list | groupb/sigrl.bin | sigrevokedmember0 |
| Empty private key based revocation list | groupb/privrl_empty.bin | None |
| Empty signature based revocation list | groupb/sigrl_empty.bin | None |
If an entire group is no longer valid, the issuer can revoke it using the group based revocation list. Two sample group based revocation lists are provided with the SDK.
+
+
| Group Based Revocation List | Description |
|---|---|
grprl_empty.bin | No entries |
grprl.bin | One entry in which groupb is revoked |
Sample Groups
+Intel® EPID SDK supports use of compressed member private keys. The groups described here use compressed compressed member private keys but structuarlly corospond to groups described above.
+Group A (groupa) contains eight group members and sample revocation lists:
+
| Group Member | Revocation Status |
|---|---|
| groupa/member0 | Non-revoked |
| groupa/member1 | Non-revoked |
| groupa/privrevokedmember0 | Revoked in PrivRL |
| groupa/privrevokedmember1 | Revoked in PrivRL |
| groupa/privrevokedmember2 | Revoked in PrivRL |
| groupa/sigrevokedmember0 | Revoked in SigRL |
| groupa/sigrevokedmember1 | Revoked in SigRL |
| groupa/sigrevokedmember2 | Revoked in SigRL |
+
| Description | Directory Location | Revoked Members |
|---|---|---|
| Private key based revocation list | groupa/privrl.bin | privrevokedmember0, + privrevokedmember1, + privrevokedmember2 |
| Signature based revocation list | groupa/sigrl.bin | sigrevokedmember0, + sigrevokedmember1, + sigrevokedmember2 |
| Empty private key based revocation list | groupa/privrl_empty.bin | None |
| Empty signature based revocation list | groupa/sigrl_empty.bin | None |
+
Group B (groupb) contains four group members and sample revocation lists:
+
| Group Member | Revocation Status |
|---|---|
| groupb/member0 | Non-revoked |
| groupb/member1 | Non-revoked |
| groupb/privrevokedmember0 | Revoked in PrivRL |
| groupb/sigrevokedmember0 | Revoked in SigRL |
+
| Description | Directory Location | Revoked Members |
|---|---|---|
| Private key based revocation list | groupb/privrl.bin | privrevokedmember0 |
| Signature based revocation list | groupb/sigrl.bin | sigrevokedmember0 |
| Empty private key based revocation list | groupb/privrl_empty.bin | None |
| Empty signature based revocation list | groupb/sigrl_empty.bin | None |
If an entire group is no longer valid, the issuer can revoke it using the group based revocation list. Two sample group based revocation lists are provided with the SDK.
+
+
| Group Based Revocation List | Description |
|---|---|
grprl_empty.bin | No entries |
grprl.bin | One entry in which groupb is revoked |
|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
+UNLESS OTHERWISE AGREED IN WRITING BY INTEL, THE INTEL PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR.
+Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.
+The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
+Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.
+Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or by visiting Intel's web site http://www.intel.com.
+Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and other countries.
+*Other names and brands may be claimed as the property of others.
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
This in-depth explanation covers the available options to revoke members in the Intel® EPID scheme. It also provides details on how and why each type of revocation is used.
+
+
The verifier only checks the revocation lists if the message was signed with a member private key that corresponds with the correct group public key.
+After concluding that the signer is a member of a group, the verifier proceeds to check for group based revocation, then member private key based revocation, then signature based revocation, then verifier blacklist revocation.
+If the group is revoked, the verifier stops and reports it.
+If the member private key is revoked, the verifier does not check the signature based revocation list.
+The verifier should periodically download the revocation lists (GroupRL, PrivRL, and SigRL) from the issuer and should use the latest revocation list during signature verification. The verifier should make sure that it gets the newest version of the revocation list during the update by checking RLver, the revocation list version number.
+The group based revocation list, also called the GroupRL, has a list of revoked groups.
+The issuer revokes the entire Intel® EPID group by revoking the group public key. This results in the revocation of all members of a group.
+Group revocation is expected to be a rare event and would only happen under limited criteria.
+Reasons to revoke a group might include:
+Private key based revocation is used to revoke a compromised member. For example, the issuer can revoke a member if the member private key is exposed. When a compromised member private key is identified, it needs to be communicated to the issuer so that the issuer can revoke the member private key.
+The issuer manages and publishes the member private key revocation list, also called the PrivRL, which contains member private keys that can no longer be used.
+Depending on the use case, these member private keys could belong to members whose identity was compromised. For example, if a member private key is exposed online, allowing group members to be impersonated, then the compromised member private key is known, and the issuer revokes the member private key.
+In signature based revocation, the issuer revokes a member based on the signature generated by the member. This revocation method is used when a member becomes subject to revocation criteria, but the issuer does not know the member's member private key.
+The issuer manages and publishes the signature based revocation list, also called SigRL.
+Entries in the SigRL cause signing to take longer for all members of the group. Therefore, when an issuer receives a signature revocation request, it first checks the signature against all entries in the private key based revocation list. If the signature was generated by a revoked private key, then it is not placed in the SigRL.
+For the same reason, if the issuer were requested to revoke a private key, and the current SigRL had entries that corresponded to that private key, then the issuer would remove those entries from the SigRL.
+The verifier and the member both use the SigRL managed by the issuer (the method of obtaining the SigRL is outside the scope of the SDK). The member sends the verifier an Intel® EPID signature that includes a number of non-revoked proofs that correspond to each revoked member in the SigRL.
+In other words, the member mathematically proves that it is not any of the members who created the entries on the SigRL. One proof of non-revocation is generated by the member per entry in the SigRL. A single proof indicates the member in question cannot be the one who generated that signature in the SigRL.
+For privacy, Intel® EPID signatures that are generated by the same member are unlinkable by default. This means that the verifier cannot recognize if two Intel® EPID signatures are from the same device. Therefore, multiple Intel® EPID signatures on the SigRL could be from the same member.
+Reasons for revoking a signature might include the following:
+Verifier blacklist revocation is similar to signature based revocation in that it can be used to revoke a member using only a signature from a compromised member. Unlike the procedure for the signature based revocation list, members do not have to create non-revoked proofs for each entry on the verifier blacklist. Instead, the verifier relies on the member to use a basename when creating the signature (in other words, to use a name based signature) in order to determine if the same member created any of the signatures on the verifier blacklist.
+For the verifier to determine that a member created an entry on the verifier blacklist, the member and verifier must use the same basename. The mechanism that allows them to agree on a basename is outside the scope of the SDK.
+For more information on basenames, refer to Name Based Signatures.
+The verifier adds a signature to a blacklist when the verifier does not want to trust the signer, but the verifier does not have enough reason to send a request to the issuer to revoke the member's signature.
+When the verifier tracks a member using a basename, and decides the member is not trustworthy, the verifier can add the member's signature to the verifier blacklist.
+Reasons a verifier might revoke a member based on its tracked signatures include the following:
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
The SDK is divided into logical components to separate responsibilities and create interfaces that you can re-implement using custom tools such as hardware accelerators.
+
+
+ The Intel® EPID SDK is divided into the following components:
Components in the SDK Core implement the features of Intel® EPID.
+| Component | Description |
|---|---|
| member | Library containing APIs needed to implement a member |
| verifier | Library containing APIs needed to implement a verifier |
| common | Library containing common types and functions |
| math | Math primitives used by member and verifier |
| IPP | A C-only non-optimized subset of Intel® IPP |
Examples show how to use the SDK APIs in working code.
+| Component | Description |
|---|---|
| signmsg | A sample program showing how to sign messages |
| verfifysig | A sample program showing how to verify signatures |
| util | Common utilities used by samples |
| Sample Issuer Material | Sample keys and revocation lists |
Tools implement utility code to interact with Intel® EPID related services such as the Intel® Key GenerationFacility (iKGF)".
+| Component | Description |
|---|---|
| extractgrps | A tool to extract groups from a bulk group file |
| extractkeys | A tool to extract member keys from a bulk key file |
| revokegrp | A tool to create a revocation request for a group |
| revokekey | A tool to create a revocation request for a member key |
| revokesig | A tool to create a revocation request from a signature |
The SDK comes with a number of other components that support building and validating the code.
+| Component | Description |
|---|---|
| gtest | gtest unit test framework |
| Build Scripts | Scripts to configure and build the SDK |
Math primitives are implemented in the math sub-component of common. The reference math primitive implementation is based on a non-optimized Vanilla C subset of the Intel® Performance Primitives. Math is designed so that you can replace its implementation to call custom hardware IP blocks or optimized libraries.
+In addition to the default Intel® EPID 2.0 APIs, the verifier component also includes APIs that allow verification of Intel® EPID 1.1 signatures.
+Billions of existing devices, including most Intel platforms manufactured since 2008, create signatures that need Intel® EPID 1.1 verification.
+For details on verifying Intel® EPID 1.1 signatures see EPID 1.1 support in the API Reference.
+The Intel® EPID SDK has two filesystem layouts: the Source Layout and the Install Layout.
+The Source Layout is what you find when you download the SDK and extract it to disk. This layout contains all of the files that you need to build the libraries, samples, tests, and data generated by the SDK.
+The Install Layout is the layout of files under the _install folder after you build the SDK.
The Source Layout is used by the build scripts in the Intel® EPID SDK to find components and files needed to create libraries and executables.
epid-sdk/ +|__ LICENSE.txt Distribution license +|__ NOTICE.txt Legal notices +|__ README.md Readme +|__ CHANGELOG.md Change log +|__ SConstruct Main build configuration +| +|__ doc/ +| |__ html/ HTML format documentation +| |__ index.html Entry point for HTML format documentation +| +|__ epid/ +| |__ common/ Source for Common +| |__ common-testhelper/ Source for unit test helper common helpers +| |__ member/ Source for Member +| |__ verifier/ Source for Verifier +| +|__ example/ +| |__ data/ Binary data used for testing and tutorials +| |__ compressed_data/ Compressed Member Key Binary data used for testing and tutorials +| |__ signmsg/ Source for message signing example +| |__ util/ Common utilities for examples +| |__ verifysig/ Source for signature validation signing example +| +|__ ext/ +| |__ gtest/ Third party gtest library +| |__ ipp/ IPP library +| +|__ parts-site/ Parts platform config scripts +| +|__ tools/ + |__ extractgrps/ Tool to extract groups + |__ extractkeys/ Tool to extract keys + |__ revokegrp/ Tool to create group revocation request + |__ revokekey/ Tool to create a member key revocation request + |__ revokesig/ Tool to create a signature based revocation + request +
The Install Layout contains the data developers need to develop and build their applications using the Intel® EPID SDK. Once built, the Install Layout has no dependency on the Source Layout, allowing developers to build the SDK once and reuse the built files in other locations or on other computers.
_install/ +|__ epid-sdk/ + |__ include/ C include header files for the SDK + |__ lib/ + | |__ <platform> Target specific static libraries for the SDK + | + |__example/ Sample applications and data + |__test/ Unit test executables (if unit tests built) + |__tools/ Tools
|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
The Intel® EPID SDK provides example tools to show you how to use the Intel® EPID SDK APIs. These examples are called signmsg and verifysig.
+You can build these examples using the instructions in Building from Source. The tutorial assumes _install/epid-sdk/example is the current directory.
All command lines in this tutorial use posix command line conventions; for other systems, adjust accordingly.
+For the code used in this tutorial, refer to Walkthroughs of Examples Showing API Usage.
+_install/epid-sdk/example/data directory. See Sample Issuer Material.The example application signmsg shows you how to create an Intel® EPID signature of a given message.
$ ./signmsg -h
+Usage: signmsg [OPTION]...
+Create Intel(R) EPID signature of message
+
+Options:
+ --sig=FILE
+ write signature to FILE (default: sig.dat)
+
+ --msg=MESSAGE
+ MESSAGE to sign
+
+ --bsn=BASENAME
+ BASENAME to sign with (default: random)
+
+ --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
+
+ --mprecmpo=FILE
+ write pre-computed member data to FILE
+
+ --capubkey=FILE
+ load IoT Issuing CA public key from FILE (default: cacert.bin)
+
+ --hashalg={SHA-256 | SHA-384 | SHA-512}
+ use specified hash algorithm (default: SHA-512)
+
+ -h, --help
+ display this help and exit
+
+ -v, --verbose
+ print status messages to stdout
+To sign a message, a group member in good standing uses the following command:
$ ./signmsg --msg="test0" +
The above command signs a message "test0". signmsg 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: sig.dat
The example application verifysig shows you how to verify that a given Intel® EPID signature is produced by a member in good standing.
$ ./verifysig -h
+Usage: verifysig [OPTION]...
+Verify signature was created by group member in good standing
+
+Options:
+ --sig=FILE
+ load signature from FILE (default: sig.dat)
+
+ --msg=MESSAGE
+ MESSAGE that was signed (default: empty)
+
+ --bsn=BASENAME
+ BASENAME used in signature (default: random)
+
+ --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}
+ use specified hash algorithm for 2.0 groups (default: SHA-512)
+
+ -h, --help
+ display this help and exit
+
+ -v, --verbose
+ print status messages to stdout
+To verify that a signature is from a member in good standing, the verifier uses the following command:
$ ./verifysig --msg="test0" +signature verified successfully +
This verifies that the default signature file sig.dat is generated for the message "test0" by a member in good standing. verifysig uses default inputs for group public key, hash algorithm and IoT Issuing CA public key. All other parameters are ignored. The output verifysig: signature verified successfully denotes that the verification is successful.
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.
+To validate a signature with a basename, you need to use the same basename for signing and verification. The mechanism for ensuring that the member and verifier use the same basename is outside the scope of the SDK.
+If a basename is not provided, then the member uses a random basename and the signature generated by the member is anonymous.
+For more general information on why you might want to use a basename, refer to Name Based Signatures.
+To sign message "test0" with a basename "base0":
$ ./signmsg --msg="test0" --bsn="base0" +
To verify the signature:
$ ./verifysig --msg="test0" --bsn="base0" +verifysig: signature verified successfully +
To validate a signature, you need to use the same message for signing and verification. The mechanism for ensuring that the member and verifier use the same message is outside the scope of the SDK.
+Member and verifier must also use the same hash algorithm and basename, if applicable.
+The signature verification process fails if there is a parameter mismatch between sign and verify operations. Here are some examples.
+Verification fails if there is a mismatch in the message:
$ ./signmsg --msg="test0" +$ ./verifysig --msg="test1" +verifysig: signature verification failed: invalid signature +
Verification fails if there is a mismatch in the basename:
$ ./signmsg --msg="test0" --bsn="base0" +$ ./verifysig --msg="test0" --bsn="base1" +verifysig: signature verification failed: invalid signature +
The Intel® 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:
$ ./signmsg --msg="test0" --hashalg=SHA-256 +$ ./verifysig --msg="test0" --hashalg=SHA-384 +verifysig: signature verification failed: invalid signature +
Revocation lists are data structures used by the verifier to identify members that are no longer approved members of the group.
+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).
+Verification of a signature fails if it is generated by a member of a group that is revoked in the group revocation list.
+For example,
$ ./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 +
The verification fails because groupb is revoked and is an entry in the group revocation list (grprl.bin).
Verification of a signature fails if it is generated by a member whose private key is revoked in a private-key based revocation list.
+For example,
$ ./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 +
The verification fails because the private key of privrevokedmember0 is revoked and is an entry in the private key based revocation list of groupa (privrl.bin).
Verification of a signature fails if it is generated by a member whose signature is revoked in a signature based revocation list.
$ ./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 +
The message "test1" is signed by signmsg with a warning signmsg: signature revoked in SigRL. This means that the signature of sigrevokedmember0 is revoked in the signature based revocation list. The verification fails because the signature was generated by sigrevokedmember0, which is revoked and is an entry in the signature based revocation list of groupa (sigrl.bin).
|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
This walkthrough of the signmsg example shows you how to use SDK APIs to generate an Intel® EPID signature. Signmsg is built during the SDK build.
+
+
First, we include headers so we have access to needed declarations.
+The prng.h header provides access to a pseudo-random number generator needed for signing, while the utility headers are used by signmsg for logging and buffer management. The epid/member/api.h header provides access to the core member APIs. The epid/common/file_parser.h header provides an API for parsing buffers formatted according to the various IoT Intel® EPID binary file formats.
+
We define a stub function responsible for checking that the CA certificate is authorized by the root CA.
+IsCaCertAuthorizedByRootCa is called from main.c to validate the CA certificate before calling SignMsg. In an actual implementation, you need to provide an implementation to validate the issuing CA certificate with the CA root certificate before using it in parse functions.
+
The core signing functionality is contained in SignMsg.
The SignMsg parameters are either received by the member, or they are part of the member's configuration. The exceptions are the sig and sig_len parameters, which are used to output the signature.
The verifier might send the message to the member or there may be another mechanism to choose the message, but the way the message is communicated is outside the scope of the Intel® EPID scheme.
+We use the parameters member_precomp and member_precomp_is_input to pass in a pre-computation blob if provided. We can use the pre-computation blob to increase performance when verifying signatures repeatedly with the same group public key.
The member knows the group public key and the member private key.
+The member and the verifier agree on the message, basename, hash algorithm, and SigRL that the member uses for signing.
+
+
Next we do basic variable setup and argument checking.
+We create pointers to resources to be allocated and use the do {} while(0) idiom so that we can reliably free resources on return from SignMsg.
We create variables on the stack to hold the group public key and member private key.
+Finally we check to make sure that sig is a vaild pointer.
+
Next, we authenticate and extract the group public key using EpidParseGroupPubKeyFile.
+EpidParseGroupPubKeyFile takes a buffer containing a group public key in issuer binary format and validates that the public key is signed by the private key that corresponds to the provided CA certificate, extracting the key in the process.
+
+
We authenticate and extract the signed SigRL using EpidParseSigRlFile.
+We use EpidParseSigRlFile to:
+To determine the required sig_rl output buffer size, we provide a null pointer for the output buffer when calling EpidParseSigRlFile. This updates sig_rl_size with the required size of the output buffer.
After we find out the required size of the sig_rl, we allocate a buffer for the sig_rl. Then we fill the buffer using EpidParseSigRlFile.
+
Next, we fill the member private key.
+If the member private key is compressed, then we decompress it using EpidDecompressPrivKey before it can be passed to the member APIs. To determine if the member private key is compressed, we check if it is the known size of a compressed key.
+If the key size is not the size of a known format, we return an error.
+
+
Next, we create a pseudo-random number generator.
+ +prng should be a cryptographically secure random number generator.
+
Now that the inputs have been prepared, we create a member context using EpidMemberCreate.
+If a pre-computation blob is provided to the top level application, we use it. Otherwise, we pass in NULL.
+
We serialize pre-computed member data using EpidMemberWritePrecomp.
+ +The serialized member pre-computation blob can be used to greatly increase performance of EpidMemberCreate in future sessions if the same member private key is used.
+
+
Next, if a basename is specified, we register it with EpidRegisterBaseName so that the member can use it.
+In a typical use case, to prevent loss of privacy, the member keeps a list of basenames that correspond to authorized verifiers. The member signs a message with a basename only if the basename is in the member's basename list.
+
+
Then we set the hash algorithm to be used by the member using EpidMemberSetHashAlg.
+ +After the hash algorithm is set, future calls to EpidSign will use the same algorithm.
+
Next, we sign the message, generating an Intel® EPID signature.
+To create a signature, first we find out the required size of the signature using EpidGetSigSize. Then we allocate a buffer for the signature and fill the buffer using EpidSign.
+It is important to compute signature size after loading sig_rl because the signature size varies with the size of the SigRL.
+
Finally, we clean up and exit.
+If we made it past signing without an error, we set the return code appropriately and fall out of the do-while loop. If there was an error earlier, all breaks in the do-while loop bring us to this point with an error status.
+Next, we free the allocated resources. EpidMemberDelete deletes an existing member context.
+We return from SignMsg with the success or error status.
+
+
This concludes the signmsg walkthrough. Now you should be able to generate an Intel® EPID signature that proves a member's group membership to a verifier without revealing the member's identity.
To learn more about the SDK APIs see the API Reference. To learn more about the Intel® EPID scheme see Introduction to the Intel® EPID Scheme in the documentation.
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
This walkthrough of the verifysig example shows you how to use SDK APIs to verify an Intel® EPID 2.0 signature. Verifysig is built during the SDK build.
To verify an Intel® EPID 1.1 signature see the example code in verifysig11.c. For information on Intel® EPID 1.1 speciifc APIs see EPID 1.1 support.
+
First, we include headers so we have access to needed declarations.
+The utility headers are used by verifysig for logging and buffer management. The epid/verifier/api.h header provides access to the core verifier APIs, and the epid/common/file_parser.h header provides an API for parsing buffers formatted according to the various IoT Intel® EPID binary file formats.
+
We define a stub function responsible for checking that the CA certificate is authorized by the root CA.
+IsCaCertAuthorizedByRootCa is called from main.c to validate the CA certificate before calling Verify. In an actual implementation, you need to provide an implementation to validate the issuing CA certificate with the CA root certificate before using it in parse functions.
+
We use Verify to verify an Intel® EPID signature. Verify is a wrapper function that isolates SDK API functionality for the purpose of this walkthrough.
The Verify parameters were either sent by the verifier to the member, or they were part of the member's configuration. The exceptions are the sig and sig_len parameters, which we use to input the signature to be verified.
The verifier might send the message to the member or there may be another mechanism to choose the message, but the way the message is communicated is outside the scope of the Intel® EPID scheme.
+We use the parameters verifier_precomp and verifier_precomp_is_input to pass in a pre-computation blob if provided. We can use the pre-computation blob to increase performance when verifying signatures repeatedly with the same group public key.
The member and the verifier agree on the message, basename, hash algorithm, and SigRL that the verifier uses for verification.
+
+
Next we do basic variable setup.
+We create pointers to resources to be allocated and we use the do {} while(0) idiom so that we can reliably free resources on return from Verify. We also allocate the group public key on the stack.
+
Next, we authenticate and extract the group public key using EpidParseGroupPubKeyFile.
+EpidParseGroupPubKeyFile takes a buffer containing a group public key in issuer binary format and validates that the public key is signed by the private key that corresponds to the provided CA certificate, reading the key into pub_key in the process.
+
Next, we create a verifier context using EpidVerifierCreate.
+If a pre-computation blob is provided to the top level application, we use it. Otherwise, we pass in NULL.
+
Then we serialize pre-computed verifier data using EpidVerifierWritePrecomp.
+ +The serialized verifier pre-computation blob can be used to greatly increase performance of EpidVerifierCreate in future sessions if the same group public key is used.
+
+
We use EpidVerifierSetHashAlg to indicate the hash algorithm used for verification, which should be the same algorithm that the member used when signing.
+ +After the hash algorithm is set, future calls to EpidVerify will use the same algorithm.
+
+
We use EpidVerifierSetBasename to indicate the basename used for verification, which should be the same one that the member used when signing.
+ +After the basename is set, future calls to EpidVerify will use the same basename.
+
+
Before we verify a signature, we have to configure revocation lists so that we can check to see if a signer's group membership has been revoked.
+
+
We set the private key based revocation list using EpidVerifierSetPrivRl.
+We use EpidParsePrivRlFile to:
+To determine the required priv_rl buffer size, we provide a null pointer for the output buffer when calling EpidParsePrivRlFile.
After we find out the required size of the priv_rl buffer, we allocate memory for it. Then we fill the buffer using EpidParsePrivRlFile.
+
Next, we set the signature based revocation list using EpidVerifierSetSigRl.
+We use EpidParseSigRlFile to:
+To determine the required sig_rl buffer size, we provide a null pointer for the output buffer when calling EpidParseSigRlFile.
After we find out the required size of the sig_rl buffer, we allocate memory for it. Then we fill the buffer using EpidParseSigRlFile.
+
Next, we set the group based revocation list using EpidVerifierSetGroupRl.
+We use EpidParseGroupRlFile to:
+To determine the required grp_rl buffer size, we provide a null pointer for the output buffer when calling EpidParseGroupRlFile.
After we find out the required size of the grp_rl buffer, we allocate memory for it. Then we fill the buffer using EpidParseGroupRlFile.
+
Next, we set the verifier blacklist using EpidVerifierSetVerifierRl.
+The verifier is responsible for ensuring that the verifier revocation list is authorized. Validating it is outside the scope of this example.
+
+
Next, we use EpidVerify to verify that the Intel® EPID signature was created by a valid member of a group in good standing.
+Finally, we clean up and exit.
+If we made it past verification without an error, we set the return code appropriately and fall out of the do-while loop. If there was an error earlier, all breaks in the do-while loop bring us to this point with an error status.
Then we free the allocated resources. EpidVerifierDelete deletes the verifier context.
+After deleting the verifier context, we can also delete the revocation lists.
+We return from Verify with the success or error status.
+
This concludes the verifysig walkthrough. Now you should be able to verify an Intel® EPID signature using the SDK APIs.
To learn more about the SDK APIs see the API Reference. To learn more about the Intel® EPID Scheme see Introduction to the Intel® EPID Scheme in the documentation.
+|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
| CBasicSignature | Intel(R) EPID 2.0 basic signature |
| CBigNumStr | Serialized BigNum |
| CCompressedPrivKey | Compressed private key |
| CEcdsaPrivateKey | ECDSA Private Key |
| CEcdsaPublicKey | ECDSA Public Key |
| CEcdsaSignature | ECDSA Signature using NIST 256-bit curve secp256r1 |
| CEpid11BasicSignature | Intel(R) EPID 1.1 basic signature |
| CEpid11G2ElemStr | Serialized Intel(R) EPID 1.1 G2 element |
| CEpid11GroupPubKey | Intel(R) EPID 1.1 group public key |
| CEpid11GroupRl | Intel(R) EPID 1.1 group revocation list |
| CEpid11GtElemStr | Serialized Intel(R) EPID 1.1 GT element |
| CEpid11NrProof | Intel(R) EPID 1.1 non-revoked Proof |
| CEpid11Params | Intel(R) EPID 1.1 Parameters |
| CEpid11PrivRl | Intel(R) EPID 1.1 private-key based revocation list |
| CEpid11Signature | Intel(R) EPID 1.1 Signature |
| CEpid11SigRl | Intel(R) EPID 1.1 signature based revocation list |
| CEpid11SigRlEntry | Intel(R) EPID 1.1 entry in SigRL (B,K) |
| CEpid11VerifierPrecomp | Intel(R) EPID 1.1 Pre-computed verifier settings |
| CEpid2Params | Intel(R) EPID 2.0 Parameters |
| CEpidCaCertificate | IoT CA Certificate binary format |
| CEpidFileHeader | Intel(R) EPID binary file header |
| CEpidSignature | Intel(R) EPID 2.0 Signature |
| CFpElemStr | Number in [0, p-1] |
| CFq12ElemStr | Serialized Fq2^3^2 element |
| CFq2ElemStr | Serialized Fq2 element |
| CFq3ElemStr | Serialized Fq3 element |
| CFq6ElemStr | Serialized Fq2^3 element |
| CFqElemStr | Number in [0, q-1] |
| CG1ElemStr | Serialized G1 element |
| CG2ElemStr | Serialized G2 element |
| CGroupPubKey | Intel(R) EPID 2.0 group public key |
| CGroupRl | Group revocation list |
| CGtElemStr | Serialized GT element |
| CIPrivKey | Intel(R) EPID 2.0 issuing private key |
| CJoinRequest | Join request |
| CMemberPrecomp | Pre-computed member settings |
| CMembershipCredential | Membership credential |
| CNrProof | Non-revoked Proof |
| COctStr128 | 128 bit octet string |
| COctStr16 | 16 bit octet string |
| COctStr256 | 256 bit octet string |
| COctStr32 | 32 bit octet string |
| COctStr512 | 512 bit octet string |
| COctStr600 | 600 bit octet string |
| COctStr64 | 64 bit octet string |
| COctStr768 | 768 bit octet string |
| COctStr8 | 8 bit octet string |
| COctStr80 | 80 bit octet string |
| CPreComputedSignature | Pre-computed signature |
| CPrivKey | Intel(R) EPID 2.0 private key |
| CPrivRl | Private-key based revocation list |
| CSha256Digest | SHA256 digest |
| CSigRl | Signature based revocation list |
| CSigRlEntry | Entry in SigRL (B,K) |
| CVerifierPrecomp | Pre-computed verifier settings |
| CVerifierRl |
|
+ Intel® Enhanced Privacy ID SDK
+ 3.0.0
+
+ |
+
This file is used by Doxygen to generate documentation. +More...
+This file is used by Doxygen to generate documentation.
+e
zV7R~EP|a?vGtuf&jRryzMW8pt(B<`HCj7Vt>^3O$P0i@G94&Y|cTt&qd9R?iy>~bM
z|8K0whwlW)=6Dw Big number interface.
+More... Big number interface. Random data supplier interface.
+More... Random data supplier interface. This file is used by Doxygen to generate documentation.
+More... This file is used by Doxygen to generate documentation. This file is used by Doxygen to generate documentation.
+More... This file is used by Doxygen to generate documentation. This file is used by Doxygen to generate documentation.
+More... This file is used by Doxygen to generate documentation. Math primitives. Math primitives. Common code shared between core sub-components. Common code shared between core sub-components. Ecdsa interface.
+More... Ecdsa interface. Elliptic curve group interface.
+More... Elliptic curve group interface. This file is used by Doxygen to generate documentation.
+More... This file is used by Doxygen to generate documentation. (?(6XgW;oy<@Nh4c?(DA|K^BMz)A^8I|Pnm%Yw#cN9p+??#O#
z=DK!%VSjC6J`prGBuK!{n9NoRC2N$445LmhV`R W5mSOW@$
zMqVF~$R$+kd@R>29<#(o5B^;Kh9{2h@uP6~2)3IweXYmTrb`B;1WA 3F3NKL
+
+
+
+
+
+
+
+ #include <stddef.h>
+#include <stdint.h>
+#include "epid/common/stdtypes.h"
+#include "epid/common/errors.h"
+#include "epid/common/types.h"
+
+
+
+Typedefs
+
+typedef struct BigNum BigNum
+ Internal representation of large numbers.
+
+
+
+
+Functions
+EpidStatus NewBigNum (size_t data_size_bytes, BigNum **bignum)
+ Constructs a new BigNum. More...
+
+void DeleteBigNum (BigNum **bignum)
+ Deletes a previously allocated BigNum. More...
+
+EpidStatus ReadBigNum (void const *bn_str, size_t strlen, BigNum *bn)
+ Deserializes a BigNum from a string. More...
+
+EpidStatus WriteBigNum (BigNum const *bn, size_t strlen, void *bn_str)
+ Serializes a BigNum to a string. More...
+
+EpidStatus BigNumAdd (BigNum const *a, BigNum const *b, BigNum *r)
+ Adds two BigNum values. More...
+
+EpidStatus BigNumSub (BigNum const *a, BigNum const *b, BigNum *r)
+ Subtracts two BigNum values. More...
+
+EpidStatus BigNumMul (BigNum const *a, BigNum const *b, BigNum *r)
+ Multiplies two BigNum values. More...
+
+EpidStatus BigNumDiv (BigNum const *a, BigNum const *b, BigNum *q, BigNum *r)
+ Divides two BigNum values. More...
+
+EpidStatus BigNumMod (BigNum const *a, BigNum const *b, BigNum *r)
+ Computes modular reduction for BigNum value by specified modulus. More...
+
+EpidStatus BigNumIsEven (BigNum const *a, bool *is_even)
+ Checks if a BigNum is even. More...
+
+EpidStatus BigNumIsZero (BigNum const *a, bool *is_zero)
+ Checks if a BigNum is zero. More...
+
+EpidStatus BigNumPow2N (unsigned int n, BigNum *r)
+ Raises 2 to the given power. More...
+ Detailed Description
+
+
+
+
+
+
+
+
+
+
+
+
+Typedefs
+typedef int(__STDCALL * BitSupplier) (unsigned int *rand_data, int num_bits, void *user_data)
+ Generates random data. More...
+ Detailed Description
+
+
+
+
+
+
+
+
+ Detailed Description
+
+
+
+
+
+
+
+
+ Detailed Description
+
+
+
+
+
+
+
+
+ Detailed Description
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Files
+file file_parser.h
+ Epid 1.1 issuer material parsing utilities.
+
+file types.h
+ SDK data types for Intel(R) EPID 1.1.
+
+
+
+
+
+
+
+
+
+
+
+
+Files
+file api.h
+ Intel(R) EPID SDK verifier Intel(R) EPID 1.1 API.
+
+
+
+
+
+
+
+
+
+
+
+
+Files
+file bignum.h
+ Big number interface.
+
+file ecdsa.h
+ Ecdsa interface.
+
+file ecgroup.h
+ Elliptic curve group interface.
+
+file finitefield.h
+ Finite field interface.
+
+file hash.h
+ Hash primitives.
+
+file pairing.h
+ Pairing interface.
+
+file printutils.h
+ Print helper interface.
+
+file tatepairing.h
+ Intel(R) EPID 1.1 Pairing interface.
+ Detailed Description
+
+
+
+
+
+
+
+
+
+
+
+Directories
+directory math
+ Math primitives.
+
+
+
+
+Files
+file bitsupplier.h
+ Random data supplier interface.
+
+file errors.h
+ Error reporting.
+
+file file_parser.h
+ Epid issuer material parsing utilities.
+
+file stdtypes.h
+ C99 standard data types.
+
+file types.h
+ SDK data types.
+ Detailed Description
+
+
+
+
+
+
+
+
+ #include <stddef.h>
+#include "epid/common/errors.h"
+#include "epid/common/types.h"
+#include "epid/common/bitsupplier.h"
+
+
+
+
+Functions
+EpidStatus EcdsaVerifyBuffer (void const *buf, size_t buf_len, EcdsaPublicKey const *pubkey, EcdsaSignature const *sig)
+ Verifies authenticity of a digital signature over a buffer. More...
+
+EpidStatus EcdsaSignBuffer (void const *buf, size_t buf_len, EcdsaPrivateKey const *privkey, BitSupplier rnd_func, void *rnd_param, EcdsaSignature *sig)
+ Creates ECDSA signature of buffer. More...
+ Detailed Description
+
+
+
+
+
+
+
+
+ #include "epid/common/stdtypes.h"
+#include "epid/common/errors.h"
+#include "epid/common/math/bignum.h"
+#include "epid/common/math/finitefield.h"
+#include "epid/common/types.h"
+
+
+
+Typedefs
+
+typedef struct EcGroup EcGroup
+ Elliptic curve group over finite field.
+
+
+typedef struct EcPoint EcPoint
+ Point on elliptic curve over finite field.
+
+
+
+
+Functions
+EpidStatus NewEcGroup (FiniteField const *ff, FfElement const *a, FfElement const *b, FfElement const *x, FfElement const *y, BigNum const *order, BigNum const *cofactor, EcGroup **g)
+ Constructs a new EcGroup. More...
+
+void DeleteEcGroup (EcGroup **g)
+ Deletes a previously allocated EcGroup. More...
+
+EpidStatus NewEcPoint (EcGroup const *g, EcPoint **p)
+ Creates a new EcPoint. More...
+
+void DeleteEcPoint (EcPoint **p)
+ Deletes a previously allocated EcPoint. More...
+
+EpidStatus ReadEcPoint (EcGroup *g, void const *p_str, size_t strlen, EcPoint *p)
+ Deserializes an EcPoint from a string. More...
+
+EpidStatus WriteEcPoint (EcGroup *g, EcPoint const *p, void *p_str, size_t strlen)
+ Serializes an EcPoint to a string. More...
+
+EpidStatus EcMul (EcGroup *g, EcPoint const *a, EcPoint const *b, EcPoint *r)
+ Multiplies two elements in an elliptic curve group. More...
+
+EpidStatus EcExp (EcGroup *g, EcPoint const *a, BigNumStr const *b, EcPoint *r)
+ Raises a point in an elliptic curve group to a power. More...
+
+EpidStatus EcSscmExp (EcGroup *g, EcPoint const *a, BigNumStr const *b, EcPoint *r)
+ Software side-channel mitigated implementation of EcExp. More...
+
+EpidStatus EcMultiExp (EcGroup *g, EcPoint const **a, BigNumStr const **b, size_t m, EcPoint *r)
+ Multi-exponentiates elements in elliptic curve group. More...
+
+EpidStatus EcMultiExpBn (EcGroup *g, EcPoint const **a, BigNum const **b, size_t m, EcPoint *r)
+ Multi-exponentiates elements in elliptic curve group. More...
+
+EpidStatus EcSscmMultiExp (EcGroup *g, EcPoint const **a, BigNumStr const **b, size_t m, EcPoint *r)
+ Software side-channel mitigated implementation of EcMultiExp. More...
+
+EpidStatus EcGetRandom (EcGroup *g, BitSupplier rnd_func, void *rnd_func_param, EcPoint *r)
+ Generates a random element from an elliptic curve group. More...
+
+EpidStatus EcInGroup (EcGroup *g, void const *p_str, size_t strlen, bool *in_group)
+ Checks if a point is in an elliptic curve group. More...
+
+EpidStatus Epid11EcHash (EcGroup *g, void const *msg, size_t msg_len, EcPoint *r)
+ Hashes an arbitrary message to an Intel(R) EPID 1.1 element in an elliptic curve group. More...
+
+EpidStatus EcHash (EcGroup *g, void const *msg, size_t msg_len, HashAlg hash_alg, EcPoint *r)
+ Hashes an arbitrary message to an element in an elliptic curve group. More...
+
+EpidStatus EcMakePoint (EcGroup *g, FfElement const *x, EcPoint *r)
+ Sets an EcPoint variable to a point on a curve. More...
+
+EpidStatus EcInverse (EcGroup *g, EcPoint const *p, EcPoint *r)
+ Computes the additive inverse of an EcPoint. More...
+
+EpidStatus EcIsEqual (EcGroup *g, EcPoint const *a, EcPoint const *b, bool *is_equal)
+ Checks if two EcPoints are equal. More...
+
+EpidStatus EcIsIdentity (EcGroup *g, EcPoint const *p, bool *is_identity)
+ Checks if an EcPoint is the identity element. More...
+ Detailed Description
+
+
+
+
+
+
+
+
+ Detailed Description
+