Intel

Developer Zone

SigmaAlgEx


com.intel.crypto
Class SigmaAlgEx

java.lang.Object
  extended by com.intel.crypto.SigmaAlg
      extended by 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 the createInstance method followed by the initialize method of this class. Note that this instance can only be used for one Sigma key exchange session simultaneously (after calling the dispose 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 and getMacKey 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 data
s1Index - 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 the processS2Message method was already called).
CryptoException

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

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)
Note that if S2 message verification fails, the current Sigma session can no longer be used, and the caller must re-initialize it by calling the dispose and initialize 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
The 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 verifier
s2Index - index in the S2 message array
s2Length - length of the S2 message
s3 - an array to hold the S3 message
s3Index - 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 the initialize method.
IllegalUseException - if the current state of the Sigma session does not allow calling this method (for example, if it is called before the getS1Message 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 verifier
s2Index - index in the S2 message array
s2Length - 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 the initialize method.
IllegalUseException - if the current state of the Sigma session does not allow calling this method (for example, if it is called before the getS1Message 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 class SigmaAlg
Parameters:
publicKey - an array to hold the public key
publicKeyIndex - 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 class SigmaAlg
Parameters:
publicKey - second party public part of the Diffie-Hellman key (g^b)
publicKeyIndex - index in the public key array
certificate - the certificate received from the second party (in Sigma proprietary format)
certificateIndex - index in the certificate array
certificateLength - certificate length
HMAC - HMAC on the certificate using the session MAC key
HMACIndex - index in the HMAC array
signature - EC-DSA signature on (g^a || g^b) using the private key from the certificate
signatureIndex - 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.

Specified by:
getParams in class SigmaAlg
Parameters:
certificate - an array to hold the firmware EPID certificate (in EPID proprietary format)
certificateIndex - index in the certificate array
HMAC - HMAC on the certificate using the session MAC key
HMACIndex - index in the HMAC array
signature - 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 class SigmaAlg
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 class SigmaAlg
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