com.intel.crypto
Class SigmaAlg
java.lang.Objectcom.intel.crypto.SigmaAlg
- Direct Known Subclasses:
- SigmaAlgEx
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).
Note that this class provides an interface for Sigma 1.0 protocol version, while
all new applications are advised to use a newer version of the protocol: Sigma 1.1.
See SigmaAlgEx
for details on Sigma 1.1 protocol.
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.
Method Summary | |
---|---|
static SigmaAlg |
create()
Factory method for creating SigmaAlg 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. |
Methods inherited from class java.lang.Object |
---|
equals, hashCode, toString |
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.
CryptoException
- This instance was not initialized yet using the
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. The
getPublicKeySize
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.
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
- This instance was not initialized yet using the
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 the
dispose
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.
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
- This instance was not initialized yet using the
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 the
getParams
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 the
getParams
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.
CryptoException
- This instance was not initialized yet using the
getSecretKey
public abstract short getSecretKey(byte[] secretKey, short secretKeyIndex) throws CryptoException
- Obtains the secret key generated during the key exchange. The
getSecretKeySize
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 for Sigma 1.0 session, of before theprocessS2Message
method is called for Sigma 1.1 session).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.
CryptoException
- This instance was not initialized yet using the
getMacKey
public abstract short getMacKey(byte[] macKey, short macKeyIndex) throws CryptoException
- Obtains the MAC key generated during the key exchange. The
getMacKeySize
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 for Sigma 1.0 session, of before theprocessS2Message
method is called for Sigma 1.1 session).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 creating
SigmaAlg
instance for a new Sigma session.- Returns:
SigmaAlg
instance.