Intel

Developer Zone

AuthenticatedBlockCipherAlg

com.intel.crypto

Class AuthenticatedBlockCipherAlg

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


  • public abstract class AuthenticatedBlockCipherAlg
    extends java.lang.Object

    This abstract class represents an AES GCM algorithm ( AES-Galois/Counter Mode). GCM is a generic authenticated encryption block cipher mode.

    The following key types are supported by this class:

    • Key size of 128 or 256 bits which will be provided by the user, KEY_TYPE_AES_GCM.
    • Key size of 256 bits, platform bind KEY_TYPE_AES_GCM_256_PBIND.

    Before using the encryption/decryption methods of this class, the class must be configured with the following parameters:

    • Encryption key - using the setKey method.
    • IV - using the setIV method. And the following parameter is optional:
    • Additional Authenticated Data - using the setAdditionalAuthenticationData method.
    • Method Summary

      Methods
      Modifier and Type Method and Description
      abstract void clearAdditionalAuthenticationData()
      Clears the AdditionalAuthenticationData currently used by this instance.
      static AuthenticatedBlockCipherAlg create(short keyType)
      Factory method for creating a concrete instance.
      static short dataMigrationDecrypt(byte[] input, short inputIndex, short inputLength, byte[] tag, short tagIndex, short tagLength, byte[] iv, short ivIndex, short ivLength, byte[] additionalAuthenticationData, short additionalAuthenticationDataIndex, short additionalAuthenticationDataLength, byte[] output, short outputIndex)
      This function use to migrate encrypted data from SVN X to SVN Y (where Y > X) the function decrypts the provided input data using the previous Pbind key.
      abstract short decrypt(byte[] input, short inputIndex, short inputLength, byte[] tag, short tagIndex, short tagLength, byte[] output, short outputIndex)
      Decrypts the provided input data using the key currently stored by the instance.
      abstract short encrypt(byte[] input, short inputIndex, short inputLength, byte[] tag, short tagIndex, short tagLength, byte[] output, short outputIndex)
      Encrypts the provided input data using the key currently stored by the instance.
      abstract short getAdditionalAuthenticationData(byte[] additionalAuthenticationData, short additionalAuthenticationDataIndex)
      Obtains the AdditionalAuthenticationData currently used by this instance.
      abstract short getIV(byte[] iv, short ivIndex)
      Obtains the IV currently used by this instance.
      abstract short getKey(byte[] key, short keyIndex)
      Obtains the key currently used by this instance.
      abstract short getKeyType()
      returns the key type this instance was created with.
      abstract void setAdditionalAuthenticationData(byte[] additionalAuthenticationData, short additionalAuthenticationDataIndex, short additionalAuthenticationDataLength)
      Sets the AdditionalAuthenticationData to be used by this instance for encrypt/decrypt operations.
      abstract void setIV(byte[] iv, short ivIndex, short ivLength)
      Sets the IV to be used by this instance for encrypt/decrypt operations.
      abstract void setKey(byte[] key, short keyIndex, short keyLength)
      Sets the key to be used by this instance for encrypt/decrypt operations.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, toString
    • Field Detail

      • KEY_TYPE_AES_GCM

        public static final short KEY_TYPE_AES_GCM
        constant representing a 128/256 bit key which is provided by the user.
        See Also:
        Constant Field Values
      • KEY_TYPE_AES_GCM_256_PBIND

        public static final short KEY_TYPE_AES_GCM_256_PBIND
        constant representing a 256 bit PBIND AES_GCM key
        See Also:
        Constant Field Values
      • AES_GCM_IV_SIZE

        public static final short AES_GCM_IV_SIZE
        constant representing the only legal size(in bytes) of the IV.
        See Also:
        Constant Field Values
      • AES_GCM_MIN_TAG_SIZE_BYTES

        public static final short AES_GCM_MIN_TAG_SIZE_BYTES
        constant representing the minimal size(in bytes) of the authentication tag.
        See Also:
        Constant Field Values
      • AES_GCM_MAX_TAG_SIZE_BYTES

        public static final short AES_GCM_MAX_TAG_SIZE_BYTES
        constant representing the maximal size(in bytes) of the authentication tag.
        See Also:
        Constant Field Values
      • AES_GCM_KEY_SIZE_128

        public static final short AES_GCM_KEY_SIZE_128
        constant representing 128 bit key in bytes.
        See Also:
        Constant Field Values
      • AES_GCM_KEY_SIZE_256

        public static final short AES_GCM_KEY_SIZE_256
        constant representing 128 bit key in bytes.
        See Also:
        Constant Field Values
    • Method Detail

      • setKey

        public abstract void setKey(byte[] key,
                  short keyIndex,
                  short keyLength)
                             throws CryptoException
        Sets the key to be used by this instance for encrypt/decrypt operations. This method must be called before using any processing methods of this class. Calling this method will override any other key previously stored by this instance. Note: legal key size is 128/256 bits (16/32 bytes).
        Parameters:
        key - the key data
        keyIndex - index in the key array
        keyLength - key length in bytes
        Throws:
        IllegalParameterException - when the provided key size is illegal or not supported
        NotSupportedException - - if this instance was created with KEY_TYPE_AES_GCM_256_PBIND.
        CryptoException - in case of an internal error
      • getKey

        public abstract short getKey(byte[] key,
                   short keyIndex)
                              throws CryptoException
        Obtains the key currently used by this instance.
        Parameters:
        key - output array for the key
        keyIndex - index in the output array
        Returns:
        The returned key size in bytes.
        Throws:
        IllegalParameterException - when the provided parameter is illegal.
        NotInitializedException - if key was not set for this instance.
        NotSupportedException - - if this instance was created with KEY_TYPE_AES_GCM_256_PBIND.
        CryptoException
      • setIV

        public abstract void setIV(byte[] iv,
                 short ivIndex,
                 short ivLength)
                            throws CryptoException
        Sets the IV to be used by this instance for encrypt/decrypt operations. This method must be called before using any processing methods of this class. Calling this method will override any other IV previously stored by this instance. Note: legal key size is 16 bytes
        Parameters:
        iv - the IV data
        ivIndex - index in the IV array
        ivLength - IV length in bytes
        Throws:
        IllegalParameterException - when the provided IV size is illegal or not supported
        CryptoException - in case of an internal error
      • getIV

        public abstract short getIV(byte[] iv,
                  short ivIndex)
                             throws CryptoException
        Obtains the IV currently used by this instance.
        Parameters:
        iv - output array for the IV
        ivIndex - index in the output array
        Returns:
        The returned IV size in bytes.
        Throws:
        IllegalParameterException - when the provided parameter is illegal.
        NotInitializedException - if IV was not set for this instance.
        CryptoException
      • setAdditionalAuthenticationData

        public abstract void setAdditionalAuthenticationData(byte[] additionalAuthenticationData,
                                           short additionalAuthenticationDataIndex,
                                           short additionalAuthenticationDataLength)
                                                      throws CryptoException
        Sets the AdditionalAuthenticationData to be used by this instance for encrypt/decrypt operations. Calling this method will override any other AdditionalAuthenticationData previously stored by this instance. Note: This parameter is optional.
        Parameters:
        additionalAuthenticationData - the additionalAuthenticationData data
        additionalAuthenticationDataIndex - index in the additionalAuthenticationData array
        additionalAuthenticationDataLength - additionalAuthenticationData length in bytes
        Throws:
        IllegalParameterException - when the provided parameter is illegal.
        CryptoException - in case of an internal error
      • clearAdditionalAuthenticationData

        public abstract void clearAdditionalAuthenticationData()
        Clears the AdditionalAuthenticationData currently used by this instance.
      • getAdditionalAuthenticationData

        public abstract short getAdditionalAuthenticationData(byte[] additionalAuthenticationData,
                                            short additionalAuthenticationDataIndex)
                                                       throws CryptoException
        Obtains the AdditionalAuthenticationData currently used by this instance.
        Parameters:
        additionalAuthenticationData - output array for the additionalAuthenticationData
        additionalAuthenticationDataIndex - index in the output array
        Returns:
        The returned additionalAuthenticationData size in bytes.
        Throws:
        IllegalParameterException - when the provided parameter is illegal.
        NotInitializedException - if additionalAuthenticationData was not set for this instance.
        CryptoException
      • encrypt

        public abstract short encrypt(byte[] input,
                    short inputIndex,
                    short inputLength,
                    byte[] tag,
                    short tagIndex,
                    short tagLength,
                    byte[] output,
                    short outputIndex)
                               throws CryptoException
        Encrypts the provided input data using the key currently stored by the instance.
        Parameters:
        input - the plain text data to encrypt
        inputIndex - index in the input array
        inputLength - input data length
        tag - the authentication tag
        tagIndex - index in the tag array
        tagLength - tag data length
        output - an array to hold the encrypted data. The size must not be less than the size of the input
        outputIndex - index in the outputIndex 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
        ComputationException - if encryption operation failed due to mismatching parameters
        CryptoException - if an internal error occurred
      • decrypt

        public abstract short decrypt(byte[] input,
                    short inputIndex,
                    short inputLength,
                    byte[] tag,
                    short tagIndex,
                    short tagLength,
                    byte[] output,
                    short outputIndex)
                               throws CryptoException
        Decrypts the provided input data using the key currently stored by the instance.
        Parameters:
        input - the cipher text data to encrypt
        inputIndex - index in the input array
        inputLength - input data length
        tag - the authentication tag
        tagIndex - index in the tag array
        tagLength - tag data length
        output - an array to hold the decrypted data. The size must not be less than the size of the input
        outputIndex - index in the outputIndex 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 encryption)
        IllegalParameterException - when one or more of the input parameters are illegal
        ComputationException - if decryption operation failed due to mismatching parameters
        CryptoException - if an internal error occurred
      • dataMigrationDecrypt

        public static short dataMigrationDecrypt(byte[] input,
                                 short inputIndex,
                                 short inputLength,
                                 byte[] tag,
                                 short tagIndex,
                                 short tagLength,
                                 byte[] iv,
                                 short ivIndex,
                                 short ivLength,
                                 byte[] additionalAuthenticationData,
                                 short additionalAuthenticationDataIndex,
                                 short additionalAuthenticationDataLength,
                                 byte[] output,
                                 short outputIndex)
                                          throws CryptoException
        This function use to migrate encrypted data from SVN X to SVN Y (where Y > X) the function decrypts the provided input data using the previous Pbind key.
        Parameters:
        input - the cipher text data to encrypt
        inputIndex - index in the input array
        inputLength - input data length
        tag - the authentication tag
        tagIndex - index in the tag array
        tagLength - tag data length
        iv - the IV data
        ivIndex - index in the IV array
        ivLength - IV length in bytes
        additionalAuthenticationData - the additionalAuthenticationData data
        additionalAuthenticationDataIndex - index in the additionalAuthenticationData array
        additionalAuthenticationDataLength - additionalAuthenticationData length in bytes
        output - an array to hold the decrypted data. The size must not be less than the size of the input
        outputIndex - index in the outputIndex array
        Returns:
        the number of bytes written to the output array.
        Throws:
        NotInitializedException - if no previous pbind key exist
        IllegalParameterException - when one or more of the input parameters are illegal
        ComputationException - if decryption operation failed due to mismatching parameters
        CryptoException - if an internal error occurred
      • getKeyType

        public abstract short getKeyType()
        returns the key type this instance was created with.
        Returns:
        The key type, one of KEY_TYPE_AES_GCM_
      • create

        public static final AuthenticatedBlockCipherAlg create(short keyType)
        Factory method for creating a concrete instance.
        Parameters:
        keyType - the key type that the algorithm will use should be one of KEY_TYPE_AES_GCM_
        Returns:
        AuthenticatedBlockCipherAlg instance.
        Throws:
        NotSupportedException - if given keyType is not supported.
        CryptoException - if an internal error occurred