Class CCAAlgorithmParameterSpec

  • All Implemented Interfaces:
    java.security.spec.AlgorithmParameterSpec

    public class CCAAlgorithmParameterSpec
    extends java.lang.Object
    implements java.security.spec.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 Summary

      Fields 
      Modifier and Type Field Description
      static byte CKDS
      A key that is encrypted by the ICSF host master key and stored in the CKDS.
      static byte CLEAR
      A clear key.
      static byte PROTECTED
      Deprecated.
      This is deprecated and SECURE_INTERNAL_TOKEN should be used instead.
      static 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.
      static byte WRAPPING_MODE_CBC
      This value represents the encryption wrapping mode to be used while wrapping the key value.
      static byte WRAPPING_MODE_DEFAULT
      This value represents the encryption wrapping mode to be used while wrapping the key value.
      static byte WRAPPING_MODE_ECB
      This value represents the encryption wrapping mode to be used while wrapping the key value.
    • Constructor Summary

      Constructors 
      Constructor Description
      CCAAlgorithmParameterSpec()
      Constructs a parameter set for a DES, DESede, or AES key.
      CCAAlgorithmParameterSpec​(byte hwType)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      CCAAlgorithmParameterSpec​(byte hwType, java.lang.String label)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      CCAAlgorithmParameterSpec​(int size)
      Constructs a parameter set with the desired key size for a DES, DESede, or AES key.
      CCAAlgorithmParameterSpec​(int size, byte hwType)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      CCAAlgorithmParameterSpec​(int size, byte hwType, java.lang.String label)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
      CCAAlgorithmParameterSpec​(int size, byte hwType, java.lang.String label, byte wrappingMode)
      Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
    • Field Detail

      • 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:
        Constant Field Values
      • PROTECTED

        @Deprecated
        public static final byte PROTECTED
        Deprecated.
        This is deprecated and SECURE_INTERNAL_TOKEN should be used instead. 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
    • Constructor Detail

      • 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:
        java.security.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:
        java.security.InvalidParameterException - if hwType is not valid.
      • CCAAlgorithmParameterSpec

        public CCAAlgorithmParameterSpec​(int size,
                                         byte hwType,
                                         java.lang.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:
        java.security.InvalidParameterException - if hwType is not valid or if label is longer than 64 characters.
      • CCAAlgorithmParameterSpec

        public CCAAlgorithmParameterSpec​(byte hwType,
                                         java.lang.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:
        java.security.InvalidParameterException - if hwType is not valid or if label is longer than 64 characters.
      • CCAAlgorithmParameterSpec

        public CCAAlgorithmParameterSpec​(int size,
                                         byte hwType,
                                         java.lang.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:
        java.security.InvalidParameterException - if hwType is not valid, label is longer than 64 characters, or wrappingMode is not valid.
    • Method Detail

      • 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:
        java.security.InvalidParameterException - if the supplied hwTypeVal is not supported.
      • getLabel

        public java.lang.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​(java.lang.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:
        java.security.InvalidParameterException - if label is longer than 64 characters in length.
      • setTokenWrappingMode

        public void setTokenWrappingMode​(byte wrappingMode)
                                  throws java.security.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:
        java.security.InvalidParameterException - if the wrappingMode is not supported.
      • setOAEPParameterSpec

        public void setOAEPParameterSpec​(javax.crypto.spec.OAEPParameterSpec oaepSpec)
        Sets the OAEP padding parameters.
        Parameters:
        oaepSpec - the OAEP padding parameters
      • getOAEPParameterSpec

        public javax.crypto.spec.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.
      • 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​(javax.crypto.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:
        java.security.InvalidParameterException - if key2KeyEncryptingKey is not an instance of DESedeKey or AESKey, or if the key type is CLEAR.
      • getKey2KeyEncryptingKey

        public javax.crypto.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 or PROTECTED.