com.intel.crypto
Class SigmaAlgEx2
- java.lang.Object
-
- com.intel.crypto.SigmaAlg
-
- com.intel.crypto.SigmaAlgEx2
-
public abstract class SigmaAlgEx2 extends SigmaAlg
This abstract class represents the extended version of Sigma key exchange protocol: Sigma 2.0 (detailed description of this protocol is defined in the Sigma Protocol Specification). See also
SigmaAlg
class.Note that max verifier certificate chain length supported is 5.
During a Sigma 2.0 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.
NOTE: The default for OCSP requered is false. - 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.
- The application creates a new instance of
-
-
Field Summary
Fields Modifier and Type Field and Description static byte
SESSION_PARAM_VERIFIER_CERT_ISSUER_COMMON_NAME
The issuer common name of the verifier's certificate received in S2.static byte
SESSION_PARAM_VERIFIER_CERT_OCSP_REQUIRED
Is OCSP required flag 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_COMMON_NAME
The subject common name 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 int
SIGMA_ALG_EX_PROPERTY_APPEND_SVN
If property is set to true, the caller security version number is appended to the S3 message. Default value: False.static int
SIGMA_ALG_EX_PROPERTY_APPEND_SVN_BIT
The first bit in the bit mask indicates append SVN property.static byte
SIGMA_PROTOCOL_VERSION_2_0
Sigma 2.0 protocol version
-
Constructor Summary
Constructors Constructor and Description SigmaAlgEx2()
-
Method Summary
Methods Modifier and Type Method and Description static SigmaAlgEx2
createInstance(byte protocolVersion)
Factory method for creatingSigmaAlgEx
instance for a new Sigma session.abstract short
getCertChainLength(byte[] s2)
This function returns the number of certificates in the Verifier chain including the root certificateabstract short
getFwCertLength()
This method is not supported as part of Sigma 2.0 protocol.abstract boolean
getIsOcspRequired()
Returns if OCSP required is setabstract void
getParams(byte[] certificate, short certificateIndex, byte[] HMAC, short HMACIndex, byte[] signature, short signatureIndex)
This method is not supported as part of Sigma 2.0 protocol.abstract boolean
getProperty(int propertyId)
Returns the value of a specific algorithm propertyabstract short
getPublicKey(byte[] publicKey, short publicKeyIndex)
This method is not supported as part of Sigma 2.0 protocol.abstract short
getPublicKeySize()
This method is not supported as part of Sigma 2.0 protocol.abstract int
getS1Message(boolean isOcspRequired, byte[] s1, int s1Index)
Obtains the first message that should be sent by the prover to the verifier during Sigma key exchange.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 bygetS1Message
method.abstract int
getS3MessageLength(byte[] s2, int s2Index, int s2Length)
Returns the maximum length of the S3 message that is expected to be returned byprocessS2Message
method.abstract byte[]
getSessionParameter(byte parameterType)
Returns the data of the specified parameter in the established session.abstract byte[]
getSessionParameter(byte[] s2, short certificateIndex, byte parameterType)
Returns the data in x509 format (including metadata) of the specified parameter in the specific index in the certificate chain.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 void
setProperty(int propertyId, boolean state)
Sets a property that modifies the algorithm behaviorabstract 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 2.0 protocol.-
Methods inherited from class com.intel.crypto.SigmaAlg
create, dispose, getEpidSignatureLength, getHmacLength, getMacKey, getMacKeySize, getSecretKey, getSecretKeySize, initialize
-
-
-
-
Field Detail
-
SIGMA_PROTOCOL_VERSION_2_0
public static final byte SIGMA_PROTOCOL_VERSION_2_0
Sigma 2.0 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_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
-
SESSION_PARAM_VERIFIER_CERT_ISSUER_COMMON_NAME
public static final byte SESSION_PARAM_VERIFIER_CERT_ISSUER_COMMON_NAME
The issuer common name of the verifier's certificate received in S2.- See Also:
- Constant Field Values
-
SESSION_PARAM_VERIFIER_CERT_SUBJECT_COMMON_NAME
public static final byte SESSION_PARAM_VERIFIER_CERT_SUBJECT_COMMON_NAME
The subject common name of the verifier's certificate received in S2.- See Also:
- Constant Field Values
-
SESSION_PARAM_VERIFIER_CERT_OCSP_REQUIRED
public static final byte SESSION_PARAM_VERIFIER_CERT_OCSP_REQUIRED
Is OCSP required flag in the verifier's certificate received in S2.- See Also:
- Constant Field Values
-
SIGMA_ALG_EX_PROPERTY_APPEND_SVN
public static final int SIGMA_ALG_EX_PROPERTY_APPEND_SVN
If property is set to true, the caller security version number is appended to the S3 message. Default value: False.- See Also:
- Constant Field Values
-
SIGMA_ALG_EX_PROPERTY_APPEND_SVN_BIT
public static final int SIGMA_ALG_EX_PROPERTY_APPEND_SVN_BIT
The first bit in the bit mask indicates append SVN property. If this bit is set, the caller security version number is appended to the S3 message By default this bit isn't set.- See Also:
- Constant Field Values
-
-
Method Detail
-
getCertChainLength
public abstract short getCertChainLength(byte[] s2) throws CryptoException
This function returns the number of certificates in the Verifier chain including the root certificate- Parameters:
s2
- an array holds s2 message- Returns:
- Number of certificates in the Verifier chain including the root certificate.
- Throws:
IllegalParameterException
CryptoException
- for any other error
-
getS1Message
public abstract int getS1Message(boolean isOcspRequired, 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 Intel® Enhanced Privacy ID (Intel® 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. ThegetS1MessageLength
method can be used to obtain the maximum expected size of data to be returned by this method.- Parameters:
isOcspRequired
- flag used to indicate if prover should request OCSP response. (this field is false by default)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. - Intel® EPID was not provisioned yet.
- This instance was not initialized yet using the
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
-
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 Intel® 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. ThegetS1MessageLength
method can be used to obtain the maximum expected size of data to be returned by this method.
NOTE: The default for OCSP required is false, you can set by callinggetS1Message(boolean, byte[], int)
or pass this value via the verifier certificate ocsp extention.- 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. - Intel® EPID was not provisioned yet.
- This instance was not initialized yet using the
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
-
getS1MessageLength
public abstract int getS1MessageLength() throws CryptoException
Returns the maximum length of the S1 message that is expected to be returned bygetS1Message
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. - Intel® EPID was not provisioned yet.
- This instance was not initialized yet using the
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)
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 UUID of the specific applet that created this session
- may include the applet security version according to
SIGMA_ALG_EX_PROPERTY_APPEND_SVN
- prover's Intel® 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 Intel® 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).OperationFailedException
- if the platform keys are revokedCryptoException
-
getSessionParameter
public abstract byte[] getSessionParameter(byte parameterType) throws CryptoException
Returns the data of the specified parameter in the established session.
This function supports only this session parameters:- SESSION_PARAM_VERIFIER_CERT_SUBJECT_UNIQUE_ID
- SESSION_PARAM_VERIFIER_CERT_SERIAL_NUMBER
- SESSION_PARAM_VERIFIER_CERT_PRODUCT_TYPE
- 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
-
getSessionParameter
public abstract byte[] getSessionParameter(byte[] s2, short certificateIndex, byte parameterType) throws CryptoException
Returns the data in x509 format (including metadata) of the specified parameter in the specific index in the certificate chain. See the SESSION_PARAM_... definitions above for the supported parameter types. NOTE: This property is updated after calling 'processS2Message'. NOTE: For parameter data format, refer to the x509/SIGMA specification.- Parameters:
s2
- s2 message that includes the certificate chaincertificateIndex
- the index in the certificate chainparameterType
- 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.IllegalParameterException
- in case the one of the parameters is illegal.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 byprocessS2Message
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 2.0 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 2.0 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 2.0 protocol.- Specified by:
getParams
in classSigmaAlg
- Parameters:
certificate
- an array to hold the firmware Intel® EPID certificate (in Intel® EPID proprietary format)certificateIndex
- index in the certificate arrayHMAC
- HMAC on the certificate using the session MAC keyHMACIndex
- index in the HMAC arraysignature
- Intel® 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 2.0 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 2.0 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.
-
setProperty
public abstract void setProperty(int propertyId, boolean state) throws CryptoException
Sets a property that modifies the algorithm behavior- Parameters:
propertyId
- the property to be set, one of SIGMA_ALG_EX_PROPERTY_XYZstate
- determines whether the property is enabled or disabled- Throws:
IllegalParameterException
- if propertyId is unknownNotInitializedException
- if this instance was not initializedCryptoException
- for any other error
-
getProperty
public abstract boolean getProperty(int propertyId) throws CryptoException
Returns the value of a specific algorithm property- Parameters:
propertyId
- the property to get, one of SIGMA_ALG_EX2_PROPERTY_XYZ- Returns:
- Returns whether a specific property is disabled or enabled
- Throws:
IllegalParameterException
- if propertyId is unknownNotInitializedException
- if this instance was not initializedCryptoException
- for any other error
-
getIsOcspRequired
public abstract boolean getIsOcspRequired()
Returns if OCSP required is set- Returns:
- Returns whether OCSP is required
NOTE: This property updated after calling toprocessS2Message
and can be set by callinggetS1Message(boolean, byte[], int)
or pass this files in the verifier certificate.
-
createInstance
public static final SigmaAlgEx2 createInstance(byte protocolVersion)
Factory method for creatingSigmaAlgEx
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
-
-