Intel

Developer Zone

EccAlg

com.intel.crypto

Class EccAlg

  • java.lang.Object
    • com.intel.crypto.EccAlg


  • public abstract class EccAlg
    extends java.lang.Object

    This abstract class represents ECC algorithm set including key-generation, signing and verifying. This class allows the instantiation of an ECC implementation class through the create() factory method.

    NOTE:
    The ECC algorithm implementation supports the following curve types only:

    • The secp256k1 curve is a 256-bit elliptic curve over finite field Fp, based on "SEC 2: Recommended Elliptic Curve Domain Parameters" Version 1.0 September 20, 2000.
    • The ECC P256 curve is a 256-bit elliptic curve over finite field Fp, based on "SEC 2: Recommended Elliptic Curve Domain Parameters" Version 1.0 September 20, 2000.
    • Supported on Broxton platforms only: The ECC P384 curve is a 384-bit elliptic curve over finite field Fp, based on "SEC 2: Recommended Elliptic Curve Domain Parameters" Version 1.0 September 20, 2000.

    The following key generation and signing algorithms are supported by this class:
    • ECC keys generation
    • ECC signature using the ECDSA algorithm
    • Supported on Broxton platforms only: ECIES encryption scheme

    The default hash algorithm is SHA-256 HashAlg.HASH_TYPE_SHA256.
    • Nested Class Summary

      Nested Classes
      Modifier and Type Class and Description
      static class EccAlg.CurvePoint
      This class represents a generic uncompressed point (x, y) on an elliptic curve.
      static class EccAlg.CurveProperties
      This class represents elliptic curve properties, namely the tuple T = (p, a, b, G, n, h).
    • Field Summary

      Fields
      Modifier and Type Field and Description
      static short ECC_CURVE_TYPE_P256
      The ECC P256 curve is a 256-bit elliptic curve over finite field Fp.
      static short ECC_CURVE_TYPE_P384
      The ECC P384 curve is a 384-bit elliptic curve over finite field Fp.
      static short ECC_CURVE_TYPE_SECP256K1
      The ECC secp256k1 curve is a 256-bit elliptic curve over finite field Fp.
    • Method Summary

      Methods
      Modifier and Type Method and Description
      abstract void calculatePublicKey(EccAlg.CurvePoint publicKey)
      Calculates the public key based on the private key scalar set in the instance and stores it into the provided publicKey.
      abstract void clear()
      Clears all of the optional data that has been set for this instance (shared information 1, shared information 2)
      static EccAlg create(short curveType)
      Factory method for creating a concrete instance.
      abstract short decrypt(byte[] input, short inputIndex, short inputLength, byte[] r, short rIndex, short rLength, byte[] d, short dIndex, short dLength, byte[] output, short outputIndex)
      Decrypts the provided input data using the key currently stored by the instance using the ECIES algorithm.
      abstract short encrypt(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex, byte[] r, short rIndex, byte[] d, short dIndex)
      Encrypts the provided input data using the key currently stored by the instance using the ECIES algorithm.
      abstract void generateKeys()
      Generates ECC public and private keys.
      abstract EccAlg.CurveProperties getCurveProperties()
      Returns the object that represents the properties of the instance's curve.
      abstract short getCurveType()
      Return the ECC curve type.
      abstract short getDSize()
      Get the size of D parameter used in encrypt and decrypt methods.
      abstract short getHashAlg()
      Obtains the hash algorithm which is currently used by this instance during signing operations.
      abstract void getKeys(EccAlg.CurvePoint publicKey, byte[] privateKey, short privateKeyIndex)
      Obtains the ECC public and private keys for this instance.
      abstract short getPrivateKeySize()
      Returns the ECC private key scalar length in bytes.
      abstract void getPublicKey(EccAlg.CurvePoint publicKey)
      Obtains the ECC public key for this instance.
      abstract short getPublicKeySize()
      Returns the ECC public key point coordinate length in bytes.
      abstract short getRSize()
      Get the size of R parameter used in encrypt and decrypt methods.
      abstract short getSharedInformation1(byte[] sharedInformation1, short sharedInformation1Index)
      Obtains the shared information 1 data currently used by this instance.
      abstract short getSharedInformation2(byte[] sharedInformation2, short sharedInformation2Index)
      Obtains the shared information 2 data currently used by this instance.
      abstract short getSignatureSize()
      Returns the signature length in bytes of the curve currently used in the instance.
      abstract void setHashAlg(short hashAlgType)
      Sets the hash algorithm to be used by this instance during signing operations.
      abstract void setKeys(EccAlg.CurvePoint publicKey, byte[] privateKey, short privateKeyIndex, short privateKeyLength)
      Sets the ECC public and private keys.
      abstract void setPrivateKey(byte[] privateKey, short privateKeyIndex, short privateKeyLength)
      Sets the ECC private key.
      abstract void setPublicKey(EccAlg.CurvePoint publicKey)
      Sets the ECC public key.
      abstract void setSharedInformation1(byte[] sharedInformation1, short sharedInformation1Index, short sharedInformation1Length)
      Sets the shared information 1 data to be used by this instance for encrypt/decrypt operations.
      abstract void setSharedInformation2(byte[] sharedInformation2, short sharedInformation2Index, short sharedInformation2Length)
      Sets the shared information 2 data to be used by this instance for encrypt/decrypt operations.
      abstract void signComplete(byte[] data, short dataIndex, short dataLength, byte[] signatureR, short signatureRIndex, byte[] signatureS, short signatureSIndex)
      Signs the provided input data using the key and hash algorithm currently stored by the instance.
      abstract void signHash(byte[] hash, short hashIndex, short hashLength, byte[] signatureR, short signatureRIndex, byte[] signatureS, short signatureSIndex)
      Signs the provided already hashed data using the key currently stored in the instance.
      abstract boolean validatePublicKey(EccAlg.CurvePoint publicKey)
      Validates the provided public key by verifying that it represents a legal point on the elliptic curve.
      abstract boolean verifyComplete(byte[] data, short dataIndex, short dataLength, byte[] signatureR, short signatureRIndex, short signatureRLength, byte[] signatureS, short signatureSIndex, short signatureSLength)
      Verifies the signature on the provided input data using the key and hash algorithm currently stored by the instance.
      abstract boolean verifyHash(byte[] hash, short hashIndex, short hashLength, byte[] signatureR, short signatureRIndex, short signatureRLength, byte[] signatureS, short signatureSIndex, short signatureSLength)
      Verifies the signature on the provided already hashed input data using the key currently stored in the instance.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, toString
    • Field Detail

      • ECC_CURVE_TYPE_SECP256K1

        public static final short ECC_CURVE_TYPE_SECP256K1
        The ECC secp256k1 curve is a 256-bit elliptic curve over finite field Fp.
        See Also:
        Constant Field Values
      • ECC_CURVE_TYPE_P256

        public static final short ECC_CURVE_TYPE_P256
        The ECC P256 curve is a 256-bit elliptic curve over finite field Fp.
        See Also:
        Constant Field Values
      • ECC_CURVE_TYPE_P384

        public static final short ECC_CURVE_TYPE_P384
        The ECC P384 curve is a 384-bit elliptic curve over finite field Fp.
        See Also:
        Constant Field Values
    • Method Detail

      • generateKeys

        public abstract void generateKeys()
                                   throws CryptoException
        Generates ECC public and private keys. Keys are generated according to the curve type and are stored internally in the instance. Calling this method will override any other key (public or private) previously stored by this instance.
        Throws:
        ComputationException - if the operation did not complete successfully due to errors returned from the crypto engine
        CryptoException - if an unexpected error occurred
      • setPrivateKey

        public abstract void setPrivateKey(byte[] privateKey,
                         short privateKeyIndex,
                         short privateKeyLength)
                                    throws CryptoException
        Sets the ECC private key. Calling this method will override any other private key previously stored by this instance. The key validity is not checked.
        Parameters:
        privateKey - the ECC private key scalar
        privateKeyIndex - index in the privateKey array
        privateKeyLength - private key length in bytes should be equal to getPrivateKeySize()
        Throws:
        IllegalParameterException - if the privateKeyLength doesn't match the size returned by getPrivateKeySize() or input is invalid
        CryptoException
      • setKeys

        public abstract void setKeys(EccAlg.CurvePoint publicKey,
                   byte[] privateKey,
                   short privateKeyIndex,
                   short privateKeyLength)
                              throws CryptoException
        Sets the ECC public and private keys. Calling this method will override any other key (public or private) previously stored by this instance. The key-pair validity is checked based on the elliptic curve.
        Parameters:
        publicKey - the ECC public key. Should contain valid X and Y coordinates buffers with size getPublicKeySize()
        privateKey - the ECC private key scalar
        privateKeyIndex - index in the privateKey array
        privateKeyLength - private key length in bytes should be equal to getPrivateKeySize()
        Throws:
        IllegalParameterException - if the lengths of publicKey.x or publicKey.y don't match the size returned by getPublicKeySize() or privateKeyLength doesn't match the size returned by getPrivateKeySize() or provided keys are invalid
        ComputationException - if the operation did not complete successfully due to errors returned from the crypto engine
        CryptoException - if an unexpected error occurred
      • getCurveType

        public abstract short getCurveType()
        Return the ECC curve type.
        Returns:
        returns the ECC curve type used by this instance.
      • getPublicKeySize

        public abstract short getPublicKeySize()
        Returns the ECC public key point coordinate length in bytes.
        Returns:
        the ECC public key point coordinate according to the curve type used by this instance.
      • getPrivateKeySize

        public abstract short getPrivateKeySize()
        Returns the ECC private key scalar length in bytes.
        Returns:
        the ECC private key length according to the curve type used by this instance.
      • getKeys

        public abstract void getKeys(EccAlg.CurvePoint publicKey,
                   byte[] privateKey,
                   short privateKeyIndex)
                              throws CryptoException
        Obtains the ECC public and private keys for this instance. The getPublicKeySize() method can be used to retrieve the required size for publicKey.x and publicKey.y coordinate buffers. The getPrivateKeySize() can be used to retrieve the required size for the privateKey buffer.
        Parameters:
        publicKey - the ECC public key. should contain X coordinate and the Y coordinate buffers with size getPublicKeySize()
        privateKey - an array to hold the ECC private key with the correct size
        privateKeyIndex - index in the private key array
        Throws:
        NotInitializedException - if the keys were not set or generated for this instance
        IllegalParameterException - if the lengths of publicKey.x or publicKey.y don't match the size returned by getPublicKeySize() or input is invalid
        CryptoException
      • signComplete

        public abstract void signComplete(byte[] data,
                        short dataIndex,
                        short dataLength,
                        byte[] signatureR,
                        short signatureRIndex,
                        byte[] signatureS,
                        short signatureSIndex)
                                   throws CryptoException
        Signs the provided input data using the key and hash algorithm currently stored by the instance. The method getSignatureSize() provides the required size for the signatureR and signatureS buffers. The default hash algorithm is SHA-526 HashAlg.HASH_TYPE_SHA256.
        Parameters:
        data - the plain data to sign
        dataIndex - index in the data array
        dataLength - data length in bytes
        signatureR - the R signature buffer to hold the data must be at least getSignatureSize() length
        signatureRIndex - index in the R signature buffer
        signatureS - the S signature buffer to hold the data must be at least getSignatureSize() length
        signatureSIndex - index in the S signature buffer
        Throws:
        NotInitializedException - if this instance is not configured correctly in order to generate a signature. For example, if the private key or the hash algorithm were not set for this instance
        ComputationException - if the operation did not complete successfully due to errors returned from the crypto engine
        CryptoException - if an unexpected error occurred
        IllegalParameterException - if the lengths of signatureR or signatureS are less than the size returned by getSignatureSize() or input is invalid
      • verifyComplete

        public abstract boolean verifyComplete(byte[] data,
                             short dataIndex,
                             short dataLength,
                             byte[] signatureR,
                             short signatureRIndex,
                             short signatureRLength,
                             byte[] signatureS,
                             short signatureSIndex,
                             short signatureSLength)
                                        throws CryptoException
        Verifies the signature on the provided input data using the key and hash algorithm currently stored by the instance.
        Parameters:
        data - The data to verify
        dataIndex - index in the data array
        dataLength - data length in bytes
        signatureR - The R signature buffer to verify
        signatureRIndex - index in the R signature buffer
        signatureRLength - R signature buffer length in bytes
        signatureS - The S signature buffer to verify
        signatureSIndex - index in the S signature buffer
        signatureSLength - S signature buffer length in bytes
        Throws:
        NotInitializedException - if this instance is not configured correctly in order to generate a signature. For example, if the public key or the hash algorithm were not set for this instance
        IllegalParameterException - signatureLength doesn't match getSignatureSize() or input invalid
        ComputationException - if the operation did not complete successfully due to errors returned from the crypto engine
        CryptoException - if an unexpected error occurred
      • signHash

        public abstract void signHash(byte[] hash,
                    short hashIndex,
                    short hashLength,
                    byte[] signatureR,
                    short signatureRIndex,
                    byte[] signatureS,
                    short signatureSIndex)
                               throws CryptoException
        Signs the provided already hashed data using the key currently stored in the instance.
        Parameters:
        hash - the input data to sign
        hashIndex - index in the input array
        hashLength - input data length must be no larger than getPrivateKeySize()
        signatureR - the R signature buffer to hold the data must be at least getSignatureSize() length
        signatureRIndex - index in the R signature buffer
        signatureS - the S signature buffer to hold the data must be at least getSignatureSize()length
        signatureSIndex - index in the S signature buffer
        Throws:
        NotInitializedException - if this instance is not configured correctly in order to generate a signature. For example, the private key or the public key is not set.
        IllegalParameterException - if the lengths of signatureR or signatureS are less than the size returned by getSignatureSize() or hash is bigger than getPrivateKeySize() or input is invalid
        ComputationException - if the operation did not complete successfully due to errors returned from the crypto engine
        CryptoException - if an unexpected error occurred
      • verifyHash

        public abstract boolean verifyHash(byte[] hash,
                         short hashIndex,
                         short hashLength,
                         byte[] signatureR,
                         short signatureRIndex,
                         short signatureRLength,
                         byte[] signatureS,
                         short signatureSIndex,
                         short signatureSLength)
                                    throws CryptoException
        Verifies the signature on the provided already hashed input data using the key currently stored in the instance.
        Parameters:
        hash - the hash that was signed
        hashIndex - index in the hash array
        hashLength - hash data length
        signatureR - The R signature buffer to verify
        signatureRIndex - index in the R signature buffer
        signatureRLength - R signature buffer length in bytes
        signatureS - The S signature buffer to verify
        signatureSIndex - index in the S signature buffer
        signatureSLength - S signature buffer length in bytes
        Returns:
        true if the signature verified successfully, false otherwise.
        Throws:
        NotInitializedException - if this instance is not configured correctly in order to verify the signature. For example, the public key.
        IllegalParameterException - if hash doesn't match the size returned by getPrivateKeySize() or signatureLengths don't match getSignatureSize()
        ComputationException - if the operation did not complete successfully due to errors returned from the crypto engine
        CryptoException - if an unexpected error occurred
      • validatePublicKey

        public abstract boolean validatePublicKey(EccAlg.CurvePoint publicKey)
                                           throws CryptoException
        Validates the provided public key by verifying that it represents a legal point on the elliptic curve.
        Parameters:
        publicKey - the public key to verify.
        Returns:
        return true iff publicKey is valid false otherwise.
        Throws:
        IllegalParameterException - if size of publicKey.x or publicKey.y don't match the size returned by getPublicKeySize() or the provided input is illegal
        CryptoException - if an unexpected error occurred
        ComputationException - if the operation did not complete successfully due to errors returned from the crypto engine
      • calculatePublicKey

        public abstract void calculatePublicKey(EccAlg.CurvePoint publicKey)
                                         throws CryptoException
        Calculates the public key based on the private key scalar set in the instance and stores it into the provided publicKey.
        Parameters:
        publicKey - the output ECC public key. Should contain valid X and Y coordinates buffers with size getPublicKeySize()
        Throws:
        NotInitializedException - if this instance is not configured correctly in order to calculate the public key. For example, if the private key is not set for this instance
        IllegalParameterException - if size of publicKey.x or publicKey.y don't match the size returned by getPublicKeySize() or the provided input is illegal
        CryptoException - if an unexpected error occurred
        ComputationException - if the operation did not complete successfully due to errors returned from the crypto engine
      • getSignatureSize

        public abstract short getSignatureSize()
        Returns the signature length in bytes of the curve currently used in the instance. (Note: this size is for R and S)
      • setHashAlg

        public abstract void setHashAlg(short hashAlgType)
                                 throws CryptoException
        Sets the hash algorithm to be used by this instance during signing operations.
        Parameters:
        hashAlgType - the hash algorithm that will be used during signing operations, see HashAlg.HASH_TYPE_XXX definitions for possible values
        Throws:
        NotSupportedException - if the provided hashing algorithm is not supported.
        CryptoException
      • getHashAlg

        public abstract short getHashAlg()
        Obtains the hash algorithm which is currently used by this instance during signing operations.
        Returns:
        The hash algorithm that is used during signing operations, see HashAlg.HASH_TYPE_XXX definitions for possible values
      • getCurveProperties

        public abstract EccAlg.CurveProperties getCurveProperties()
        Returns the object that represents the properties of the instance's curve.
        Returns:
        a EccAlg.CurveProperties object that represents the curve's properties.
      • setSharedInformation1

        public abstract void setSharedInformation1(byte[] sharedInformation1,
                                 short sharedInformation1Index,
                                 short sharedInformation1Length)
        Sets the shared information 1 data to be used by this instance for encrypt/decrypt operations. Note that once set the new associated data is used for all future encrypt/decrypt operations until the associated data is reset to a new value (by calling the setSharedInformation1 method again). This optional data usage can be removed by calling the clear method.
        Parameters:
        sharedInformation1 - an array consists of the shared information 1 data
        sharedInformation1Index - the index within the provided array
        sharedInformation1Length - the length of the shared information 1 data
        Throws:
        IllegalParameterException - when the provided shared information 1 data is invalid or the provided associated data size is illegal
      • setSharedInformation2

        public abstract void setSharedInformation2(byte[] sharedInformation2,
                                 short sharedInformation2Index,
                                 short sharedInformation2Length)
        Sets the shared information 2 data to be used by this instance for encrypt/decrypt operations. Note that once set the new associated data is used for all future encrypt/decrypt operations until the associated data is reset to a new value (by calling the setSharedInformation2 method again). This optional data usage can be removed by calling the clear method.
        Parameters:
        sharedInformation2 - an array consists of the shared information 2 data
        sharedInformation2Index - the index within the provided array
        sharedInformation2Length - the length of the shared information 2 data
        Throws:
        IllegalParameterException - when the provided shared information 2 data is invalid or the provided associated data size is illegal
      • getSharedInformation1

        public abstract short getSharedInformation1(byte[] sharedInformation1,
                                  short sharedInformation1Index)
        Obtains the shared information 1 data currently used by this instance.
        Parameters:
        sharedInformation1 - output array for the shared information 1 data
        sharedInformation1Index - index in the output array
        Returns:
        The returned shared information 1 data size in bytes.
        Throws:
        NotInitializedException - if shared information 1 data was not set for this instance.
      • getSharedInformation2

        public abstract short getSharedInformation2(byte[] sharedInformation2,
                                  short sharedInformation2Index)
        Obtains the shared information 2 data currently used by this instance.
        Parameters:
        sharedInformation2 - output array for the shared information 2 data
        sharedInformation2Index - index in the output array
        Returns:
        The returned shared information 2 data size in bytes.
        Throws:
        NotInitializedException - if shared information 2 data was not set for this instance.
      • encrypt

        public abstract short encrypt(byte[] input,
                    short inputIndex,
                    short inputLength,
                    byte[] output,
                    short outputIndex,
                    byte[] r,
                    short rIndex,
                    byte[] d,
                    short dIndex)
                               throws CryptoException
        Encrypts the provided input data using the key currently stored by the instance using the ECIES algorithm.
        Parameters:
        input - the input data to encrypt
        inputIndex - index in the input array
        inputLength - input data length
        output - an array to hold the encrypted data. The size must not be less than the size of the input data
        outputIndex - index in the output array.
        r - an array to hold the R parameter. The size of R parameter can be retrieved by getRSize. r will be prefixed with 0x04 since point compression is not used.
        rIndex - index in the r array
        d - an array to hold the D parameter. The size of D parameter can be retrieved by getDSize
        dIndex - index in the d array
        Returns:
        the number of bytes written to the output array.
        Throws:
        NotInitializedException - if a required encryption parameter is not configured (for example, the key to be used for encryption)
        IllegalParameterException - when one or more of the input parameters are illegal
        NotSupportedException - if the hash algorithm is different than HashAlg.HASH_TYPE_SHA1 and HashAlg.HASH_TYPE_SHA256
        CryptoException - if an internal error occurred
      • decrypt

        public abstract short decrypt(byte[] input,
                    short inputIndex,
                    short inputLength,
                    byte[] r,
                    short rIndex,
                    short rLength,
                    byte[] d,
                    short dIndex,
                    short dLength,
                    byte[] output,
                    short outputIndex)
                               throws CryptoException
        Decrypts the provided input data using the key currently stored by the instance using the ECIES algorithm.
        Parameters:
        input - the input data to decrypt
        inputIndex - index in the input data array
        inputLength - input data array length
        r - the R data. r must be prefixed with 0x04 since point compression is not used.
        rIndex - index in the r array
        d - the D data
        dIndex - index in the d array
        output - an array to hold the decrypted data. The size must not be less than the size of the cipher text
        outputIndex - index in the output array
        Returns:
        the number of bytes written to the output array
        Throws:
        NotInitializedException - if a required decryption parameter is not configured (for example, the key to be used for decryption)
        IllegalParameterException - when one or more of the input parameters are illegal
        NotSupportedException - if the hash algorithm is different than HashAlg.HASH_TYPE_SHA1 and HashAlg.HASH_TYPE_SHA256
        CryptoException - if an internal error occurred
      • clear

        public abstract void clear()
        Clears all of the optional data that has been set for this instance (shared information 1, shared information 2)
      • getRSize

        public abstract short getRSize()
        Get the size of R parameter used in encrypt and decrypt methods.
        Returns:
        The size of R parameter according to the ECC curve type
        Throws:
        NotSupportedException - if the instance was created with an unsupported curve type
      • getDSize

        public abstract short getDSize()
        Get the size of D parameter used in encrypt and decrypt methods.
        Returns:
        The size of D parameter
      • create

        public static final EccAlg create(short curveType)
                                   throws CryptoException
        Factory method for creating a concrete instance.
        Parameters:
        curveType - the ECC curve type - one of EccAlg.ECC_CURVE_TYPE_XXX values
        Returns:
        EccAlg instance.
        Throws:
        IllegalParameterException - if the curveType is unsupported
        CryptoException