Intel

Developer Zone

SigmaAlg

com.intel.crypto

Class SigmaAlg

  • java.lang.Object
    • com.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 the create 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 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 and getMacKey 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

      Methods
      Modifier and Type Method and Description
      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 the dispose 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
      • 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 key
        publicKeyIndex - 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 the verifyParams 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 the dispose and initialize methods.
        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:
        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 getPublicKey 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 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:
        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 the verifyParams 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 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
      • 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 key
        secretKeyIndex - index in the key array
        Returns:
        The secret key length in bytes.
        Throws:
        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 verifyParams method is called for Sigma 1.0 session, of before the processS2Message 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
      • 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 key
        macKeyIndex - index in the key array
        Returns:
        The MAC key length in bytes.
        Throws:
        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 verifyParams method is called for Sigma 1.0 session, of before the processS2Message 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 the initialize method.
        CryptoException
      • create

        public static final SigmaAlg create()
        Factory method for creating SigmaAlg instance for a new Sigma session.
        Returns:
        SigmaAlg instance.