Module ibm.crypto.hdwrcca
Package com.ibm.crypto.hdwrCCA.provider

Class AESKeyWrap

java.lang.Object
javax.crypto.CipherSpi
com.ibm.crypto.hdwrCCA.provider.AESKeyWrap
public final class AESKeyWrap extends CipherSpi
This class implements hardware AES key wrapping. It allows an AES key encrypting key to wrap other hardware DES, Triple-DES, and AES keys.

  • Constructor Summary

    Constructors
    Constructor
    Description
    AESKeyWrap()
    Creates an instance of hardware AES key wrap.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected byte[]
    engineDoFinal(byte[] input, int inputOffset, int inputLen)
    Encrypting or decrypting data in a single-part operation, or finishing a multiple-part operation is not supported.
    protected int
    engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
    Encrypting or decrypting data in a single-part operation, or finishing a multiple-part operation is not supported.
    protected int
    engineGetBlockSize()
    Returns cipher block size in bytes.
    protected byte[]
    engineGetIV()
    Returns the initialization vector (IV) used with this cipher.
    protected int
    engineGetKeySize(Key key)
    Returns the key size of the given key object.
    protected int
    engineGetOutputSize(int inputLen)
    Returns the length in bytes that an output buffer would need.
    protected AlgorithmParameters
    engineGetParameters()
    Returns the parameters used with this cipher.
    protected void
    engineInit(int opmode, Key key, AlgorithmParameters params, SecureRandom random)
     
    protected void
    engineInit(int opmode, Key key, SecureRandom random)
    Initializes this cipher with a key and a source of randomness.
    protected void
    engineInit(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random)
    Initializes this cipher with a key and a source of randomness.
    protected void
    engineSetMode(String mode)
    Setting the cipher mode is not supported.
    protected void
    engineSetPadding(String paddingScheme)
    Setting the cipher padding mechanism is not supported.
    protected Key
    engineUnwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType)
    Unwrap a previously wrapped CCA hardware DES, DESede, or AES key.
    protected byte[]
    engineUpdate(byte[] input, int inputOffset, int inputLen)
    Continuing a multiple-part encryption or decryption operation is not supported.
    protected int
    engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
    Continuing a multiple-part encryption or decryption operation is not supported.
    protected byte[]
    engineWrap(Key key)
    Wrap a CCA hardware DES, DESede, or AES key.

    Methods inherited from class javax.crypto.CipherSpi

    engineDoFinal, engineUpdate, engineUpdateAAD, engineUpdateAAD

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • AESKeyWrap

      public AESKeyWrap()
      Creates an instance of hardware AES key wrap.
      Throws:
      SecurityException - if this constructor fails to authenticate the JCE framework.

  • Method Details

    • engineGetBlockSize

      protected int engineGetBlockSize()
      Returns cipher block size in bytes.
      Specified by:
      engineGetBlockSize in class CipherSpi
      Returns:
      cipher block size in bytes.

    • engineGetOutputSize

      protected int engineGetOutputSize(int inputLen)
      Returns the length in bytes that an output buffer would need.
      Specified by:
      engineGetOutputSize in class CipherSpi
      Parameters:
      inputLen - the input length in bytes, which will be ignored
      Returns:
      the required output buffer size in bytes.

    • engineGetKeySize

      protected int engineGetKeySize(Key key)
      Returns the key size of the given key object. This method is called by the JCE framework to ensure that the size of the key to be used does not exceed the maximum allowable key size specified in the Java restricted policy files.

      Since cryptographic operations using AES ciphers are always done at the cryptographic hardware level, and the hardware itself enforces the US export restrictions relating to cryptographic keys, we should always return a key size that will pass the restricted policy files check done by the JCE framework.

      Overrides:
      engineGetKeySize in class CipherSpi
      Parameters:
      key - the key object
      Returns:
      a key size that will pass the restricted policy files check done by the JCE framework.

    • engineInit

      protected void engineInit(int opmode, Key key, SecureRandom random) throws InvalidKeyException
      Initializes this cipher with a key and a source of randomness. This cipher may be initialized for key wrapping or key unwrapping operations only, depending on the value of opmode. Encryption and decryption operations are not supported by this cipher.

      This cipher does not require an initialization vector (IV), so the source of randomness provided by random must be null. This method resets any existing state information.

      By default, keys are unwrapped as SymmetricKeyConstants.KeyType.CKDS keys.

      Specified by:
      engineInit in class CipherSpi
      Parameters:
      opmode - the operation mode of this cipher. This is one of WRAP_MODE or UNWRAP_MODE. Please note that ENCRYPT_MODE and DECRYPT_MODE operation modes are not supported
      key - the CCA hardware AES key encrypting key
      random - the source of randomness, which must be null
      Throws:
      UnsupportedOperationException - if the opmode is either ENCRYPT_MODE or DECRYPT_MODE, which is not supported by this cipher.
      InvalidParameterException - if the opmode is not a valid cipher operation mode or if a source of randomness is specified.
      NullPointerException - if the key is null.
      InvalidKeyException - if the given key not a CCA hardware AES key.

    • engineInit

      protected void engineInit(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
      Initializes this cipher with a key and a source of randomness. This cipher may be initialized for key wrapping or key unwrapping operations only, depending on the value of opmode. Encryption and decryption operations are not supported by this cipher.

      This cipher does not require an initialization vector (IV), so the source of randomness provided by random must be null. This method resets any existing state information.

      By default, keys are unwrapped as SymmetricKeyConstants.KeyType.CKDS keys.

      Specified by:
      engineInit in class CipherSpi
      Parameters:
      opmode - the operation mode of this cipher. This is one of WRAP_MODE or UNWRAP_MODE. Please note that ENCRYPT_MODE and DECRYPT_MODE operation modes are not supported
      key - the CCA hardware AES key encrypting key
      params - algorithm parameters that specify whether to unwrap keys as SymmetricKeyConstants.KeyType.SECURE_INTERNAL_TOKEN keys or as SymmetricKeyConstants.KeyType.CKDS keys. Unwrapping to SymmetricKeyConstants.KeyType.CLEAR keys is not supported. This algorithm parameters is only supported in UNWRAP_MODE
      random - the source of randomness, which must be null
      Throws:
      UnsupportedOperationException - if the opmode is either ENCRYPT_MODE or DECRYPT_MODE, which is not supported by this cipher.
      InvalidParameterException - if the opmode is not a valid cipher operation mode or if a source of randomness is specified.
      NullPointerException - if the key is null.
      InvalidKeyException - if the given key not a CCA hardware AES key.
      InvalidAlgorithmParameterException - if params is not null and opmode is WRAP_MODE, or if params is not an instance of CCAAlgorithmParameterSpec, or if the algorithm parameters specify to unwrap keys as CLEAR keys.

    • engineInit

      protected void engineInit(int opmode, Key key, AlgorithmParameters params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
      Specified by:
      engineInit in class CipherSpi
      Throws:
      InvalidKeyException
      InvalidAlgorithmParameterException
      See Also:

    • engineWrap

      protected byte[] engineWrap(Key key) throws InvalidKeyException
      Wrap a CCA hardware DES, DESede, or AES key. The wrapped key will be formatted as a CCA external key token. ICSF HCR77A1 or above is required in order to wrap hardware DES or DESede keys using AES key encrypting keys.
      Overrides:
      engineWrap in class CipherSpi
      Parameters:
      key - the CCA hardware DES, DESede, or AES key to be wrapped
      Returns:
      the wrapped key formatted as a CCA external key token.
      Throws:
      NullPointerException - if key is null.
      InvalidKeyException - if the provided key is not a CCA hardware DES, DESede, or AES key. Or if the key to be wrapped is a DES or Triple-DES key and ICSF version is less than HCR77A1.
      IllegalStateException - if this cipher is not initialized for the WRAP_MODE operational mode.

    • engineUnwrap

      protected Key engineUnwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType) throws InvalidKeyException
      Unwrap a previously wrapped CCA hardware DES, DESede, or AES key. By default, all unwrapped keys will be CKDS keys stored in the CKDS, unless otherwise specified through algorithm parameter specs during cipher initialization.
      Overrides:
      engineUnwrap in class CipherSpi
      Parameters:
      wrappedKey - the previously wrapped CCA hardware DES, DESede, or AES key to be unwrapped
      wrappedKeyAlgorithm - the key algorithm of the original key
      wrappedKeyType - the type of wrapped key, this value must be Cipher.SECRET_KEY
      Returns:
      the unwrapped CCA hardware DES, DESede, or AES key.
      Throws:
      NullPointerException - if wrappedKey is null.
      InvalidKeyException - if wrappedKeyAlgorithm is not "DES", "DESede", "TripleDES", "3DES", or "AES". Or if wrappedKeyType is not Cipher.SECRET_KEY, or there is an issue creating the unwrapped CCA hardware key. Or if the key to be unwrapped is a DES or Triple-DES key and ICSF version is less than HCR77A1.
      IllegalStateException - if this cipher is not initialized for the UNWRAP_MODE operational mode.

    • engineSetMode

      protected void engineSetMode(String mode)
      Setting the cipher mode is not supported.
      Specified by:
      engineSetMode in class CipherSpi
      Parameters:
      mode - the cipher mode
      Throws:
      UnsupportedOperationException - always.

    • engineSetPadding

      protected void engineSetPadding(String paddingScheme)
      Setting the cipher padding mechanism is not supported.
      Specified by:
      engineSetPadding in class CipherSpi
      Parameters:
      paddingScheme - the padding mechanism
      Throws:
      UnsupportedOperationException - always.

    • engineGetIV

      protected byte[] engineGetIV()
      Returns the initialization vector (IV) used with this cipher.
      Specified by:
      engineGetIV in class CipherSpi
      Returns:
      null, because this cipher does not use any IV.

    • engineGetParameters

      protected AlgorithmParameters engineGetParameters()
      Returns the parameters used with this cipher.
      Specified by:
      engineGetParameters in class CipherSpi
      Returns:
      null, because this cipher does not return any parameters.

    • engineUpdate

      protected byte[] engineUpdate(byte[] input, int inputOffset, int inputLen)
      Continuing a multiple-part encryption or decryption operation is not supported.
      Specified by:
      engineUpdate in class CipherSpi
      Throws:
      UnsupportedOperationException - always.

    • engineUpdate

      protected int engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
      Continuing a multiple-part encryption or decryption operation is not supported.
      Specified by:
      engineUpdate in class CipherSpi
      Throws:
      UnsupportedOperationException - always.

    • engineDoFinal

      protected byte[] engineDoFinal(byte[] input, int inputOffset, int inputLen)
      Encrypting or decrypting data in a single-part operation, or finishing a multiple-part operation is not supported.
      Specified by:
      engineDoFinal in class CipherSpi
      Throws:
      UnsupportedOperationException - always.

    • engineDoFinal

      protected int engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
      Encrypting or decrypting data in a single-part operation, or finishing a multiple-part operation is not supported.
      Specified by:
      engineDoFinal in class CipherSpi
      Throws:
      UnsupportedOperationException - always.