Intel

Developer Zone

SymmetricBlockCipherAlg

com.intel.crypto

Class SymmetricBlockCipherAlg

  • java.lang.Object
    • com.intel.crypto.SymmetricBlockCipherAlg
  • All Implemented Interfaces:
    Cipher, SequentialCipher


    public abstract class SymmetricBlockCipherAlg
    extends java.lang.Object
    implements SequentialCipher

    This abstract class represents a symmetric encryption algorithm. This class implements the cipher interface and creates specific encryption algorithm implementations using the create factory method. In addition, this class supports encryption or decryption of input data in several transactions and maintains the intermediate internal state between them (see the encryptUpdate and decryptUpdate methods for more details).

    The following encryption methods are supported by this class:

    • AES with 128 and 256 bit keys in CBC, ECB and CTR modes.
    • DES with 64, 128 and 192 bit keys in CBC, ECB and CTR modes.
    • AES with 128 and 256 Platform Binding key in CBC mode.

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

    • Encryption key - using the setKey method (if not using an instance that implements the Platform Binding algorithm).
    • IV - using the setIV method for algorithms that work in CBC or CTR mode. Note that in CBC mode, calling the setIV method is optional and the the default IV value is 0.
    • Method Summary

      Methods
      Modifier and Type Method and Description
      static SymmetricBlockCipherAlg create(short algType)
      Factory method for creating a concrete instance.
      abstract short decryptComplete(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex)
      Decrypts the provided input data using the key currently stored by the instance.
      abstract short encryptComplete(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex)
      Encrypts the provided input data using the key currently stored by the instance.
      short getAlgType()
      Returns the algorithm type implemented by this instance.
      abstract short getBlockSize()
      Returns the block size (in bytes) for this algorithm instance.
      abstract short getKey(byte[] keyArray, short keyIndex)
      Obtains the key currently used by this instance.
      abstract short getKeySize()
      Returns the key size (in bytes) for this algorithm instance.
      abstract void setIV(byte[] ivArray, short ivIndex, short ivLength)
      Sets the IV to be used by this instance for encrypt/decrypt operations.
      abstract void setKey(byte[] keyArray, 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, hashCode, toString
    • Field Detail

      • ALG_TYPE_AES_CBC

        public static final short ALG_TYPE_AES_CBC
        AES encryption with 128 or 256 bit key in CBC mode. The block size for this algorithm type is 16 bytes. The IV size for this algorithm type is 16 bytes. The default IV value, if not set, is 0.
        See Also:
        Constant Field Values
      • ALG_TYPE_AES_ECB

        public static final short ALG_TYPE_AES_ECB
        AES encryption with 128 or 256 bit key in ECB mode. The block size for this algorithm type is 16 bytes. No IV must be configured while using this algorithm type.
        See Also:
        Constant Field Values
      • ALG_TYPE_AES_CTR

        public static final short ALG_TYPE_AES_CTR
        AES encryption with 128 or 256 bit key in CTR mode. The block size for this algorithm type is 16 bytes. The initial value of the counter for this algorithm must be set to 16 bytes using the setIV method.
        See Also:
        Constant Field Values
      • ALG_TYPE_PBIND_AES_128_CBC

        public static final short ALG_TYPE_PBIND_AES_128_CBC
        AES encryption with 128 bit Platform Binding key in CBC mode. The block size for this algorithm type is 16 bytes. The IV size for this algorithm type is 16 bytes. The default IV value, if not set, is 0. This algorithm type does not require a key to be configured using setKey method. The Platform Binding key is generated internally by the algorithm implementation, unique for each application and each platform, and cannot be accessed through any of the external interfaces. Note that different instances of the same application will share the same Platform Binding key. This algorithm type can be used by applications to encrypt data saved in external storage (for example, the hard drive).
        See Also:
        Constant Field Values
      • ALG_TYPE_PBIND_AES_256_CBC

        public static final short ALG_TYPE_PBIND_AES_256_CBC
        AES encryption with 256 bit Platform Binding key in CBC mode. The block size for this algorithm type is 16 bytes. The IV size for this algorithm type is 16 bytes. The default IV value, if not set, is 0. This algorithm type does not require a key to be configured using setKey method. The Platform Binding key is generated internally by the algorithm implementation, unique for each application and each platform, and cannot be accessed through any of the external interfaces. Note that different instances of the same application will share the same Platform Binding key. This algorithm type can be used by applications to encrypt data saved in external storage (for example, the hard drive).
        See Also:
        Constant Field Values
      • ALG_TYPE_DES_CBC

        public static final short ALG_TYPE_DES_CBC
        DES encryption with 64, 128 or 192 bit key in CBC mode. The block size for this algorithm type is 8 bytes. The IV size for this algorithm type is 8 bytes. The default IV value, if not set, is 0.
        See Also:
        Constant Field Values
      • ALG_TYPE_DES_ECB

        public static final short ALG_TYPE_DES_ECB
        DES encryption with 64, 128 or 192 bit key in ECB mode. The block size for this algorithm type is 8 bytes. No IV must be configured while using this algorithm type.
        See Also:
        Constant Field Values
      • ALG_TYPE_DES_CTR

        public static final short ALG_TYPE_DES_CTR
        DES encryption with 64, 128 or 192 bit key in CTR mode. The block size for this algorithm type is 8 bytes. The initial value of the counter for this algorithm must be set to 8 bytes using the setIV method.
        See Also:
        Constant Field Values
      • AES_BLOCK_SIZE

        public static final short AES_BLOCK_SIZE
        AES block size in bytes.
        See Also:
        Constant Field Values
      • DES_BLOCK_SIZE

        public static final short DES_BLOCK_SIZE
        DES block size in bytes.
        See Also:
        Constant Field Values
    • Method Detail

      • getBlockSize

        public abstract short getBlockSize()
        Returns the block size (in bytes) for this algorithm instance.
        Returns:
        Block size in bytes.
      • getAlgType

        public short getAlgType()
        Returns the algorithm type implemented by this instance.
        Returns:
        The algorithm used by this instance, see ALG_TYPE_... definitions above for possible values.
      • setKey

        public abstract void setKey(byte[] keyArray,
                  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 as well as reset any sequence of operations started before.
        Parameters:
        keyArray - the key data
        keyIndex - index in the key array
        keyLength - key length in bytes
        Throws:
        NotSupportedException - when called for an instance of Platform Binding algorithm type
        IllegalParameterException - when the provided key size is illegal or not supported
        CryptoException
      • getKey

        public abstract short getKey(byte[] keyArray,
                   short keyIndex)
                              throws CryptoException
        Obtains the key currently used by this instance.
        Parameters:
        keyArray - output array for the key
        keyIndex - index in the output array
        Returns:
        The returned key size in bytes.
        Throws:
        NotInitializedException - if key was not set for this instance.
        NotSupportedException - when called for an instance of Platform Binding algorithm type.
        CryptoException
      • setIV

        public abstract void setIV(byte[] ivArray,
                 short ivIndex,
                 short ivLength)
                            throws CryptoException
        Sets the IV to be used by this instance for encrypt/decrypt operations. Note that once set the new IV value is used for all future encrypt/decrypt operations until the IV is reset to a new value (by calling the setIV method again). In addition, calling this method resets any sequence of operations that has already started. This method is required only for algorithm types that implement CBC or CTR mode.
        Parameters:
        ivArray - the IV data
        ivIndex - index in the IV array
        ivLength - IV length in bytes
        Throws:
        NotSupportedException - when called for an instance that does not support IV (for example, ECB cipher)
        IllegalParameterException - when the provided IV size is illegal or not supported
        CryptoException
      • encryptComplete

        public abstract short encryptComplete(byte[] input,
                            short inputIndex,
                            short inputLength,
                            byte[] output,
                            short outputIndex)
                                       throws CryptoException
        Encrypts the provided input data using the key currently stored by the instance. Note that the total size of data being encrypted using this class must be a multiple of the relevant algorithm block size.
        Specified by:
        encryptComplete in interface Cipher
        Specified by:
        encryptComplete in interface SequentialCipher
        Parameters:
        input - the input data to encrypt
        inputIndex - index in the input array
        inputLength - input data length
        output - an array to hold the output data
        outputIndex - index in the output array
        Returns:
        The number of bytes returned in output array.
        Throws:
        IllegalUseException - if the total data size is not block size aligned.
        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
        CryptoException - if an internal error occurred
      • decryptComplete

        public abstract short decryptComplete(byte[] input,
                            short inputIndex,
                            short inputLength,
                            byte[] output,
                            short outputIndex)
                                       throws CryptoException
        Decrypts the provided input data using the key currently stored by the instance. Note that the total size of data being decrypted using this class must be a multiple of the relevant algorithm block size.
        Specified by:
        decryptComplete in interface Cipher
        Specified by:
        decryptComplete in interface SequentialCipher
        Parameters:
        input - the input data to decrypt
        inputIndex - index in the input array
        inputLength - input data length
        output - an array to hold the decrypted data
        outputIndex - index in the output array
        Returns:
        The number of bytes returned in output array.
        Throws:
        IllegalUseException - if the total data size is not block size aligned.
        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
        CryptoException - if an internal error occurred
      • create

        public static final SymmetricBlockCipherAlg create(short algType)
                                                    throws CryptoException
        Factory method for creating a concrete instance.
        Parameters:
        algType - the requested algorithm, see ALG_TYPE_.. definitions above for the possible values
        Returns:
        SymmetricAlg instance of the requested algorithm.
        Throws:
        NotSupportedException - if the requested algorithm is not supported
        CryptoException