com.intel.crypto
Class SigmaAlgEx
java.lang.Objectcom.intel.crypto.SigmaAlg
com.intel.crypto.SigmaAlgEx
public abstract class SigmaAlgEx
- extends SigmaAlg
This abstract class represents the extended version of Sigma key exchange protocol: Sigma 1.1
(detailed description of this protocol is defined in the Sigma Protocol Specification).
See also SigmaAlg
class.
During a Sigma 1.1 protocol session, between an application that acts as the prover and a remote party that acts as the verifier, the following steps are expected to take place:
- The application creates a new instance of
SigmaAlgEx
using thecreateInstance
method followed by theinitialize
method of this class. Note that this instance can only be used for one Sigma key exchange session simultaneously (after calling thedispose
method,initialize
can be called again in order to start another Sigma session). - The application obtains the S1 message using the
getS1Message
method of this class and sends it to the remote party. - The application receives the S2 message from the remote party and uses the
processS2Message
method of this class to validate S2 and obtain the S3 message to be sent to the remote party in order to complete the key exchange. - After the authentication of both parties is complete, the application
can obtain the secret key and MAC key generated for this session by calling
the
getSecretKey
andgetMacKey
methods. - After the Sigma session ends, the application must call the
dispose
method of this class to release any resources that might have been allocated for the session.
Field Summary | |
---|---|
static byte |
SESSION_PARAM_VERIFIER_CERT_ISSUER_UNIQUE_ID
The issuer unique ID as specified in the verifier's certificate received in S2. |
static byte |
SESSION_PARAM_VERIFIER_CERT_PRODUCT_TYPE
The product type field as specified in the verifier's certificate received in S2. |
static byte |
SESSION_PARAM_VERIFIER_CERT_SERIAL_NUMBER
The serial number of the verifier's certificate received in S2. |
static byte |
SESSION_PARAM_VERIFIER_CERT_SUBJECT_UNIQUE_ID
The subject unique ID as specified in the verifier's certificate received in S2. |
static byte |
SIGMA_PROTOCOL_VERSION_1_1
Sigma 1.1 protocol version |
Constructor Summary | |
---|---|
SigmaAlgEx()
|
Method Summary | |
---|---|
static SigmaAlgEx |
createInstance(byte protocolVersion)
Factory method for creating SigmaAlgEx instance for a new Sigma session. |
abstract short |
getFwCertLength()
This method is not supported as part of Sigma 1.1 protocol. |
abstract void |
getParams(byte[] certificate,
short certificateIndex,
byte[] HMAC,
short HMACIndex,
byte[] signature,
short signatureIndex)
This method is not supported as part of Sigma 1.1 protocol. |
abstract short |
getPublicKey(byte[] publicKey,
short publicKeyIndex)
This method is not supported as part of Sigma 1.1 protocol. |
abstract short |
getPublicKeySize()
This method is not supported as part of Sigma 1.1 protocol. |
abstract int |
getS1Message(byte[] s1,
int s1Index)
Obtains the first message that should be sent by the prover to the verifier during Sigma key exchange. |
abstract int |
getS1MessageLength()
Returns the maximum length of the S1 message that is expected to be returned by getS1Message method. |
abstract int |
getS3MessageLength(byte[] s2,
int s2Index,
int s2Length)
Returns the maximum length of the S3 message that is expected to be returned by processS2Message method. |
abstract byte[] |
getSessionParameter(byte parameterType)
Returns the data of the specified parameter in the established session. |
abstract int |
processS2Message(byte[] s2,
int s2Index,
int s2Length,
byte[] s3,
int s3Index)
Validates the S2 message sent by the verifier to the prover during the Sigma session and obtains the S3 message that should be sent by the prover to the verifier to complete the key exchange. |
abstract boolean |
verifyParams(byte[] publicKey,
short publicKeyIndex,
byte[] certificate,
short certificateIndex,
short certificateLength,
byte[] HMAC,
short HMACIndex,
byte[] signature,
short signatureIndex)
This method is not supported as part of Sigma 1.1 protocol. |
Methods inherited from class com.intel.crypto.SigmaAlg |
---|
create, dispose, getEpidSignatureLength, getHmacLength, getMacKey, getMacKeySize, getSecretKey, getSecretKeySize, initialize |
Methods inherited from class java.lang.Object |
---|
equals, hashCode, toString |
Field Detail |
---|
SIGMA_PROTOCOL_VERSION_1_1
public static final byte SIGMA_PROTOCOL_VERSION_1_1
- Sigma 1.1 protocol version
- See Also:
- Constant Field Values
SESSION_PARAM_VERIFIER_CERT_PRODUCT_TYPE
public static final byte SESSION_PARAM_VERIFIER_CERT_PRODUCT_TYPE
- The product type field as specified in the verifier's certificate received in S2.
- See Also:
- Constant Field Values
SESSION_PARAM_VERIFIER_CERT_SERIAL_NUMBER
public static final byte SESSION_PARAM_VERIFIER_CERT_SERIAL_NUMBER
- The serial number of the verifier's certificate received in S2.
- See Also:
- Constant Field Values
SESSION_PARAM_VERIFIER_CERT_ISSUER_UNIQUE_ID
public static final byte SESSION_PARAM_VERIFIER_CERT_ISSUER_UNIQUE_ID
- The issuer unique ID as specified in the verifier's certificate received in S2.
- See Also:
- Constant Field Values
SESSION_PARAM_VERIFIER_CERT_SUBJECT_UNIQUE_ID
public static final byte SESSION_PARAM_VERIFIER_CERT_SUBJECT_UNIQUE_ID
- The subject unique ID as specified in the verifier's certificate received in S2.
- See Also:
- Constant Field Values
Constructor Detail |
---|
SigmaAlgEx
public SigmaAlgEx()
Method Detail |
---|
getS1Message
public abstract int getS1Message(byte[] s1, int s1Index) throws CryptoException
- Obtains the first message that should be sent by the prover to the verifier during
Sigma key exchange. This message contains the EPID Group ID of this platform, the
public part of the Diffie-Hellman key (g^a) generated for the current Sigma session
and the OCSP request generated for this session. The
getS1MessageLength
method can be used to obtain the maximum expected size of data to be returned by this method.- Parameters:
s1
- an array to hold the output datas1Index
- index in the output array- Returns:
- Actual length of the S1 message copied into the output array.
- Throws:
NotInitializedException
- in the following cases:- This instance was not initialized yet using the
initialize
method. - EPID was not provisioned yet.
IllegalUseException
- if the current state of the Sigma session does not allow calling this method (for example, if it is called after theprocessS2Message
method was already called).CryptoException
- This instance was not initialized yet using the
getS1MessageLength
public abstract int getS1MessageLength() throws CryptoException
- Returns the maximum length of the S1 message that is expected to be returned by
getS1Message
method.- Returns:
- Expected length in bytes of the S1 message.
- Throws:
NotInitializedException
- in the following cases:- This instance was not initialized yet using the
initialize
method. - EPID was not provisioned yet.
CryptoException
- This instance was not initialized yet using the
processS2Message
public abstract int processS2Message(byte[] s2, int s2Index, int s2Length, byte[] s3, int s3Index) throws CryptoException
- Validates the S2 message sent by the verifier to the prover during the Sigma session and obtains
the S3 message that should be sent by the prover to the verifier to complete the key exchange.
The S2 message from the verifier contains the following data:
- verifier's public part of the Diffie-Hellman key (g^b)
- verifier's certificate chain
- the Basename chosen by the verifier for the protocol (verifier can choose random based signature)
- the Signature Revocation List for the Group ID specified in S1
- OCSP response for the verifier's certificate chain
- HMAC computed using the session MAC key on several fields in the message, as required by the protocol
- signature using the verifier's private key on (g^a || g^b)
dispose
andinitialize
methods. The S3 message to be sent by the prover contains the following data:- task information that identifies the initiator of this Sigma session inside the firmware, including the specific applet that created this session (accordig to UUID)
- prover's EPID certificate
- prover's public part of the Diffie-Hellman key (g^a) (equals to the one sent in S1)
- HMAC computed using the session MAC key on several fields in the message, as required by the protocol
- prover's EPID signature on several fields in the message, as required by the protocol
- Non-Revoked proofs created by the prover based on the Signature Revocation List from S2
getS3MessageLength
method can be used to obtain the maximum expected size of data to be returned by this method.- Parameters:
s2
- S2 message received from the verifiers2Index
- index in the S2 message arrays2Length
- length of the S2 messages3
- an array to hold the S3 messages3Index
- index in the output array- Returns:
- Actual length of the S3 message copied into the output array.
- Throws:
IllegalParameterException
- if S2 message validation failed.NotInitializedException
- if this instance was not initialized yet using theinitialize
method.IllegalUseException
- if the current state of the Sigma session does not allow calling this method (for example, if it is called before thegetS1Message
method is called).CryptoException
getSessionParameter
public abstract byte[] getSessionParameter(byte parameterType) throws CryptoException
- Returns the data of the specified parameter in the established session.
See SESSION_PARAM_... definitions above for the support parameter types.
- Parameters:
parameterType
- the type of the requested parameter- Returns:
- The data corresponding to the requested parameter in the established session.
- Throws:
NotInitializedException
- in case the requested parameter was not initialized during the session.NotSupportedException
- in case the specified parameter type is not supported.CryptoException
getS3MessageLength
public abstract int getS3MessageLength(byte[] s2, int s2Index, int s2Length) throws CryptoException
- Returns the maximum length of the S3 message that is expected to be returned by
processS2Message
method.- Parameters:
s2
- S2 message received from the verifiers2Index
- index in the S2 message arrays2Length
- length of the S2 message- Returns:
- Expected length in bytes of the S3 message.
- Throws:
IllegalParameterException
- if S2 message is not valid.NotInitializedException
- if this instance was not initialized yet using theinitialize
method.IllegalUseException
- if the current state of the Sigma session does not allow calling this method (for example, if it is called before thegetS1Message
method is called).CryptoException
getPublicKey
public abstract short getPublicKey(byte[] publicKey, short publicKeyIndex) throws NotSupportedException
- This method is not supported as part of Sigma 1.1 protocol.
- Specified by:
getPublicKey
in classSigmaAlg
- Parameters:
publicKey
- an array to hold the public keypublicKeyIndex
- index in the key array- Returns:
- The number of bytes returned in the array.
- Throws:
NotSupportedException
- always, since this method is supported only for Sigma 1.0 protocol.
verifyParams
public abstract boolean verifyParams(byte[] publicKey, short publicKeyIndex, byte[] certificate, short certificateIndex, short certificateLength, byte[] HMAC, short HMACIndex, byte[] signature, short signatureIndex) throws NotSupportedException
- This method is not supported as part of Sigma 1.1 protocol.
- Specified by:
verifyParams
in classSigmaAlg
- Parameters:
publicKey
- second party public part of the Diffie-Hellman key (g^b)publicKeyIndex
- index in the public key arraycertificate
- the certificate received from the second party (in Sigma proprietary format)certificateIndex
- index in the certificate arraycertificateLength
- certificate lengthHMAC
- HMAC on the certificate using the session MAC keyHMACIndex
- index in the HMAC arraysignature
- EC-DSA signature on (g^a || g^b) using the private key from the certificatesignatureIndex
- index in the signature array- Returns:
true
if the parameters verification was successful,false
otherwise.- Throws:
NotSupportedException
- always, since this method is supported only for Sigma 1.0 protocol.
getParams
public abstract void getParams(byte[] certificate, short certificateIndex, byte[] HMAC, short HMACIndex, byte[] signature, short signatureIndex) throws NotSupportedException
- This method is not supported as part of Sigma 1.1 protocol.
- Parameters:
certificate
- an array to hold the firmware EPID certificate (in EPID proprietary format)certificateIndex
- index in the certificate arrayHMAC
- HMAC on the certificate using the session MAC keyHMACIndex
- index in the HMAC arraysignature
- EPID signature on (g^a || g^b)signatureIndex
- index in the signature array- Throws:
NotSupportedException
- always, since this method is supported only for Sigma 1.0 protocol.
getFwCertLength
public abstract short getFwCertLength() throws NotSupportedException
- This method is not supported as part of Sigma 1.1 protocol.
- Specified by:
getFwCertLength
in classSigmaAlg
- Returns:
- Length in bytes of the firmware certificate.
- Throws:
NotSupportedException
- always, since this method is supported only for Sigma 1.0 protocol.
getPublicKeySize
public abstract short getPublicKeySize() throws NotSupportedException
- This method is not supported as part of Sigma 1.1 protocol.
- Specified by:
getPublicKeySize
in classSigmaAlg
- Returns:
- Length of the public key in bytes.
- Throws:
NotSupportedException
- always, since this method is supported only for Sigma 1.0 protocol.
createInstance
public static final SigmaAlgEx createInstance(byte protocolVersion)
- Factory method for creating
SigmaAlgEx
instance for a new Sigma session.- Parameters:
protocolVersion
- the version of the protocol that should be used by the created instance.- Returns:
SigmaAlgEx
instance.- Throws:
NotSupportedException
- if the requested protocol version is not supported