Class CCAAlgorithmParameterSpec

java.lang.Object
com.ibm.crypto.hdwrCCA.provider.CCAAlgorithmParameterSpec
All Implemented Interfaces:
AlgorithmParameterSpec
public final class CCAAlgorithmParameterSpec extends Object implements AlgorithmParameterSpec
This class specifies a set of parameters that can optionally be used with the init method of the DESedeKeyGenerator, DESKeyGenerator, and AESKeyGenerator classes.

This class can also be used with the RSA cipher class for specifying parameters associated with how a secret key is to be unwrapped.

If the key type is SECURE_INTERNAL_TOKEN, then only the key token is returned from the hardware and resident in memory.

If the key type is CKDS, after the SECURE_INTERNAL_TOKEN key is passed to the hardware, only the CKDS entry label is resident in memory.

  • Field Details

    • CKDS

      public static final byte CKDS
      A key that is encrypted by the ICSF host master key and stored in the CKDS. The key is wrapped by the ICSF master key using the default key wrapping modes as set within ICSF.
      See Also:

    • CLEAR

      public static final byte CLEAR
      A clear key.
      See Also:

    • SECURE_INTERNAL_TOKEN

      public static final byte SECURE_INTERNAL_TOKEN
      A key that is encrypted by the ICSF host master key, sometimes called a secure hardware key, and saved as a key token. This is the default type. The key is wrapped by the ICSF master key using the default key wrapping modes as set within ICSF.
      See Also:

    • WRAPPING_MODE_DEFAULT

      public static final byte WRAPPING_MODE_DEFAULT
      This value represents the encryption wrapping mode to be used while wrapping the key value. This mode will be used by ICSF to wrap the ICSF token with the ICSF master key. In this case the default mode as set by ICSF will be used. This setting is relevant to keys that are being generated or unwrapped as CKDS or SECURE_INTERNAL_TOKEN keys.
      See Also:

    • WRAPPING_MODE_ECB

      public static final byte WRAPPING_MODE_ECB
      This value represents the encryption wrapping mode to be used while wrapping the key value. This mode will be used by ICSF to wrap the ICSF token with the ICSF master key. In this case the EBC mode will be used. This setting is relevant to keys that are being generated or unwrapped as CKDS or SECURE_INTERNAL_TOKEN keys.
      See Also:

    • WRAPPING_MODE_CBC

      public static final byte WRAPPING_MODE_CBC
      This value represents the encryption wrapping mode to be used while wrapping the key value. This mode will be used by ICSF to wrap the ICSF token with the ICSF master key. In this case the CBC mode will be used. ICSF currently refers to the CBC mode as enhanced key wrapping mode. This setting is relevant to keys that are being generated or unwrapped as CKDS or SECURE_INTERNAL_TOKEN keys.
      See Also:

  • Constructor Details

    • CCAAlgorithmParameterSpec

      public CCAAlgorithmParameterSpec()
      Constructs a parameter set for a DES, DESede, or AES key. Key type will default to SECURE_INTERNAL_TOKEN using the default wrapping mode WRAPPING_MODE_DEFAULT as set by ICSF.

    • CCAAlgorithmParameterSpec

      public CCAAlgorithmParameterSpec(int size)
      Constructs a parameter set with the desired key size for a DES, DESede, or AES key. Key type will default to SECURE_INTERNAL_TOKEN using the default wrapping mode WRAPPING_MODE_DEFAULT as set by ICSF.
      Parameters:
      size - the size or strength of the requested key, a key size of 0 indicates that the default key size of the key generator or cipher is to be used

    • CCAAlgorithmParameterSpec

      public CCAAlgorithmParameterSpec(byte hwType)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      Parameters:
      hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS. If the hwType is CKDS and a CKDS label is not explicitly specified, a CKDS label will be generated automatically
      Throws:
      InvalidParameterException - if hwType is not valid.

    • CCAAlgorithmParameterSpec

      public CCAAlgorithmParameterSpec(int size, byte hwType)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      Parameters:
      size - the size or strength of the requested key, a key size of 0 indicates that the default key size of the key generator or cipher is to be used
      hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS. If the hwType is CKDS and a CKDS label is not explicitly specified, a CKDS label will be generated automatically
      Throws:
      InvalidParameterException - if hwType is not valid.

    • CCAAlgorithmParameterSpec

      public CCAAlgorithmParameterSpec(int size, byte hwType, String label)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      Parameters:
      size - the size or strength of the requested key, a key size of 0 indicates that the default key size of the key generator or cipher is to be used
      hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS
      label - if hwType is CKDS, this label will be used to identify the CKDS entry created to store the key. Otherwise, this label is ignored. This label must not be longer than 64 characters and cannot include embedded spaces. If null is specified, a label will be generated automatically if hwType is CKDS
      Throws:
      InvalidParameterException - if hwType is not valid or if label is longer than 64 characters.

    • CCAAlgorithmParameterSpec

      public CCAAlgorithmParameterSpec(byte hwType, String label)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      Parameters:
      hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS
      label - if hwType is CKDS, this label will be used to identify the CKDS entry created to store the key. Otherwise, this label is ignored. This label must not be longer than 64 characters and cannot include embedded spaces. If null is specified, a label will be generated automatically if hwType is CKDS
      Throws:
      InvalidParameterException - if hwType is not valid or if label is longer than 64 characters.

    • CCAAlgorithmParameterSpec

      public CCAAlgorithmParameterSpec(int size, byte hwType, String label, byte wrappingMode)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      Parameters:
      size - the size or strength of the requested key, a key size of 0 indicates that the default key size of the key generator or cipher is to be used
      hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS
      label - if hwType is CKDS, this label will be used to identify the CKDS entry created to store the key. Otherwise, this label is ignored. This label must not be longer than 64 characters and cannot include embedded spaces. If null is specified, a label will be generated automatically if hwType is CKDS
      wrappingMode - the wrapping mode to be used by ICSF. This value will only be used when the key type is set to SECURE_INTERNAL_TOKEN or CKDS. If the key type is CLEAR, this value is ignored. The wrappingMode must be one of WRAPPING_MODE_DEFAULT, WRAPPING_MODE_CBC, or WRAPPING_MODE_ECB
      Throws:
      InvalidParameterException - if hwType is not valid, label is longer than 64 characters, or wrappingMode is not valid.

  • Method Details

    • getKeySize

      public int getKeySize()
      Get the desired key size.
      Returns:
      the desired key size.

    • setKeySize

      public void setKeySize(int size)
      Set the desired key size for the key to be generated.
      Parameters:
      size - the desired key size, a key size of 0 indicates that the default key size of the key generator or cipher is to be used

    • getHwType

      public byte getHwType()
      Returns the type of key to be generated.
      Returns:
      the type of key to be generated, must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS.

    • setHwType

      public void setHwType(byte hwTypeVal)
      Sets the type of key to be generated.
      Parameters:
      hwTypeVal - the type of key to be generated, this must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS
      Throws:
      InvalidParameterException - if the supplied hwTypeVal is not supported.

    • getLabel

      public String getLabel()
      Returns a CKDS label.
      Returns:
      the user specified CKDS entry label. If no label was specified, then null will be returned.

    • setLabel

      public void setLabel(String label)
      Sets the label for a CKDS type hardware key.
      Parameters:
      label - if the key to be generated is a CKDS key, then this label will be used to identify the CKDS entry associated with the key. Otherwise, this label will be ignored. This label must not be longer than 64 characters and must not include embedded spaces.
      Throws:
      InvalidParameterException - if label is longer than 64 characters in length.

    • getTokenWrappingMode

      public byte getTokenWrappingMode()
      Returns the type of key token wrapping to be used. Key token wrapping applies only for SECURE_INTERNAL_TOKEN and CKDS hardware key types.
      Returns:
      the key token wrapping mode to be used, one of WRAPPING_MODE_DEFAULT, WRAPPING_MODE_CBC, or WRAPPING_MODE_ECB.

    • setTokenWrappingMode

      public void setTokenWrappingMode(byte wrappingMode) throws InvalidParameterException
      Sets the type of key token wrapping mode to be used. Key token wrapping occurs only for SECURE_INTERNAL_TOKEN and CKDS hardware key types.
      Parameters:
      wrappingMode - the wrapping mode to be used, this must be one of WRAPPING_MODE_DEFAULT, WRAPPING_MODE_CBC, or WRAPPING_MODE_ECB
      Throws:
      InvalidParameterException - if the wrappingMode is not supported.

    • setOAEPParameterSpec

      public void setOAEPParameterSpec(OAEPParameterSpec oaepSpec)
      Sets the OAEP padding parameters.
      Parameters:
      oaepSpec - the OAEP padding parameters

    • getOAEPParameterSpec

      public OAEPParameterSpec getOAEPParameterSpec()
      Returns OAEP padding parameters.
      Returns:
      the OAEP padding parameters if previously set, otherwise returns null.

    • setNoCvKEK

      public void setNoCvKEK(boolean NoCvKEK)
      Specifies whether the CKDS Key Encrypting Key should be created with the NoCvKEK option. This is usually true only when the KEK will be used to export keys to non-z/OS systems, as in a TR-31 Key Block.

      The default value is false.

      The NoCvKEK attribute is only allowed when generating a KEK in the CKDS or importing a KEK to the CKDS.

      Parameters:
      NoCvKEK - the requested key usage NoCvKEK attribute

    • getNoCvKEK

      public boolean getNoCvKEK()
      Returns the NoCvKEK attribute.
      Returns:
      the NoCvKEK attribute.

    • setTR31OptionalDataBlocks

      public void setTR31OptionalDataBlocks(TR31OptionalDataBlock[] OptData)
      Specifies an array of optional data blocks to be included when a TR-31 KeyBlock is created to export a key. Optional data blocks are used to specify key attributes not included in the formal Tr-31 KeyBlock header but required by the platform where the KeyBlock will be unwrapped.

      The tr31OptionalDataBlocks attribute is ignored if not creating a TR-31 KeyBlock.

      This method follows a replace model. After this method is called, the CCAAlgorithmParameterSpec will contain only the TR31OptionalDataBlocks specified in this method call.

      This method copies the data passed to it into local storage so it will be unaffected by changes the caller makes after the call.

      Parameters:
      OptData - An array of TR31OptionalDataBlock objects to be included in a TR-31 KeyBlock.

    • setTR31OptionalDataBlock

      public void setTR31OptionalDataBlock(TR31OptionalDataBlock OptData)
      Specifies an optional data block to be included when a TR-31 KeyBlock is created to export a key. Optional data blocks are used to specify key attributes not included in the formal Tr-31 KeyBlock header but required by the platform where the KeyBlock will be unwrapped.

      The tr31OptionalDataBlocks attribute is ignored if not creating a TR-31 KeyBlock.

      This method follows a replace model. After this method is called, the CCAAlgorithmParameterSpec will contain exactly one TR31OptionalDataBlock.

      This method copies the data passed to it into local storage so it will be unaffected by changes the caller makes after the call.

      Parameters:
      OptData - A TR31OptionalDataBlock object to be included in a TR-31 KeyBlock.

    • getTR31OptionalDataBlocks

      public TR31OptionalDataBlock[] getTR31OptionalDataBlocks()
      Returns a user-specified block of optional data blocks suitable to be included when a TR-31 KeyBlock is created to export a key. Optional data blocks are used to specify key attributes not included in the formal Tr-31 KeyBlock header but required by the platform where the KeyBlock will be unwrapped.
      Returns:
      user-specified block of optional data blocks suitable to be included when a TR-31 KeyBlock is created.

    • setKeyUsage

      public void setKeyUsage(SymmetricKeyConstants.KeyUsage keyUsage)
      Sets hardware key usage attributes. This may be a single operational DATA key, or something more complex, like a pair of key encrypting keys.

      The default key usage attribute for hardware DES, Triple-DES, and AES key generation is SymmetricKeyConstants.KeyUsage.OP_DATA. Valid key usage attribute for DES key generation is SymmetricKeyConstants.KeyUsage.OP_DATA. Valid key usage attributes for Triple-DES and AES key generation are SymmetricKeyConstants.KeyUsage.OP_DATA, SymmetricKeyConstants.KeyUsage.OPEX_EXPORTER_IMPORTER, and SymmetricKeyConstants.KeyUsage.OPEX_IMPORTER_EXPORTER.

      Hardware key usage attribute is ignored if generating CLEAR keys.

      Parameters:
      keyUsage - the requested key usage attribute, null may be specified to indicate the default key usage attribute

    • getKeyUsage

      public SymmetricKeyConstants.KeyUsage getKeyUsage()
      Returns the user specified hardware key usage attributes.
      Returns:
      the user specified hardware key usage attributes, or null if not previously set.

    • setKey2KeyEncryptingKey

      public void setKey2KeyEncryptingKey(SecretKey key2KeyEncryptingKey)
      Sets the key encrypting key that will be used to wrap the second key of a generated key pair.
      Parameters:
      key2KeyEncryptingKey - key encrypting key that will be used to wrap the second key of a generated key pair, has no effect if not generating a key pair
      Throws:
      InvalidParameterException - if key2KeyEncryptingKey is not an instance of DESedeKey or AESKey, or if the key type is CLEAR.

    • getKey2KeyEncryptingKey

      public SecretKey getKey2KeyEncryptingKey()
      Returns the specified key encrypting key.
      Returns:
      the specified key encrypting key, or null if no such key was specified.

    • isSecureInternalToken

      protected boolean isSecureInternalToken()
      Checks to see if this CCAAlgorithmParameterSpec is a SECURE_INTERNAL_TOKEN type.
      Returns:
      true if hwType is SECURE_INTERNAL_TOKEN.