Intel

Developer Zone

SigmaAlgEx

com.intel.crypto

Class 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.

    Note that max verifier certificate chain length supported is 5.

    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.

    • Constructor Summary

      Constructors
      Constructor and Description
      SigmaAlgEx()

    • Method Summary

      Methods
      Modifier and Type Method and Description
      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 boolean getProperty(int propertyId)
      Returns the value of a specific algorithm property
      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 void setProperty(int propertyId, boolean state)
      Sets a property that modifies the algorithm behavior
      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 java.lang.Object

        equals, getClass, 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

      • 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 is 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

    • 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:
        • 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).
        OperationFailedException - if the platform keys are revoked
        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.

      • 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_XYZ
        state - determines whether the property is enabled or disabled
        Throws:
        IllegalParameterException - if propertyId is unknown
        NotInitializedException - if this instance was not initialized
        CryptoException - 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_EX_PROPERTY_XYZ
        Returns:
        Returns whether a specific property is disabled or enabled
        Throws:
        IllegalParameterException - if propertyId is unknown
        NotInitializedException - if this instance was not initialized
        CryptoException - for any other error

      • 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.
Back to top

Hardware Developers

  • Resource and Design Center
  • Shop Intel
  • Firmware

    • Open Source

  • 01.org
  • Clear Linux* Project
  • Zephyr Project

    • Manage Your Tools

  • Download Center
  • Online Service Center
  • Registration Center

    • Stay Up-to-Date

  • Forums
  • Recent Updates
  • Subscribe to our YouTube Channel
  • Newsletter Archives

    • Terms of Use
    *Trademarks
    Privacy
    Cookies