com.intel.crypto
Class SigmaAlg
- java.lang.Object
-
- com.intel.crypto.SigmaAlg
-
public abstract class SigmaAlg extends java.lang.Object
This abstract class represents a Sigma key exchange protocol. This protocol lets an application running in the firmware securely exchange symmetric keys with a remote party. The Sigma protocol is based on the Diffie-Hellman key exchange and uses the EPID signing algorithm to authenticate the firmware to the remote party. Since the Sigma protocol uses an EPID signature, EPID must be provisioned prior to using this class (see the
EpidAlg
class for more details on EPID provisioning).During a single Sigma protocol session between an application and a remote party, the following steps are expected to take place:
- The application creates a new instance of
SigmaAlg
using thecreate
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 its public key for the session using the
getPublicKey
method of this class and sends it to the remote party. - The application receives the authentication parameters of the remote party and
uses the
verifyParams
method of this class to validate them. - The application uses the
getParams
method of this class to obtain the firmware authentication parameters to be sent to the remote party. - 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 of this class. - 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
-
-
Method Summary
Methods Modifier and Type Method and Description static SigmaAlg
create()
Factory method for creatingSigmaAlg
instance for a new Sigma session.abstract void
dispose()
Releases resources which may have been allocated by the Sigma implementation.abstract short
getEpidSignatureLength()
Returns the length of the EPID signature.abstract short
getFwCertLength()
Returns the length of the firmware EPID certificate.abstract short
getHmacLength()
Returns the length of the HMAC signature used by the Sigma key exchange protocol.abstract short
getMacKey(byte[] macKey, short macKeyIndex)
Obtains the MAC key generated during the key exchange.abstract short
getMacKeySize()
Returns the length of the MAC key generated during the key exchange.abstract void
getParams(byte[] certificate, short certificateIndex, byte[] HMAC, short HMACIndex, byte[] signature, short signatureIndex)
Obtains the firmware authentication parameters to be sent to the remote party during the Sigma session.abstract short
getPublicKey(byte[] publicKey, short publicKeyIndex)
Obtains the public part of the Diffie-Hellman key (g^a) generated for the current Sigma key exchange session.abstract short
getPublicKeySize()
Returns the length of the public key generated during the key exchange.abstract short
getSecretKey(byte[] secretKey, short secretKeyIndex)
Obtains the secret key generated during the key exchange.abstract short
getSecretKeySize()
Returns the length of the secret key generated during the key exchange.abstract void
initialize()
Initializes this instance to start a new Sigma key exchange session.abstract boolean
verifyParams(byte[] publicKey, short publicKeyIndex, byte[] certificate, short certificateIndex, short certificateLength, byte[] HMAC, short HMACIndex, byte[] signature, short signatureIndex)
Validates the authentication parameters received from the remote party during the Sigma session.
-
-
-
Method Detail
-
initialize
public abstract void initialize() throws CryptoException
Initializes this instance to start a new Sigma key exchange session. This method must be called before using any other methods of this class.- Throws:
IllegalUseException
- if the instance is already initialized and thedispose
method was not invoked.OutOfResourcesException
- if currently there are no more resources in the system available to start a new Sigma session. In such a case, the caller should try opening a new session at a later time.CryptoException
-
getPublicKeySize
public abstract short getPublicKeySize() throws CryptoException
Returns the length of the public key generated during the key exchange.- Returns:
- Length of the public key in bytes.
- Throws:
NotInitializedException
- in the following cases:- This instance was not initialized yet using the
initialize
method. - EPID was not provisioned yet.
- This instance was not initialized yet using the
CryptoException
-
getPublicKey
public abstract short getPublicKey(byte[] publicKey, short publicKeyIndex) throws CryptoException
Obtains the public part of the Diffie-Hellman key (g^a) generated for the current Sigma key exchange session. ThegetPublicKeySize
method can be used to obtain the expected size of the key.- Parameters:
publicKey
- an array to hold the public keypublicKeyIndex
- index in the key array- Returns:
- The number of bytes returned in the array.
- Throws:
NotInitializedException
- in the following cases:- This instance was not initialized yet using the
initialize
method. - 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 theverifyParams
method was already called).CryptoException
-
getHmacLength
public abstract short getHmacLength()
Returns the length of the HMAC signature used by the Sigma key exchange protocol.- Returns:
- HMAC length in bytes.
-
verifyParams
public abstract boolean verifyParams(byte[] publicKey, short publicKeyIndex, byte[] certificate, short certificateIndex, short certificateLength, byte[] HMAC, short HMACIndex, byte[] signature, short signatureIndex) throws CryptoException
Validates the authentication parameters received from the remote party during the Sigma session. Note that if the parameters verification fails, the current Sigma session can no longer be used, and the caller must re-initialize it by calling thedispose
andinitialize
methods.- 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:
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 thegetPublicKey
method is called).CryptoException
-
getParams
public abstract void getParams(byte[] certificate, short certificateIndex, byte[] HMAC, short HMACIndex, byte[] signature, short signatureIndex) throws CryptoException
Obtains the firmware authentication parameters to be sent to the remote party during the Sigma session.- 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:
NotInitializedException
- in the following cases:- This instance was not initialized yet using the
initialize
method.
- 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 before theverifyParams
method is called).CryptoException
-
getFwCertLength
public abstract short getFwCertLength()
Returns the length of the firmware EPID certificate. Can be used to get the required output certificate buffer size before calling thegetParams
method.- Returns:
- Length in bytes of the firmware certificate.
-
getEpidSignatureLength
public abstract short getEpidSignatureLength()
Returns the length of the EPID signature. Can be used to get the required output signature buffer size before calling thegetParams
method.- Returns:
- Length in bytes of EPID signature.
-
getSecretKeySize
public abstract short getSecretKeySize() throws CryptoException
Returns the length of the secret key generated during the key exchange.- Returns:
- Length of the secret key in bytes.
- Throws:
NotInitializedException
- in the following cases:- This instance was not initialized yet using the
initialize
method. - EPID was not provisioned yet.
- This instance was not initialized yet using the
CryptoException
-
getSecretKey
public abstract short getSecretKey(byte[] secretKey, short secretKeyIndex) throws CryptoException
Obtains the secret key generated during the key exchange. ThegetSecretKeySize
can be used to obtain the expected size of the key.- Parameters:
secretKey
- an array to hold the secret keysecretKeyIndex
- index in the key array- Returns:
- The secret key length in bytes.
- Throws:
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 theverifyParams
method is called).CryptoException
-
getMacKeySize
public abstract short getMacKeySize() throws CryptoException
Returns the length of the MAC key generated during the key exchange.- Returns:
- Length of the MAC key in bytes.
- Throws:
NotInitializedException
- in the following cases:- This instance was not initialized yet using the
initialize
method. - EPID was not provisioned yet.
- This instance was not initialized yet using the
CryptoException
-
getMacKey
public abstract short getMacKey(byte[] macKey, short macKeyIndex) throws CryptoException
Obtains the MAC key generated during the key exchange. ThegetMacKeySize
can be used to obtain the expected size of the key.- Parameters:
macKey
- an array to hold the MAC keymacKeyIndex
- index in the key array- Returns:
- The MAC key length in bytes.
- Throws:
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 theverifyParams
method is called).CryptoException
-
dispose
public abstract void dispose() throws CryptoException
Releases resources which may have been allocated by the Sigma implementation. After calling this method, the instance can no longer be used- Throws:
NotInitializedException
- if this instance was not initialized yet using theinitialize
method.CryptoException
-
create
public static final SigmaAlg create()
Factory method for creatingSigmaAlg
instance for a new Sigma session.- Returns:
SigmaAlg
instance.
-
-