Intel

Developer Zone

KeyWrap

com.intel.crypto

Class KeyWrap

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


  • public abstract class KeyWrap
    extends java.lang.Object

    This class represents a key wrapping algorithm, a class of symmetric encryption algorithms specialized for key material encryption. The algorithm used is the RFC5297 Synthetic Initialization Vector (SIV) Authenticated Encryption Using the Advanced Encryption Standard (AES).

    The following key sizes are supported by this class:

    • Key size of 256 bits (32 bytes), KEY_SIZE_256.
    • Key size of 384 bits (48 bytes), KEY_SIZE_384.
    • Key size of 512 bits (64 bytes), KEY_SIZE_512.

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

    • Encryption key - using the setKey method. And the following parameter is optional:
    • Associated Data - using the setAssociatedData method. Note that the associated data can hold up to 126 elements.
    • Method Summary

      Methods
      Modifier and Type Method and Description
      abstract void clear()
      Clears all of the optional data that has been set for this instance (nonce, associated data)
      static KeyWrap create()
      Factory method for creating a concrete instance.
      abstract short decrypt(byte[] input, short inputIndex, short inputLength, byte[] sivVector, short sivVectorIndex, 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[] output, short outputIndex, byte[] sivVector, short sivVectorIndex)
      Encrypts the provided input data using the key currently stored by the instance.
      abstract java.util.Vector<byte[]> getAssociatedData()
      Obtains the associated data currently used by this instance.
      abstract short getKey(byte[] keyArray, short keyIndex)
      Obtains the key currently used by this instance.
      abstract short getNonce(byte[] nonceArray, short nonceIndex)
      Obtains the nonce data currently used by this instance.
      abstract void setAssociatedData(java.util.Vector<byte[]> adElements)
      Sets the associated data 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.
      abstract void setNonce(byte[] nonce, short nonceIndex, short nonceLength)
      Sets the nonce (for nonce-based authenticated encryption) to be used by this instance for encrypt/decrypt operations.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, toString
    • Field Detail

      • KEY_SIZE_256

        public static final short KEY_SIZE_256
        Indicates a key size of 256 bits
        See Also:
        Constant Field Values
      • KEY_SIZE_384

        public static final short KEY_SIZE_384
        Indicates a key size of 384 bits
        See Also:
        Constant Field Values
      • KEY_SIZE_512

        public static final short KEY_SIZE_512
        Indicates a key size of 512 bits
        See Also:
        Constant Field Values
      • MAX_ASSOCIATED_DATA_SIZE

        public static final short MAX_ASSOCIATED_DATA_SIZE
        The maximum number of associated data to be used
        See Also:
        Constant Field Values
      • SIV_VECTOR_DATA_SIZE

        public static final short SIV_VECTOR_DATA_SIZE
        The length of the SIV vector in bytes
        See Also:
        Constant Field Values
    • Method Detail

      • 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 bits
        Throws:
        IllegalParameterException - when the provided key size is illegal or not supported
        CryptoException - in case of an internal error
      • 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.
        CryptoException
      • setAssociatedData

        public abstract void setAssociatedData(java.util.Vector<byte[]> adElements)
                                        throws CryptoException
        Sets the associated data to be used by this instance for encrypt/decrypt operations.
        Parameters:
        adElements - a vector consists of all associated data
        Throws:
        IllegalParameterException - when the provided associated data is invalid or the provided associated data size is illegal
        IllegalUseException - when a nonce was set prior to this method and adElements size is MAX_ASSOCIATED_DATA_SIZE
        CryptoException
      • getAssociatedData

        public abstract java.util.Vector<byte[]> getAssociatedData()
                                                            throws CryptoException
        Obtains the associated data currently used by this instance.
        Returns:
        the current associated data used by this instance
        Throws:
        NotInitializedException - if the associated data was not set for this instance.
        CryptoException
      • clear

        public abstract void clear()
                            throws CryptoException
        Clears all of the optional data that has been set for this instance (nonce, associated data)
        Throws:
        CryptoException
      • setNonce

        public abstract void setNonce(byte[] nonce,
                    short nonceIndex,
                    short nonceLength)
                               throws CryptoException
        Sets the nonce (for nonce-based authenticated encryption) to be used by this instance for encrypt/decrypt operations.
        Parameters:
        nonce - nonce data to be used by this instance
        Throws:
        IllegalParameterException - when the provided nonce data is invalid or the provided nonce data size is illegal
        IllegalUseException - when the maximum number of associated data elements was reached (MAX_ASSOCIATED_DATA_SIZE) prior to this method by using setAssociatedData
        CryptoException
      • getNonce

        public abstract short getNonce(byte[] nonceArray,
                     short nonceIndex)
                                throws CryptoException
        Obtains the nonce data currently used by this instance.
        Returns:
        the current nonce data used by this instance
        Throws:
        NotInitializedException - if the nonce data was not set for this instance.
        CryptoException
      • encrypt

        public abstract short encrypt(byte[] input,
                    short inputIndex,
                    short inputLength,
                    byte[] output,
                    short outputIndex,
                    byte[] sivVector,
                    short sivVectorIndex)
                               throws CryptoException
        Encrypts the provided input data using the key currently stored by the instance.
        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
        sivVector - an array to hold the SIV vector data. The size must be not less than SIV_VECTOR_DATA_SIZE
        sivVectorIndex - index in the sivVector 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
        CryptoException - if an internal error occurred
      • decrypt

        public abstract short decrypt(byte[] input,
                    short inputIndex,
                    short inputLength,
                    byte[] sivVector,
                    short sivVectorIndex,
                    byte[] output,
                    short outputIndex)
                               throws CryptoException
        Decrypts the provided input data using the key currently stored by the instance.
        Parameters:
        input - the input data to decrypt
        inputIndex - index in the input data array
        inputLength - input data array length
        sivVector - SIV vector array. The size must be equal to
        sivVectorIndex - index in the sivVector array SIV_VECTOR_DATA_SIZE
        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
        CryptoException - if an internal error occurred
      • create

        public static final KeyWrap create()
        Factory method for creating a concrete instance.
        Returns:
        KeyWrap instance.