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).