com.ibm.crypto.hdwrCCA.provider.DESedeTR31KeyWrap

public final class DESedeTR31KeyWrap extends CipherSpi

This class implements hardware TR-31 KeyBlock DESede key wrapping. This function enables secure key exchange between dissimilar platforms, such as z/OS and a non-z/OS system. It allows a DESede EXPORTER Key Encrypting Key (KEK) to wrap a DES or DESede CKDSLabel or ICSFToken key to an ANSI TR-31 KeyBlock and allows a DESede IMPORTER KEK to unwrap a DES or DESede key from an ANSI TR-31 KeyBlock to a CKDSLabel or ICSFToken key.

Constructor Summary

Constructors

Constructor

Description

DESedeTR31KeyWrap()

Creates an instance of hardware DESede TR-31 KeyBlock key wrapping cipher.
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()

This operation is not supported.

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 of the required output buffer.

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, operation-specific parameters, 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[] TR31KeyBlock, String wrappedKeyAlgorithm, int wrappedKeyType)

Unwrap a DES or DESede key that was previously wrapped in a TR-31 KeyBlock.

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 or DESede 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
- DESedeTR31KeyWrap
  
  public DESedeTR31KeyWrap()
  
  Creates an instance of hardware DESede TR-31 KeyBlock key wrapping cipher.
  
  Throws:
  
  SecurityException - if this constructor fails to authenticate the JCE framework.
Method Details
- engineGetBlockSize
  
  protected int engineGetBlockSize()
  
  This operation is not supported.
  
  Specified by:
  
  engineGetBlockSize in class CipherSpi
  
  Throws:
  
  UnsupportedOperationException - always.
- engineGetOutputSize
  
  protected int engineGetOutputSize(int inputLen)
  
  Returns the length in bytes of the required output buffer.
  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, as follows:
  
  if the cipher is initialized for wrap, MAX_TR31_LENGTH (9992).
  if the cipher is initialized for unwrap, 64.
- 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.
  Cipher operations done at the hardware level should bypass the Java restricted policy files check because the cryptographic hardware enforces the US export restrictions relating to cryptographic keys. If a hardware key is used for a DES or DESede cipher operation, we can bypass the restricted policy files checking by returning a key size that conforms to the policy files.
  
  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 will be ignored.
  This method should be used to initialize this cipher for Cipher.WRAP_MODE only when both of the following are true:
  
  the key to wrap is a data encryption key (not a Key Encrypting key)
  no optional data blocks are required by the system that will unwrap the key.
  
  This method should be used to initialize this cipher for Cipher.UNWRAP_MODE only when all of the following are true:
  
  the key to unwrap is a data encryption key (not a Key Encrypting key)
  the key will be unwrapped as a CCAAlgorithmParameterSpec.CKDS key
  the CKDS label will be created automatically by the unwrap service
  
  This method resets any existing state information.
  Specified by:
  
  engineInit in class CipherSpi
  
  Parameters:
  
  opmode - the operation mode of this cipher. This is one of Cipher.WRAP_MODE or Cipher.UNWRAP_MODE. Please note that Cipher.ENCRYPT_MODE and Cipher.DECRYPT_MODE operation modes are not supported.
  
  key - the IBMJCECCA hardware DESede key encrypting key
  
  random - the source of randomness (will be ignored)
  
  Throws:
  
  UnsupportedOperationException - if the opmode is either Cipher.ENCRYPT_MODE or Cipher.DECRYPT_MODE, which is not supported by this cipher.
  
  InvalidParameterException - if the opmode is not a valid cipher operation mode.
  
  NullPointerException - if the key is null.
  
  InvalidKeyException - if the given key not a CCA hardware DESede key.
- engineInit
  
  protected void engineInit(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
  Initializes this cipher with a key, operation-specific parameters, 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 will be ignored. This method must be used to initialize this cipher when any of the following are true:
  
  the key to wrap or unwrap is an IBMJCECCA Key Encrypting Key (KEK), either IMPORTER or EXPORTER
  the key to unwrap will be a CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN key
  the wrap operation requires additional information in optional data blocks
  This method resets any existing state information.
  Specified by:
  
  engineInit in class CipherSpi
  
  Parameters:
  
  opmode - the operation mode of this cipher. This is one of Cipher.WRAP_MODE or Cipher.UNWRAP_MODE. Please note that Cipher.ENCRYPT_MODE and Cipher.DECRYPT_MODE operation modes are not supported.
  
  key - the IBMJCECCA hardware DESede key encrypting key (KEK)
  
  params - algorithm parameters in (@link CCAAlgorithmParameterSpec} that specifies information required for the requested operation.
  
  For Cipher.WRAP_MODE, if the key to be wrapped is not a data encrypting key, then the key usage of the key being wrapped must be specified. The parameter may also include optional data blocks required by the system that will unwrap the key.
  For Cipher.UNWRAP_MODE, if the key to be unwrapped is not a data encrypting key, then the key usage of the key being unwrapped must be specified. The parameter may also include the type of key to unwrap to, either CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN or CCAAlgorithmParameterSpec.CKDS. The default is CCAAlgorithmParameterSpec.CKDS.
  
  random - the source of randomness (will be ignored)
  
  Throws:
  
  UnsupportedOperationException - if the opmode is either Cipher.ENCRYPT_MODE or Cipher.DECRYPT_MODE, which is not supported by this cipher.
  
  InvalidParameterException - if the opmode is not a valid cipher operation mode.
  
  InvalidParameterException - if SymmetricKeyConstants.KeyUsage is specified in CCAAlgorithmParameterSpec but is not one of SymmetricKeyConstants.KeyUsage.OP_DATA, SymmetricKeyConstants.KeyUsage.OP_CIPHER, SymmetricKeyConstants.KeyUsage.OP_IMPORTER, or SymmetricKeyConstants.KeyUsage.OP_EXPORTER.
  
  NullPointerException - if the key is null.
  
  InvalidKeyException - if the given key is not a CCA hardware DESede key.
  
  InvalidAlgorithmParameterException - if params is not null and either params is not an instance of CCAAlgorithmParameterSpec or the algorithm parameters specify to unwrap keys as CCAAlgorithmParameterSpec.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:
  
  engineInit(int, Key, AlgorithmParameterSpec, SecureRandom)
- engineWrap
  
  protected byte[] engineWrap(Key key) throws InvalidKeyException
  
  Wrap a CCA hardware DES or DESede key. The wrapped key will be formatted as an ANSI TR-31 KeyBlock.
  
  Overrides:
  
  engineWrap in class CipherSpi
  
  Parameters:
  
  key - the CCA hardware DES or DESede key to be wrapped
  
  Returns:
  
  the wrapped key formatted as an ANSI TR-31 KeyBlock.
  
  Throws:
  
  NullPointerException - if key is null.
  
  InvalidKeyException - if the provided key is not a CCA hardware DES or DESede key.
  
  IllegalStateException - if this cipher is not initialized for the Cipher.WRAP_MODE operational mode.
- engineUnwrap
  
  protected Key engineUnwrap(byte[] TR31KeyBlock, String wrappedKeyAlgorithm, int wrappedKeyType) throws InvalidKeyException
  
  Unwrap a DES or DESede key that was previously wrapped in a TR-31 KeyBlock. The unwrapped key will use the default wrapping method that ICSF has been setup to use for internal key tokens. This can be either the original ECB wrapping method or the enhanced CBC wrapping method which is ANSI X9.24 compliant. 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:
  
  TR31KeyBlock - the previously wrapped CCA hardware DES or DESede key to be unwrapped.
  
  wrappedKeyAlgorithm - the key algorithm of the original key
  
  wrappedKeyType - the type of wrapped key, this must be Cipher.SECRET_KEY
  
  Returns:
  
  the unwrapped CCA hardware DES or DESede key.
  
  Throws:
  
  NullPointerException - if TR31KeyBlock is null.
  
  NoSuchAlgorithmException - if wrappedKeyAlgorithm is not "DES", "DESede", "TripleDES", or "3DES".
  
  InvalidKeyException - if TR31KeyBlock is not 64 bytes in length, wrappedKeyType is not Cipher.SECRET_KEY, or there is an issue creating the unwrapped CCA hardware key.
  
  IllegalStateException - if this cipher is not initialized for the Cipher.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.

Class DESedeTR31KeyWrap

Constructor Summary

Method Summary

Methods inherited from class javax.crypto.CipherSpi

Methods inherited from class java.lang.Object

Constructor Details

DESedeTR31KeyWrap

Method Details

engineGetBlockSize

engineGetOutputSize

engineGetKeySize

engineInit

engineInit

engineInit

engineWrap

engineUnwrap

engineSetMode

engineSetPadding

engineGetIV

engineGetParameters

engineUpdate

engineUpdate

engineDoFinal

engineDoFinal