- java.lang.Object
-
- com.ibm.crypto.hdwrCCA.provider.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 theDESedeKeyGenerator
,DESKeyGenerator
, andAESKeyGenerator
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 theSECURE_INTERNAL_TOKEN
key is passed to the hardware, only theCKDS
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 andSECURE_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.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description byte
getHwType()
Returns the type of key to be generated.javax.crypto.SecretKey
getKey2KeyEncryptingKey()
Returns the specified key encrypting key.int
getKeySize()
Get the desired key size.SymmetricKeyConstants.KeyUsage
getKeyUsage()
Returns the user specified hardware key usage attributes.java.lang.String
getLabel()
Returns a CKDS label.boolean
getNoCvKEK()
Returns the NoCvKEK attribute.javax.crypto.spec.OAEPParameterSpec
getOAEPParameterSpec()
Returns OAEP padding parameters.byte
getTokenWrappingMode()
Returns the type of key token wrapping to be used.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.protected boolean
isSecureInternalToken()
Checks to see if this CCAAlgorithmParameterSpec is a SECURE_INTERNAL_TOKEN type.void
setHwType(byte hwTypeVal)
Sets the type of key to be generated.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.void
setKeySize(int size)
Set the desired key size for the key to be generated.void
setKeyUsage(SymmetricKeyConstants.KeyUsage keyUsage)
Sets hardware key usage attributes.void
setLabel(java.lang.String label)
Sets the label for aCKDS
type hardware key.void
setNoCvKEK(boolean NoCvKEK)
Specifies whether the CKDS Key Encrypting Key should be created with the NoCvKEK option.void
setOAEPParameterSpec(javax.crypto.spec.OAEPParameterSpec oaepSpec)
Sets the OAEP padding parameters.void
setTokenWrappingMode(byte wrappingMode)
Sets the type of key token wrapping mode to be used.void
setTR31OptionalDataBlock(TR31OptionalDataBlock OptData)
Specifies an optional data block to be included when a TR-31 KeyBlock is created to export a key.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.
-
-
-
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 andSECURE_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
-
CLEAR
public static final byte CLEAR
A clear key.- 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 asCKDS
orSECURE_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 asCKDS
orSECURE_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 asCKDS
orSECURE_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 toSECURE_INTERNAL_TOKEN
using the default wrapping modeWRAPPING_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 toSECURE_INTERNAL_TOKEN
using the default wrapping modeWRAPPING_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 ofCLEAR
,SECURE_INTERNAL_TOKEN
, orCKDS
. If thehwType
isCKDS
and a CKDS label is not explicitly specified, a CKDS label will be generated automatically- Throws:
java.security.InvalidParameterException
- ifhwType
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 usedhwType
- the type of key to be generated. This must be one ofCLEAR
,SECURE_INTERNAL_TOKEN
, orCKDS
. If thehwType
isCKDS
and a CKDS label is not explicitly specified, a CKDS label will be generated automatically- Throws:
java.security.InvalidParameterException
- ifhwType
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 usedhwType
- the type of key to be generated. This must be one ofCLEAR
,SECURE_INTERNAL_TOKEN
, orCKDS
label
- ifhwType
isCKDS
, 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 ifhwType
isCKDS
- Throws:
java.security.InvalidParameterException
- ifhwType
is not valid or iflabel
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 ofCLEAR
,SECURE_INTERNAL_TOKEN
, orCKDS
label
- ifhwType
isCKDS
, 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 ifhwType
isCKDS
- Throws:
java.security.InvalidParameterException
- ifhwType
is not valid or iflabel
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 usedhwType
- the type of key to be generated. This must be one ofCLEAR
,SECURE_INTERNAL_TOKEN
, orCKDS
label
- ifhwType
isCKDS
, 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 ifhwType
isCKDS
wrappingMode
- the wrapping mode to be used by ICSF. This value will only be used when the key type is set toSECURE_INTERNAL_TOKEN
orCKDS
. If the key type isCLEAR
, this value is ignored. ThewrappingMode
must be one ofWRAPPING_MODE_DEFAULT
,WRAPPING_MODE_CBC
, orWRAPPING_MODE_ECB
- Throws:
java.security.InvalidParameterException
- ifhwType
is not valid,label
is longer than 64 characters, orwrappingMode
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
, orCKDS
.
-
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 ofCLEAR
,SECURE_INTERNAL_TOKEN
, orCKDS
- Throws:
java.security.InvalidParameterException
- if the suppliedhwTypeVal
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 aCKDS
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
- iflabel
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 forSECURE_INTERNAL_TOKEN
andCKDS
hardware key types.- Returns:
- the key token wrapping mode to be used, one of
WRAPPING_MODE_DEFAULT
,WRAPPING_MODE_CBC
, orWRAPPING_MODE_ECB
.
-
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 forSECURE_INTERNAL_TOKEN
andCKDS
hardware key types.- Parameters:
wrappingMode
- the wrapping mode to be used, this must be one ofWRAPPING_MODE_DEFAULT
,WRAPPING_MODE_CBC
, orWRAPPING_MODE_ECB
- Throws:
java.security.InvalidParameterException
- if thewrappingMode
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.
-
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 isSymmetricKeyConstants.KeyUsage.OP_DATA
. Valid key usage attributes for Triple-DES and AES key generation areSymmetricKeyConstants.KeyUsage.OP_DATA
,SymmetricKeyConstants.KeyUsage.OPEX_EXPORTER_IMPORTER
, andSymmetricKeyConstants.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(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
- ifkey2KeyEncryptingKey
is not an instance ofDESedeKey
orAESKey
, or if the key type isCLEAR
.
-
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.
-
-