z/OS Unique Considerations

for the Java^TM SDK, Standard Edition, v 6

(last updated March, 2013)

Hardware Cryptographic devices for z/OS: Introduction; Overview of differences between the software JCE implementation and the hardware JCE implementation; Specific Changes and Requirements; Configuring and using hardware cryptographic devices; The hardware keytool application (hwkeytool); Software to Hardware Key Migration Aids

SAF (RACF) Digital Certificate Support for z/OS Specifics: Introduction; Setting up a RACF keyring from RACF; Using a RACFInputStream to load a RACF key ring into a Java RACF KeyStore; Using a RACFOutputStream to store a Java RACF KeyStore into a RACF key ring; Storing keys into RACF using the RACFKeyStore; Accessing a RACFInputStream using URLStreamHandler; Supported key types for storing into a RACF KeyStore; Passwords and the RACF KeyStore; hwkeytool and the ICSF CSFSERV and CSFKEYS RACF classes; Updates to a JCECCARACFKS KeyStore KeyStore; Additional Information

Hardware Cryptographic devices for z/OS

Introduction

The IBMJCECCA provider replaces the IBMJCE4758 provider from earlier releases.

The IBMJCECCA provider extends Java Cryptography Extension (JCE) and Java Cryptography Architecture (JCA) seamlessly to add the capability to use hardware cryptography using IBM Common Cryptographic Architecture (CCA) interfaces. This provider implements the existing JCE architecture, taking advantage of hardware cryptography to give Java SE programmers the significant security and performance advantages of hardware cryptography with minimal changes to existing Java applications. Because the complexities of hardware cryptography are handled within the normal JCE APIs, the advanced security and performance of hardware cryptographic devices are made easily available.

IBM CCA is a set of software elements that provide common application interfaces to secure, high-speed cryptographic services on various platforms using hardware cryptographic devices. On the z/OS platform, access to hardware cryptographic devices is controlled by the Integrated Cryptographic Service Facility (ICSF). The ICSF component of z/OS provides IBM Common Cryptographic Architecture interfaces to hardware devices. One of the following sets of hardware cryptography features based on zSeries machine type must be installed in order to use the IBMJCECCA provider.

The (CEX2 or PCIXCC) feature and the CPACF feature

The PCICC feature and the CCF feature

For more information about the cryptographic features supported, refer to the zSeries machine's reference or technical guide and your service / support organization. The "Configuring and using hardware cryptographic devices" section of this document discusses configuring the correct hardware environment.

The IBMJCECCA provider supports the following:

Message Digest via the MD2, MD5, SHA-1, SHA-256, SHA-384, and SHA-512 algorithms

Signature and KeyFactory classes

the symmetric algorithms AES, DES, triple DES (also known as DESede), HMAC, PBE

the asymmetric algorithms RSA encryption and decryption with zero padding and PKCS 1 type 2 padding

digital signature creation and verification using the RSA and DSA algorithms (note that DSA is only supported on IBM eServer zSeries 800 (z800) and IBM eServer zSeries 900 (z900) hardware)

true random number generation

key generation via key factories

generation and management of keys and certificates using the keytool application

Like other JCE providers, the IBMJCECCA provider can be added to the JVM using the Security.insertProviderAt() and Security.addProvider() methods, and by adding it to the provider list in the lib/ext/java.security file.

Types of cryptographic hardware utilization

In the cryptography environment there are multiple ways to take advantage of cryptographic hardware. The IBMJCECCA provider supports five types of hardware utilization. Once an asymmetric key pair or symmetric key is generated, it is tied to the hardware type used to generate it. The two types supported only for asymmetric key pairs are "RETAINED" and "PKDS". The two types supported only for symmetric keys are "CKDS" and "PROTECTED". Type "CLEAR" is supported both for asymmetric key pairs and for symmetric keys. Each type is described in more detail below. The types of hardware utilization make trade offs between increased security and increased performance but, in general, any type of hardware cryptographic utilization is more secure and significantly faster than similar cryptographic functions provided by a provider implemented to use only software cryptography.

RETAINED hardware key pairs

Cryptographic hardware can be used to maximize the security of the environment. The most secure implementation of cryptography supported by the IBMJCECCA provider stores the keys on the actual hardware cryptographic device and never allows the private key (the sensitive part of the key pair) to be retrieved or viewed. This is called a "RETAINED" key pair because the private key is retained on the actual hardware device and can never be viewed or retrieved in the clear. What is stored in the JCE keystore or returned to the application at key pair generation is only a reference to the private key, called a label. When the actual key is needed for a cryptographic operation, the operation request is submitted to the hardware card where the key is retained, accompanied by the key label. The cryptographic operation is performed on the card using the retained key and only the results are returned.
This is the most secure of the hardware key types, but also tends to be the slowest. This is because the cryptographic calls for a specific key pair must go to the particular hardware device that retains that key pair. Consequently, the request can not take advantage of multiple (functionally equivalent) cryptographic devices that might be available on the system.
Note that new RETAINED hardware key pairs may only be created on z/OS V1R8 and earlier versions of the operating system. Existing RETAINED hardware key pairs may be read and deleted on all versions of z/OS.

PKDS hardware key pairs

The hardware can be used with key pairs to provide increased security and also to take advantage of multiple hardware devices on the system. Key pairs generated using this medium level of security are called PKDS key pairs. When a PKDS key pair is generated, the private key is encrypted using the system's master key, and the key pair is stored in a system key storage area. This key storage area is a RACF-protected data set. The clear text version of this key can never be viewed or retrieved. What is stored in the JCE keystore or returned to the application at key pair generation is only a reference to the private key, called a label. Because the key is stored in a data set instead of on a particular hardware device, cryptographic operations using PKDS key pairs can take advantage of multiple cryptographic hardware devices. When a cryptographic operation request is received, the private key is decrypted by the CCA software layer and the request is submitted to the next available cryptographic device.

The PKDS key type is the medium level of security supported by the IBMJCECCA provider. Operations using PKDS key types are less secure and generally faster than operations using RETAINED key pairs.

CKDS hardware symmetric keys

The hardware can be used with symmetric keys to provide increased security and also to take advantage of multiple hardware devices on the system. Symmetric keys generated using this medium level of security are called CKDS keys. When a CKDS key is generated, it is encrypted using the system's master key and the resulting key token is stored in a system key storage area. This key storage area is a RACF-protected data set. The clear text version of this key can never be viewed or retrieved. What is stored in the JCE keystore or returned to the application at key generation is only a reference to the key, called a label. Because the key is stored in a data set instead of on a particular hardware device, cryptographic operations using CKDS keys can take advantage of multiple cryptographic hardware devices. When a cryptographic operation request is received, the key is decrypted by the CCA software layer and the request is submitted to the next available cryptographic device.

The system master key can only be changed using the ICSF component of z/OS. When the system master key is changed, ICSF also updates the CKDS entries so that the keys it contains will be encrypted using the new system master key. This ensures that CKDS keys remain usable even if the system master key is changed.

The CKDS key type has the highest level of security supported by the IBMJCECCA provider for symmetric keys. Operations using CKDS key types are the most secure symmetric key operations supported by the IBMJCECCA provider.

PROTECTED hardware symmetric keys

The hardware can be used with symmetric keys to provide increased security and also to take advantage of multiple hardware devices on the system. Symmetric keys generated using this level of security are called PROTECTED keys. When a PROTECTED key is generated, it is encrypted using the system's master key. What is stored in the JCE keystore or returned to the application at key generation is only the encrypted key, called a key token. Because the system master key is never available outside the CCA software layer, a PROTECTED key is more secure than a CLEAR key. When a cryptographic operation request is received, the key is decrypted by the CCA software layer and the request is submitted to the next available cryptographic device.

ICSF is the z/OS component that is used to change the system master key. PROTECTED keys are encrypted using the host master key and then stored outside the CKDS, that is, outside the control of ICSF. This means that if the system master key is changed, any PROTECTED key created using the old system master key becomes unusable and data encrypted using it cannot be decrypted. For this reason, PROTECTED keys are recommended only for short-term use. They should not be used for data that will be encrypted and then decrypted at a much later date.

The PROTECTED key type has the medium level of security supported by the IBMJCECCA provider for symmetric keys. Operations using PROTECTED key types are less secure and generally faster than operations using CKDS keys.

CLEAR hardware key pairs and symmetric keys

The hardware can also be used to accelerate the performance of the cryptographic operation. The lowest level of hardware security is a "CLEAR" key pair or symmetric key, but this provides the fastest throughput. When the key pair or symmetric key is generated as type CLEAR, the keypair or symmetric key is stored in a clear and unprotected representation. This clear key pair or symmetric key can be used by the application to perform cryptographic operations on any CCA-capable hardware cryptographic device the system supports and, as there is no overhead for retrieving the key from the PKDS or CKDS, no overhead for decrypting the key, and no requirement for the cryptographic operation to be processed by a specific hardware device, it is the fastest of the three types.
The CLEAR key type is the fastest type supported by the IBMJCECCA provider, but it is also the least secure.

Note: Most JCE providers using software cryptography support only the key pair and symmetric key type CLEAR.

Key storage overview

All three types of hardware key pair and all three types of symmetric key supported by the IBMJCECCA provider can be used by any application. For RETAINED, CKDS and PKDS keys, the application will have only a label. For PROTECTED keys, the application will have only a token. For CLEAR keys, the application will have an actual clear representation of the key material. The IBMJCECCA provider accepts key labels, key tokens, and clear representations of keys interchangeably and treats all the same as actual keys. Key labels, key tokens, and clear representations of keys can be stored by the application using whatever mechanism they choose.

The IBMJCECCA provider includes a Java keystore (type JCECCAKS) that can be used to store any of these representations of keys. A JCECCAKS keystore provides an added level of security, allowing the keys stored in it to be encrypted using passwords before they are stored in the keystore file. This means that if you choose CLEAR keys or PROTECTED keys for performance reasons, they can be stored in keystore entries that are password protected. While password protection is provided for all keystore entries, regardless of the type of key stored in the entry, it is not as important for RETAINED, PKDS and CKDS keys. This is because, for RETAINED, PKDS and CKDS keys, the keystore entry contains only a key label and no sensitive key information.

Key generation and storage

Key generation can be accomplished either using the keytool application included with the IBMJCECCA provider or using JCE APIs. The keytool application included with the IBMJCECCA provider is called hwkeytool. It enables you to generate symmetric keys and key pairs then store them in a keystore file of type JCECCAKS. The JCE APIs allow you to generate symmetric keys and key pairs in an application and then, at the discretion of the application, also store them in a keystore of type JCECCAKS.

RSA Signature and Verification

The IBMJCECCA provider supports digital signature and verification with the available RSA and DSA algorithms (note that DSA is only supported on z800 and z900 hardware). This implementation moves all algorithm processing to the installed cryptographic hardware device. RSA is a relatively compute intensive algorithm, so this moves a significant portion of the CPU instructions off the main processor and onto the cryptographic hardware device. The cryptographic hardware processes this work on a secure card, making it much harder to capture and compromise the sensitive material involved. The cryptographic hardware is also much faster than software cryptographic processing.

An additional benefit provided by cryptographic hardware is the choice of three levels of security: CLEAR key pairs, PKDS based key pairs and RETAINED key pairs. When you utilize the cryptographic hardware capabilities, you increase the base security of the operation (by having the hardware process the algorithm and data), you reduce the load on your main platform, you increase the throughput rate of the request, and you have the option of using more secure key pairs.

DSA Signature and Verification

Note that the DSA algorithm is only supported on hardware cryptographic devices for z800 and z900 machines.

DSA signature and verification using hardware cryptographic devices is only available in Cryptographic Coprocessor Facility (CCF) hardware. It is only supported on z800 and z900 machines.

An additional restriction is that, due to the hardware capabilities for DSA in the CCF hardware, the only type of key pair that is available for DSA is PKDS. The CCF hardware does not support CLEAR DSA key pairs or RETAINED DSA key pairs.

MD2, MD5, SHA-1, SHA-256, SHA-384, and SHA-512 hashing algorithms

Hashing algorithms are not as compute intensive as the RSA and DSA algorithms, so it is not always better to use hardware devices to perform them. This is because the overhead of using the hardware device can outweigh the potential performance gains. Further, the security of performing hashing algorithms on hardware is not substantially better than performing the same operations in software, because the hash subsequently is used in a more secure RSA or DSA sign or verify operation. For these reasons many hardware cryptography devices don't support hashing algorithms and, in some cases, the CCA layer performs the hashing algorithm in software rather than hardware.

The IBMJCECCA provider calls the CCA interfaces to perform MD5, SHA-1, SHA-256, SHA-384, and SHA-512 hashing, and performs MD2 hashing via software. In some cases, the IBM CCA layer performs the MD5 hash using software instead of hardware.

Note the following regarding the SHA algorithms.

SHA-256 is supported on IBM System z9 (z9) and newer zSeries processor families.

SHA-384 and SHA-512 are supported on System z10 Enterprise Class (z10) and newer zSeries processor families.

Random Number generation

The IBM CCA hardware devices provide a true random number generator. This is an improvement over the java.util.Random class which provides a pseudo random number generation capability based on salting a random number operation with some value. The IBMJCECCA provider takes advantage of the true random number generation capabilities in the cryptographic hardware and makes them available to applications with the SecureRandom class. Note that there are performance implications when using this hardware-based random number generator instead of the random number generator in the IBMJCE provider. Please refer to the technote titled Random Number Generation operations performance using Hardware Crypto (IBMJCECCA) Technote for further information.

Refer to "The SecureRandom Class" for more information.

IBMJCECCA provider package includes:

An implementation of the Digital Signature Algorithm (DSA), described in NIST FIPS 186 (only supported on IBM eServer zSeries 800 (z800) and IBM eServer zSeries 900 (z900) hardware)

An implementation of RSA, described in PKCS #1.

An implementation of the MD2 (RFC1319), MD5 (RFC 1321), SHA-1 (NIST FIPS 180-1), SHA-256 (NIST FIPS 180-2), SHA-384 (NIST FIPS 180-2), and SHA-512 (NIST FIPS 180-2) message digest algorithms.
Note the following regarding the SHA algorithms.

SHA-256 is supported on z9 and newer zSeries processor families

SHA-384 and SHA-512 are supported on z10 and newer zSeries processor families.

An implementation of the HmacMD2, HmacMD5, HmacSHA1, HmacSHA256, HmacSHA384, and HmacSHA512 hashing message authentication code algorithms.
Note the following regarding the HmacSHA algorithms.

HmacSHA256 is supported on z9 and newer zSeries processor families.

HmacSHA384 and HmacSHA512 are supported on z10 and newer zSeries processor families.

An implementation of the AES cipher algorithm.

An implementation of the DES cipher algorithm.

An implementation of the TripleDES cipher algorithm.

An implementation of the following PBE algorithms:

PBEWithMD2AndDES

PBEWithMD2AndTripleDES

PBEWithMD5AndDES

PBEWithMD5AndTripleDES

PBEWithSHA1AndDES

PBEWithSHA1AndTripleDES

PBEWithSHAAnd2KeyTripleDES

PBEWithSHAAnd3KeyTripleDES

A DSA key pair generator for generating a pair of public and private keys suitable for the DSA algorithm (only supported on z800 and z900 hardware).

An RSA key pair generator for generating a pair of public and private keys suitable for the RSA algorithm.

An AES key generator for generating a key suitable for the AES algorithm.

A DES key generator for generating a key suitable for the DES algorithm.

A TripleDES key generator for generating a key suitable for the TripleDES algorithm.

An HmacMD2 key generator for generating a key suitable for the HmacMD2 algorithm.

An HmacMD5 key generator for generating a key suitable for the HmacMD5 algorithm.

A HmacSHA1 key generator for generating a key suitable for the HmacSHA1. algorithm.

An HmacSHA256 key generator for generating a key suitable for the HmacSHA256 algorithm.

Note that the HmacSHA256 algorithm is supported on z9 and newer zSeries processor families.

An HmacSHA384 key generator for generating a key suitable for the HmacSHA384 algorithm.

Note that the HmacSHA384 algorithm is supported on z10 and newer zSeries processor families.

An HmacSHA512 key generator for generating a key suitable for the HmacSHA512 algorithm.

Note that the HmacSHA512 algorithm is supported on z10 and newer zSeries processor families.

A DSA algorithm parameter generator (only supported on z800 and z900 hardware).

A DSA algorithm parameter manager (only supported on z800 and z900 hardware).

An AES algorithm parameter manager.

A DES algorithm parameter manager.

A TripleDES algorithm parameter manager.

An implementation of the proprietary "IBMSecureRandom" random number generation algorithm.

A "certificate factory" for X.509 certificates and Certificate Revocation Lists (CRLs).

Keystore implementations for the proprietary keystore type named "JCECCAKS".

Overview of differences between the software JCE implementation and the hardware JCE implementation

There are few differences between the software cryptography implementation of JCE (IBMJCE) and the hardware implementation (IBMJCECCA). For example, DES and Triple DES operations available in the IBMJCE provider are the same in the IBMJCECCA provider. One difference, discussed below, is in the required key attribute restrictions for the RSA cipher algorithm. A more important difference is in the list of supported cryptographic algorithms. The IBMJCECCA provider supports fewer algorithms than the IBMJCE provider, due to limitations in the currently available hardware. The cryptographic operations provided by the IBMJCECCA are the same as for previous versions of JCE. Therefore, an existing application can be migrated easily from a software JCE provider, such as IBMJCE, into the hardware JCE environment, IBMJCECCA. To migrate, it is only necessary to generate new key pairs for RSA or DSA with appropriate attributes (see below) and to change the security provider.
The security provider can be changed either by using API calls with the provider parameter or by changing the provider list to place the IBMJCECCA in a preferred position (that is, with a lower sequence number than the IBMJCE provider). If it is necessary to have a software JCE provider, such as IBMJCE, in the provider list in a position preferred to the position of the IBMJCECCA, you must specify the IBMJCECCA provider in the getInstance() API if you want to use it instead of the software provider. If the provider is not specified on an API call, the actual provider invoked at run time will be the first one on the provider list that supports the requested algorithm and key type. This could cause a software JCE provider to be used instead of the IBMJCECCA provider.
The following section, titled "Specific Changes and Requirements", provides more details for the advanced applications developer.

Specific Changes and Requirements
The following sections discuss the restrictions and features that differ from the basic software JCE provider (IBMJCE) to the hardware assisted JCE provider (IBMJCECCA).
The KeyFactory Class:

The key factory class is an engine class designed to provide opaque cryptographic keys (objects of type Key) and key specifications (transparent representations of the underlying key material).

AES
The IBMJCECCA provider supports a key type for AES keys that have been stored previously in the host CKDS. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CKDS label for the key.
Other keySpec classes supported by the AES KeyFactory include the AESKeySpec and the SecretKeySpec.
DES
The IBMJCECCA provider supports a key type for DES keys that have been stored previously in the host CKDS. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CKDS label for the key.
Other keySpec classes supported by the DES KeyFactory include the DESKeySpec and the SecretKeySpec.
Triple DES (aka DESede and 3DES)
The IBMJCECCA provider supports a key type for triple DES keys that have been stored previously in the host CKDS. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CKDS label for the key.
Other keySpec classes supported by the triple DES KeyFactory include the DESedeKeySpec and the SecretKeySpec.
DSA
The IBMJCECCA provider supports a key type for DSA private hardware keys that is similar to the DSA Private keys available in software providers. DSA private hardware keys are objects of type DSAPrivateHWKey. The corresponding DSA public keys are objects of type DSAPublicKey.
The KeyFactory class can be used to generate a DSA Private hardware key from a DSAPrivateKeyHWSpec. The KeyFactory can also be used to generate a DSA public key from a DSAPublicKeySpec or an X509EncodedKeySpec.

The KeyFactory class can also derive a DSAPrivateKeyHWSpec from a DSA Private hardware key or a DSAPublicKeySpec or X509PublicKeySpec from a DSA public key.

RSA
The IBMJCECCA provider adds a new key type for RSA private hardware keys that is similar to the RSA Private keys available in software providers. RSA private hardware keys are objects of type RSAPrivateHWKey. The corresponding RSA public keys are objects of type RSAPublicKey.
The KeyFactory class can be used to generate an RSA private hardware key from a RSAPrivateHWKeySpec, RSAPrivateCrtKeySpec, RSAPrivateKeySpec, or KeyLabelKeySpec. The KeyFactory can also be used to generate an RSA public key from an RSAPublicKeySpec , X509EncodedKeySpec,or KeyLabelKeySpec. Keys that already in the PKDS can also be created by passing a KeyLabelKeySpec to the RSA KeyFactory.

The KeyFactory class can also derive an RSAPrivateKeyHWSpec from an RSA private hardware key or an RSAPublicKeySpec or X509PublicKeySpec from an RSA public key.

Note that an RSAPrivateKeyHWSpec and a DSAPrivateKeyHWSpec are valid only on the system where the private key was originally generated. Private hardware keys can not be moved from the system on which they are generated to another system. This is true for all private hardware keys, including clear private keys, and is part of the security provided for them.

Algorithm Parameters Classes:

The CCAAlgorithmParameterSpec class:

This class (which implements the AlgorithmParameterSpec interface) specifies whether the AES, DES, or triple DES key to be generated will be a secret hardware key and whether it will be stored in the CKDS.
In the default case, an object of this class is created without specifying a key type, and this object is passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() will return a key object containing the requested key encrypted using the host master key.

A CCAAlgorithmParameterSpec object can be used to specify the strength (size) of the key to be generated.

If the CCAAlgorithmParameterSpec object is being used to generate a key in the system CKDS, the CCAAlgorithmParameterSpec can be used to specify the CKDS label to use to identify the CKDS entry. If a label is specified, it must be unique in the CKDS and must follow the ICSF rules for CKDS entry labels. If no label is specifed for a new CKDS entry, the KeyGenerator generateKey() method will create one automatically.

A CCAAlgorithmParameterSpec object can also be used to explicitly specify the type of key to be generated:

CCAAlgorithmParameterSpec.CKDS can be passed to the CCAAlgorithmParameterSpec constructor, and the resulting object passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() will return a key object containing the CKDS label for requested key encrypted using the host master key and stored in the system CKDS.

CCAAlgorithmParameterSpec.PROTECTED can be passed to the CCAAlgorithmParameterSpec constructor, and the resulting object passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() will return a key object containing the requested key encrypted using the host master key. This key can also be generated using a KeyGenerator class and passing a CCAAlgorithmParameterSpec object, created without specifying a key type, to the KeyGenerator init() method.

CCAAlgorithmParameterSpec.CLEAR can be passed to the CCAAlgorithmParameterSpec constructor and the resulting object passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() will return a key object containing the clear key material for requested key. This key can also be generated using a KeyGenerator class without passing any CCAAlgorithmParameterSpec object to the KeyGenerator init() method.

CCAAlgorithmParameterSpec has the following constructors:

public CCAAlgorithmParameterSpec()

public CCAAlgorithmParameterSpec(int size)

public CCAAlgorithmParameterSpec(byte hwType)

public CCAAlgorithmParameterSpec(int size,byte hwType)

public CCAAlgorithmParameterSpec(int size,byte hwType,String label)

public CCAAlgorithmParameterSpec(byte hwType,String label)

Parameters that can be passed to the constructors:

The size parameter must be valid for the specific algorithm of the KeyGenerator to which this CCAAlgorithmParameterSpec will be passed.

The hwType parameter must be one of the following constant values:

CCAAlgorithmParameterSpec.CLEAR

CCAAlgorithmParameterSpec.PROTECTED

CCAAlgorithmParameterSpec.CKDS

The label parameter must be valid for the ICSF component, according to the rules defined for the Key Generator Utility Program (KGUP).

CCAAlgorithmParameterSpec has the following methods:

public int getKeySize()

This method returns the key size specified to the CCAAlgorithmParameterSpec constructor. If no key size was specified, this method returns 0.

public byte getHwType()

This method returns the key type specified to the CCAAlgorithmParameterSpec constructor. The returned value will be one of the following constant values:

CCAAlgorithmParameterSpec.CLEAR

CCAAlgorithmParameterSpec.PROTECTED

CCAAlgorithmParameterSpec.CKDS

public String getLabel()

This method returns the CKDS label specified to the CCAAlgorithmParameterSpec constructor. If no CKDS label was specified, this method returns null.

It is not necessary to specify a CCAAlgorithmParameterSpec object in order to create a key using an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. If no CCAAlgorithmParameterSpec object is passed to the KeyGenerator init() method before the generateKey() method is called, the key object returned will contain the clear key material for requested key.

The KeyParameterSpec class for DSA hardware (DSAHWKeyParameterSpec):

This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters to use with the DSA hardware algorithm. These are:

DSAKeyHWAttributes
Due to hardware restrictions, these must be KeyHWAttributeValues.PKDS and KeyHWAttributeValues.SIGNATURE.

DSAParameterSpec
These are:

p - the prime

q - the sub-prime

g - the base

KeySize
This parameter specifies the size of the key based on prime p.

KeyLabel
This parameter specifies the name that will be used as a reference to the key stored in the hardware.

See the Java API documentation for the specific methods, default values and restrictions associated with this class.

The KeyParameterSpec class for RSA hardware (RSAKeyParameterSpec):

This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters to use with the RSA hardware algorithm. These are:

RSAKeyHWAttributes
This parameter includes

RSAKeyHWAttributes.type
which must have one of the following values:

KeyHWAttributeValues.PKDS

KeyHWAttributeValues.CLEAR

KeyHWAttributeValues.RETAIN

RSAKeyHWAttributes.usage
which must have one of the following values:

KeyHWAttributeValues.SIGNATURE

KeyHWAttributeValues.KEYMANAGEMENT

KeySize
This parameter specifies the size of the key.

KeyLabel
If the RSAKeyHWAttributes.type is not specified as KeyHWAttributeValues.CLEAR, this parameter specifies the name that will be used as a reference to the key stored in hardware.

See the Java API documentation for the specific methods, default values and restrictions associated with this class.

The Key Interface Class:
As discussed above, the clear key material for private hardware keys of type PKDS or RETAINED is never returned to an application and can never be transported for use on another system. For this reason, no implementation of the Key interface can be used to represent them.

A software reference to a private hardware key of type PKDS or RETAINED is not a key or a key specification, but instead is a label that can be specified to the IBMJCECCA provider in place of a key. The following method can be used to retrieve the representation of a hardware key pair:
public byte [] getToken() 
For a DSA key pair, getToken() returns the label that represents the key stored in the PKDS associated with the hardware.

For an RSA key pair of type CLEAR, getToken() returns an internal CCA token. For an RSA key pair of type PKDS, getToken() returns the label that represents the key stored in the PKDS associated with the hardware. For an RSA key pair of type RETAINED, getToken() returns the label that represents the key stored on the hardware itself.
Key Specification Interfaces and Classes

The KeyLabelKeySpec Class

This class (which implements the KeySpec Interface) specifies the CKDS label for an AES, DES, or DESede key stored in the system CKDS. If a KeyLabelKeySpec is passed to the generateSecret() method of an AESKeyFactory, a DESKeyFactory, or a DESedeKeyFactory then the key object returned will represent a key already stored in the CKDS. Note that generateSecret() does not create a new CKDS entry and does not verify that such an entry currently exists in the CKDS.
This class also specifies the PKDS label for an RSA key pair stored in the system PKDS. If a KeyLabelKeySpec is passed to the generatePrivate() or the generatePublic() method of an RSAKeyFactory, then the key object returned will represent the corresponding key of a key pair already stored in the PKDS. Note that generatePublic() and generatePrivate() do not create a new PKDS entry and do not verify that such an entry currently exists in the PKDS.
KeyLabelKeySpec has the following methods:

public String getLabel()

This method returns the CKDS label for the key or the PKDS label for the key pair.

public byte[] getLabelBytes()

This method returns the ASCII byte representation of the CKDS label for the key or the PKDS label for the key pair.

The DSAPrivateHWKeySpec Class

This class (which implements the KeySpec Interface) specifies a DSA private hardware key with its associated parameters. It has the following methods:

public byte[] getLabel()

This method returns the private key label.

public DSAKeyHWAttributes getAttributes()

This method returns the DSA algorithm parameters used to calculate the key.

public DSAParameterSpec getDSAParamSpec()

This method returns the DSA hardware attributes associated with the key.

See the Java API documentation for the specific methods, default values and restrictions associated with this class.

The RSAPrivateHWKeySpec Class

This class (which implements the KeySpec Interface) specifies an RSA private hardware key with its associated parameters. It has the following methods:

public byte[] getToken()

This method returns the private key token, which can be an internal CCA token or a key label.

public RSAKeyHWAttributes getAttributes()

This method returns the RSA hardware attributes associated with the key.

See the Java API documentation for the specific methods, default values and restrictions associated with this class.

The SecureRandom Class:
The SecureRandom class in this provider is a true random number generator that does not need seeding. Therefore, calls to setSeed(), getSeed() and generateSeed() will throw an exception.
The following illustrates using SecureRandom:
java.security.SecureRandom random = null;
random = java.security.SecureRandom.getInstance( "IBMSecureRandom");
byte[] testData = new byte[1024];
random.nextBytes(testData);
In this example, an instance of the SecureRandom class is obtained, a byte array is instantiated, and a random number of size 1024 bytes is generated.

See the Java API documentation for the specific methods, default values and restrictions associated with this class
Reading Base64-Encoded Certificates

Certificates encoded with Base64 are read in and written out in the ISO8859_1 code page, not the local code page. This is done to make them compatible with the Base64-Encoded Certificates on other platforms. For this reason an encoded certificate may not be human readable on some platforms.

The Signature Class:

The IBMJCECCA provider supports signatures of the following types:

SHA1 with DSA, except that DSA is only supported on z800 and z900 hardware

SHA1 with RSA

MD2 with RSA

MD5 with RSA

SHA256 with RSA (supported on z9 and newer zSeries processor families)

SHA384 with RSA (supported on z10 and newer zSeries processor families)

SHA512 with RSA (supported on z10 and newer zSeries processor families)

A Signature is created by calling the MessageDigest class that will be used when computing the signature and then calling the CCA hardware to create the actual signature from the hash and the corresponding private key. A Signature is verified by creating a hash and passing in both the public key and the previously generated signature to the hardware. (See "Specific Changes and Requirements" for specific class names.)

Data Encryption Standard (DES): Keys
The hardware JCE implementation (IBMJCECCA) extends the DES key available in the software JCE implementation (IBMJCE). In the IBMJCE implementation, the actual DES key material is stored in the key object. The IBMJCECCA implementation extends this by adding the following alternative representations:
A DES key previously stored in the CKDS. The key object will contain the CKDS label for the key.
The following illustrates creating a DES key object for a key already stored in the CKDS with the label "MYENCRYPTEDDESKEY" and then (for purposes of illustration) deleting the CKDS entry.
// create a key object for an existing CKDS entry
// (No checking is done to verify that the entry exists, or
// that the key it contains is actually a DES key.)
//
SecretKeyFactory desKeyFactory =
        SecretKeyFactory.getInstance("DES", "IBMJCECCA");
KeyLabelKeySpec spec =
        new KeyLabelKeySpec("MYENCRYPTEDDESKEY");
SecretKey key = desKeyFactory.generateSecret(spec);

// delete the entry from the CKDS
// (An exception is thrown if the CKDS entry does not exist.)
//
key.deleteCKDSEntry();

//
// Note that, in this example, the Java key object still
// exists, but the CKDS entry it represents has been deleted.
// Any attempt to use the object "key" will cause an exception
// containing a hardware return code and reason code.
//
                        
On z800 and z900 machines, a key object containing the CKDS label for an encrypted DES key can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
On the IBM eServer zSeries 890 (z890), IBM eServer zSeries 990 (z990), and newer zSeries processors, a key object containing the CKDS label for a clear DES key can be used for CBC mode, CFB mode, or ECB mode encryption and decryption with the IBMJCECCA provider. This environment also supports using a key object containing the CKDS label for an encrypted DES key for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object containing the CKDS label for an encrypted DES key can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).
A DES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain a DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains a DES hardware token. Unwrapping to a key object containing a DES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping DES keys, see RSA
A DES key generated by an IBMJCECCA call to the underlying hardware. The key object will contain a hardware token. This token contains the key encrypted with the host master key. The key material for this type of key is never resident in system memory in clear form.
The following illustrates generating a DES key object containing a hardware key token
// create a new key token and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec();
KeyGenerator keyGen =
        KeyGenerator.getInstance( "DES", "IBMJCECCA" );
keyGen.init( ccaAlgParmSpec, null );
Key desKey = keyGen.generateKey();
                        
A key object containing a DES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object containing a DES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).
A DES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain a DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains a DES hardware token. Unwrapping to a key object containing a DES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping DES keys, see RSA
A DES key generated by an IBMJCECCA call to the underlying hardware and then stored in the CKDS. The key object will contain the label for the new CKDS entry. The CKDS entry holds a token that contains the key encrypted with the host master key. The key material for this type of key is never resident in system memory in clear form.
The following illustrates generating a protected DES key token, storing it in a new CKDS entry with an automatically generated label, and creating a key object containing the label for the CKDS entry.
// create a new CKDS entry and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);
KeyGenerator keyGen = KeyGenerator.getInstance("DES", "IBMJCECCA");
keyGen.init( ccaAlgParmSpec, null );
Key thisKey = keyGen.generateKey();
                        
The following illustrates generating a protected DES key token, storing it in a new CKDS entry with the label "ADESTOKENINCKDS", and creating a key object containing the label for the CKDS entry.
// create a new CKDS entry and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS,
                                      "ADESTOKENINCKDS");
KeyGenerator keyGen = KeyGenerator.getInstance("DES", "IBMJCECCA");
keyGen.init(ccaAlgParmSpec,null);
Key thisKey = keyGen.generateKey();
                        
A key object representing a DES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object representing a DES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).
A DES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain a DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains a DES hardware token. Unwrapping to a key object containing the label for a CKDS entry that contains a DES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping DES keys, see RSA
Data Encryption Standard (DES): Operations

The hardware JCE implementation (IBMJCECCA) of DES does not change any of the APIs that are available in software JCE implementation (IBMJCE). Therefore, an application that used the DES capabilities of the IBMJCE will not require modification to use the IBMJCECCA, except for specific references to the provider. For example, if a call to the getInstance() API specified the IBMJCE provider, it will be necessary to change the call to specify the IBMJCECCA provider instead.
Although all DES ciphers are available in the IBMJCECCA provider, they are not all available in the hardware devices. The hardware cryptographic devices only support the Cipher Block Chaining (CBC) and Electronic Code Book (ECB) versions of DES. That is, all of the DES ciphers are supported by the IBMJCECCA provider, but only CBC and ECB modes use hardware cryptography.
It is not always more efficient to use hardware cryptography instead of software cryptography. The DES algorithm is not as compute intensive as some asymmetric algorithms such as RSA. For smaller data sizes, software DES cryptography can be faster than hardware cryptography. Because of this, a software version of DES with CBC and ECB also were implemented in the IBMJCECCA provider. For small amounts of data, software DES (CBC or ECB) is sometimes faster than hardware DES (CBC or ECB) cryptography, The exact size of the data at which the performance trade off is found varies from system to system. Therefore, a "clip level" is used to specify the data size at which hardware cryptography is used. Any data length below the clip level will use software cryptography. The clip level is a system property called "ibm.DES.usehdwr.size" and has a default value of 60. Thus, by default, any DES CBC or ECB processing where the data size is less than 60 bytes will be performed using software cryptography and any data size of 60 bytes or more will be performed using hardware cryptography. For ciphers other than DES CBC and DES ECB this system property has no function.
You can adjust the clip level by changing the system property to the desired level. If you set the system property to 0, all DES CBC and DES ECB processing will be performed using hardware cryptography. If you set the system property to -1, all DES CBC and DES ECB processing will be performed using software cryptography. This system property applies to both DES and triple DES CBC and ECB processing.
Note that the data size comparison to the clip level is done when the first data is passed to the cipher for encryption or decryption. For example, consider an application that decrypts the contents of a tape by reading each record and passing it to the cipher before reading the next record. In this case, the first record passed to the cipher object will be the tape header. If the tape header is smaller than the current clip level, the decryption will be done using software, even though the subsequent records may be very large. This is a case where you might choose to set the clip level to 0 so that hardware cryptography will be used, regardless of the size of the first record processed.
The example below shows how to set the "ibm.DES.usehdwr.size" system property when a java program named programName is run.
java -Dibm.DES.usehdwr.size=80 programName

This value can also be set programatically with the Java System.setProperty() method.

Triple DES (aka DESede or 3DES): Keys
The hardware JCE implementation (IBMJCECCA) extends the triple DES key available in the software JCE implementation (IBMJCE). In the IBMJCE implementation, the actual triple DES key material is stored in the key object. The IBMJCECCA implementation extends this by adding the following alternative representations:
A triple DES key previously stored in the CKDS. The key object will contain the CKDS label for the key.
The following illustrates creating a triple DES key object for a key already stored in the CKDS with the label "MYENCRYPTEDTDESKEY" and then (for purposes of illustration) deleting the CKDS entry.
// create a key object for an existing CKDS entry
// (No checking is done to verify that the entry exists, or
// that the key it contains is actually a DESede key.)
//
SecretKeyFactory desKeyFactory =
        SecretKeyFactory.getInstance("DESede", "IBMJCECCA");
KeyLabelKeySpec spec =
        new KeyLabelKeySpec("MYENCRYPTEDTDESKEY");
SecretKey key = desKeyFactory.generateSecret(spec);

// delete the entry from the CKDS
// (An exception is thrown if the CKDS entry does not exist.)
//
key.deleteCKDSEntry();

//
// Note that, in this example, the Java key object still
// exists, but the CKDS entry it represents has been deleted.
// Any attempt to use the object "key" will cause an exception
// containing a hardware return code and reason code.
//
                        
On z800 and z900 machines, a key object containing the CKDS label for an encrypted DES key can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
On z890, z990, and newer zSeries processors, a key object containing the CKDS label for a clear DES key can be used for CBC mode, CFB mode, or ECB mode encryption and decryption with the IBMJCECCA provider. This environment also supports using a key object containing the CKDS label for an encrypted DES key for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object containing the CKDS label for an encrypted triple DES key can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).
A triple DES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear triple DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain a triple DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains a triple DES hardware token. Unwrapping to a key object containing a triple DES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping triple DES keys, see RSA
A triple DES key generated by an IBMJCECCA call to the underlying hardware. The key object will contain a hardware token. This token contains the key encrypted with the host master key. The key material for this type of key is never resident in system memory in clear form.
The following illustrates generating a triple DES key object containing a hardware key token
// create a new key token and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec();
KeyGenerator keyGen =
        KeyGenerator.getInstance( "DESede", "IBMJCECCA" );
keyGen.init( ccaAlgParmSpec, null );
Key tdesKey = keyGen.generateKey();
                        
A key object containing a triple DES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object containing a triple DES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).
A triple DES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear triple DES key. If the RSA Cipher object is initialized with a CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain a triple DES hardware token. Unwrapping to a key object containing a triple DES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping triple DES keys, see RSA
A triple DES key generated by an IBMJCECCA call to the underlying hardware and then stored in the CKDS. The key object will contain the label for the new CKDS entry. The CKDS entry holds a token that contains the key encrypted with the host master key. The key material for this type of key is never resident in system memory in clear form.
The following illustrates generating a protected triple DES key token, storing it in a new CKDS entry with an automatically generated label, and creating a key object containing the label for the CKDS entry.
// create a new CKDS entry and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);
KeyGenerator keyGen = KeyGenerator.getInstance("DESede","IBMJCECCA");
keyGen.init(ccaAlgParmSpec,null);
Key thisKey = keyGen.generateKey();
                        
The following illustrates generating a protected triple DES key token, storing it in a new CKDS entry with the label "ATRIPLEDESTOKENINCKDS", and creating a key object containing the label for the CKDS entry.
// create a new CKDS entry and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS,
                                      "ATRIPLEDESTOKENINCKDS");
KeyGenerator keyGen = KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGen.init(ccaAlgParmSpec, null);
Key thisKey = keyGen.generateKey();
                        
A key object representing a triple DES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object representing a triple DES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).
A triple DES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear triple DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain a triple DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains a triple DES hardware token. Unwrapping to a key object containing the label for a CKDS entry that contains a triple DES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping triple DES keys, see RSA
Triple DES (aka DESede or 3DES): Operations

Although all triple DES ciphers are available in the IBMJCECCA provider, they are not all available in the hardware devices. The hardware cryptographic devices only support the Cipher Block Chaining (CBC) and Electronic Code Book (ECB) version of triple DES. That is, all of the triple DES ciphers are supported by the IBMJCECCA provider, but only CBC and ECB use hardware cryptography.
Triple DES is slightly more compute intensive than DES, but like DES is less compute intensive than asymmetric algorithms such as RSA. Therefore, for smaller data sizes, software triple DES cryptography can be faster than hardware triple DES cryptography. For this reason, triple DES with CBC or ECB is also implemented in software within the IBMJCE4758 provider. The same "clip level" (specified in a system property called "ibm.DES.usehdwr.size") is used to determine the data size at which hardware cryptography is used for triple DES. For more information about the "ibm.DES.usehdwr.size" system property, see the discussion above.

AES: Keys
The hardware JCE implementation (IBMJCECCA) extends the AES key available in the software JCE implementation (IBMJCE). In the IBMJCE implementation, the actual AES key material is stored in the key object. The IBMJCECCA implementation extends this by adding the following alternative representation:
An AES key previously stored in the CKDS. The key object will contain the CKDS label for the key.

The following illustrates creating an AES key object for a key already stored in the CKDS with the label "MYENCRYPTEDAESKEY" and then (for purposes of illustration) deleting the CKDS entry.
// create a key object for an existing CKDS entry
// (No checking is done to verify that the entry exists, or
// that the key it contains is actually an AES key.)
//
SecretKeyFactory aesKeyFactory =
        SecretKeyFactory.getInstance("AES", "IBMJCECCA");
KeyLabelKeySpec spec =
        new KeyLabelKeySpec("MYENCRYPTEDAESKEY");
SecretKey key = aesKeyFactory.generateSecret(spec);

// delete the entry from the CKDS
// (An exception is thrown if the CKDS entry does not exist.)
//
key.deleteCKDSEntry();

//
// Note that, in this example, the Java key object still
// exists, but the CKDS entry it represents has been deleted.
// Any attempt to use the object "key" will cause an exception
// containing a hardware return code and reason code.
//
                        
A key object containing the CKDS label for a clear AES key can be used for CBC mode, CFB mode, or ECB mode encryption and decryption with the IBMJCECCA provider.
A key object containing the CKDS label for an encrypted AES key can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).

An AES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear AES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain an AES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains an AES hardware token. Unwrapping to a key object containing an AES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping AES keys, see RSA
An AES key generated by an IBMJCECCA call to the underlying hardware. The key object will contain a hardware token. This token contains the key encrypted with the host master key. The key material for this type of key is never resident in system memory in clear form.
The following illustrates generating an AES key object containing a hardware key token
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec();
KeyGenerator keyGen =
        KeyGenerator.getInstance( "AES", "IBMJCECCA" );
keyGen.init( ccaAlgParmSpec, null );
Key aesKey = keyGen.generateKey();
                   
A key object containing an AES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).
An AES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear AES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain an AES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains an AES hardware token. Unwrapping to a key object containing an AES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping AES keys, see RSA
An AES key generated by an IBMJCECCA call to the underlying hardware and then stored in the CKDS. The key object will contain the label for the new CKDS entry. The CKDS entry holds a token that contains the key encrypted with the host master key. The key material for this type of key is never resident in system memory in clear form.
The following illustrates generating a protected AES key token, storing it in a new CKDS entry with an automatically generated label, and creating a key object containing the label for the CKDS entry.
// create a new CKDS entry and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);
KeyGenerator keyGen = KeyGenerator.getInstance("AES", "IBMJCECCA");
keyGen.init( ccaAlgParmSpec, null );
Key thisKey = keyGen.generateKey();
                   
The following illustrates generating a protected AES key token, storing it in a new CKDS entry with the label "ANAESTOKENINCKDS", and creating a key object containing the label for the CKDS entry.
// create a new CKDS entry and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS,
                                      "ANAESTOKENINCKDS");
KeyGenerator keyGen = KeyGenerator.getInstance("AES", "IBMJCECCA");
keyGen.init(ccaAlgParmSpec, null);
Key thisKey = keyGen.generateKey();
                   
A key object representing an AES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object representing an AES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host. This is not supported for AMODE(64).
An AES key that has been wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object will contain a clear DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain an AES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains an AES hardware token. Unwrapping to a key object containing the label for a CKDS entry that contains an AES hardware token is not supported for AMODE(64).
For more information about wrapping and unwrapping AES keys, see RSA
AES: Operations

The hardware JCE implementation (IBMJCECCA) of AES does not change any of the APIs that are available in software JCE implementation (IBMJCE). Therefore, an application that used the AES capabilities of the IBMJCE will not require modification to use the IBMJCECCA, except for specific references to the provider. For example, if a call to the getInstance() API specified the IBMJCE provider, it will be necessary to change the call to specify the IBMJCECCA provider instead.
The IBMJCECCA provider hardware cryptographic devices only support the Cipher Feedback (CFB), the Cipher Block Chaining (CBC) and the Electronic Code Book (ECB) versions of AES. Software failover support, as provided for DES and DESede, is available for AES ECB ciphers and AES CBC ciphers only.

RSA: Keys
The hardware JCE implementation (IBMJCECCA) extends the RSA keys available in the software JCE implementation (IBMJCE). In the IBMJCE implementation, the actual RSA key material is stored in the key object. The IBMJCECCA implementation extends this by adding the following alternative representations:
An RSA key pair previously stored in the PKDS. The key objects will contain the PKDS label for the keys.

The following illustrates creating RSA key objects for a key pair already stored in the PKDS with the label "MYRSAKEYPAIR" and then (for purposes of illustration) deleting the PKDS entry. // create key objects for an existing PKDS entry // (No checking is done to verify that the entry exists.) // KeyFactory rsaKeyFactory = KeyFactory.getInstance("RSA", "IBMJCECCA"); KeyLabelKeySpec spec = new KeyLabelKeySpec("MYRSAKEYPAIR"); PublicKey pubKey = rsaKeyFactory.generatePublic(spec); PrivateKey privKey = rsaKeyFactory.generatePrivate(spec); // delete the entry from the PKDS // (An exception is thrown if the PKDS entry does not exist.) // ((RSAPrivateHWKey)privKey).deletePKDSEntry(); // // Note that, in this example, the Java key objects still // exist, but the PKDS entry they represent has been deleted. // Any attempt to use the objects "pubKey" or "privKey" will // cause an exception containing a hardware return code and // reason code. //
An RSA key pair generated by an IBMJCECCA call to the underlying hardware and then stored in the PKDS. The key objects will contain the PKDS label for the keys.

The following illustrates generating an RSA key pair stored in the PKDS with an automatically generated label and creating key objects containing the label for the PKDS entry. // create a new PKDS entry and key objects to represent it. // AlgorithmParameterSpec spec = new RSAKeyParameterSpec(1024, KeyHWAttributeValues.PKDS, KeyHWAttributeValues.KEYMANAGEMENT); KeyPairGenerator generator = KeyPairGenerator.getInstance("RSA", "IBMJCECCA"); generator.initialize(spec); KeyPair keyPair = generator.generateKeyPair(); PublicKey pubKey = keyPair.getPublic(); PrivateKey privKey = keyPair.getPrivate(); // delete the entry from the PKDS // (An exception is thrown if the PKDS entry does not exist.) // ((RSAPrivateHWKey)privKey).deletePKDSEntry(); // // Note that, in this example, the Java key objects still // exist, but the PKDS entry they represent has been deleted. // Any attempt to use the objects "pubKey" or "privKey" will // cause an exception containing a hardware return code and // reason code. // The following illustrates generating an RSA key pair stored in the PKDS with the label "ANRSAKEYPAIR" and creating key objects containing the label for the PKDS entry. // create a new PKDS entry and key objects to represent it // AlgorithmParameterSpec spec = new RSAKeyParameterSpec(1024, KeyHWAttributeValues.PKDS, KeyHWAttributeValues.KEYMANAGEMENT, "ANRSAKEYPAIR".getBytes("8859_1")); KeyPairGenerator generator = KeyPairGenerator.getInstance("RSA", "IBMJCECCA"); generator.initialize(spec); KeyPair keyPair = generator.generateKeyPair(); PublicKey pubKey = keyPair.getPublic(); PrivateKey privKey = keyPair.getPrivate(); // delete the entry from the PKDS // (An exception is thrown if the PKDS entry does not exist.) // ((RSAPrivateHWKey)privKey).deletePKDSEntry(); // // Note that, in this example, the Java key objects still // exist, but the PKDS entry they represent has been deleted. // Any attempt to use the objects "pubKey" or "privKey" will // cause an exception containing a hardware return code and // reason code. //
RSA: Operations
Both RSA encryption and decryption are available in the IBMJCECCA provider using hardware cryptography. Because the RSA algorithm is quite compute intensive, using hardware cryptography provides significant performance improvements over software cryptography. Using hardware to perform the RSA encryption and decryption also allows use of the more secure PKDS stored key pairs and RETAINED key pairs. With a PKDS stored key pair or a RETAINED key pair, the sensitive private key is never made available in the clear.
In software implementations of JCE providers (such as IBMJCE), RSA encryption and decryption are implemented with PKCS 1 type 2 padding. RSA encryption and decryption with PKCS 1 type 2 padding is also implemented in hardware cryptography and available with the IBMJCECCA provider.
However, there are two restrictions imposed by the hardware:

The type of key pair that is needed
The hardware implementation of RSA requires that the keys used to encrypt/decrypt data be generated to have a key usage of KEYMANAGEMENT. This means that when the RSA key pair is generated the key usage must be set to KEYMANAGEMENT.

The maximum length of the data that can be encrypted or decrypted
The hardware implementation of RSA limits the amount of data to be encrypted or decrypted to 245 bytes or 11 bytes smaller that the modulus size of the key, in bytes, which ever is smaller.

The IBMJCECCA provider also implements RSA encryption/decryption with "zero padding". This padding scheme is not supported by all JCE providers. The default padding scheme is PKCS 1 type 2 padding for the IBMJCECCA provider.
The following illustrates creating an instance of an RSA Cipher with "zero padding"
Cipher myCipher = Cipher.getInstance("RSA/ /ZeroPadding", "IBMJCECCA");

The following illustrate creating an instance on an RSA Cipher with "PKCS 1 type 2 padding"
Cipher myCipher = Cipher.getInstance("RSA/ /PKCS1Padding", "IBMJCECCA");
Or
Cipher myCipher = Cipher.getInstance("RSA", "IBMJCECCA"); // accept the default padding

The IBMJCECCA provider supports RSA wrapping of a symmetric key for export to another host. The following keys are supported for RSA wrapping:

a key object containing a clear AES,DES, or triple DES key.
a key object containing a CKDS label for an encrypted AES, DES or triple DES key
a key object containing a hardware token with an encrypted AES, DES or triple DES key.
The following keys are not supported for RSA wrapping with AMODE(64):

a key object containing a CKDS label for an encrypted AES, DES or triple DES key.
a key object containing a hardware token with an encrypted AES, DES or triple DES key.

The IBMJCECCA provider supports RSA unwrapping of a symmetric key for import from another host. By default, the resulting (unwrapped) key object will contain a clear key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain a hardware token. This token will contain the key encrypted with the host master key. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains a hardware token. This token will contain the key encrypted with the host master key. Unwrapping to a key object containing a hardware token is not supported with AMODE(64).
The following illustrates generating a triple DES key object containing a clear key, wrapping it, then unwrapping it to a triple DES key object containing a clear key.
// Generate a clear triple DES key
//
KeyGenerator keyGen =
        KeyGenerator.getInstance("DESede", "IBMJCECCA");
Key tdesKey = keyGen.generateKey();

// Generate an RSA key pair
//
KeyPairGenerator rsaKeyPairGen =
        KeyPairGenerator.getInstance("RSA","IBMJCECCA");
rsaKeyPairGen.initialize(1024);
KeyPair rsaKeyPair = rsaKeyPairGen.generateKeyPair();
PublicKey rsaPub = rsaKeyPair.getPublic();
PrivateKey rsaPriv = rsaKeyPair.getPrivate();

// Wrap the triple DES key as for export
//
Cipher rsaCipher = Cipher.getInstance("RSA","IBMJCECCA");
rsaCipher.init(Cipher.WRAP_MODE, rsaPub,
               (AlgorithmParameters)null, null);
byte[] wrappedKey = rsaCipher.wrap(tdesKey);

// Unwrap the triple DES key as for import
// Unwrap to a clear key
//
Key unwrappedDesKey =
        rsaCipher.unwrap(wrappedKey, "DESede", Cipher.SECRET_KEY);
        
The following illustrates generating a triple DES key object containing a hardware key token, wrapping it, then unwrapping it to a triple DES key object containing a hardware key token.
// Generate a secure triple DES hardware key
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec();
KeyGenerator keyGen =
        KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGen.init(ccaAlgParmSpec, null);
Key tdesKey = keyGen.generateKey();

// Generate an RSA key pair
//
KeyPairGenerator rsaKeyPairGen =
        KeyPairGenerator.getInstance("RSA","IBMJCECCA");
rsaKeyPairGen.initialize(1024);
KeyPair rsaKeyPair = rsaKeyPairGen.generateKeyPair();
PublicKey rsaPub = rsaKeyPair.getPublic();
PrivateKey rsaPriv = rsaKeyPair.getPrivate();

// Wrap the triple DES hardware key as for export
//
Cipher rsaCipher = Cipher.getInstance("RSA","IBMJCECCA");
rsaCipher.init(Cipher.WRAP_MODE, rsaPub,
               (AlgorithmParameters)null, null);
byte[] wrappedKey = rsaCipher.wrap(tdesKey);

// Unwrap the triple DES key as for import
// Unwrap to a secure hardware key
//
CCAAlgorithmParameterSpec ccaAlgParmSpec_forUnwrap =
        new CCAAlgorithmParameterSpec();
rsaCipher.init(Cipher.UNWRAP_MODE, rsaPriv,
               ccaAlgParmSpec_forUnwrap, null);
Key unwrappedDesKey =
        rsaCipher.unwrap(wrappedKey, "DESede", Cipher.SECRET_KEY);
        
The following illustrates deleting a RSA hardware key object for a key stored in PKDS, with the label "MYRSAKEY".
// Get the key store instance, open an input stream to the
// keystore file and load the key store.
//
KeyStore jceccaks = KeyStore.getInstance("JCECCAKS", "IBMJCECCA");
InputStream istream = new FileInputStream("keyStore.cca");
jceccaks.load(istream, "keystorePW".toCharArray());

// Given the alias for the PKDS key entry, retrieve the private
// hardware key from the key store.
//
PrivateKey privateKey = (PrivateKey) jceccaks.getKey("MYRSAKEY", "myrsakeyPW".toCharArray());

// Delete the RSA hardware PKDS key entry.
//
((RSAPrivateHWKey)privateKey).deletePKDSEntry();

// Delete the RSA key store object.
//
jceccaks.deleteEntry("MYRSAKEY");

// Write the modified key store contents to the key store file.
//
OutputStream ostream = new FileOutputStream("keyStore.cca");
jceccaks.store(ostream, "keystorePW".toCharArray());
         
NOTE: The DSAPrivateHWKey class also has a deletePKDSEntry method. The illustration above can be followed to delete DSA private hardware PKDS key entries by substituting the DSAPrivateHWKey class for the RSAPrivateHWKey class.
HMAC and PBE

The HMAC and PBE algorithms are supported in the IBMJCECCA provider using the same APIs that are supported by software JCE providers such as IBMJCE. However, the IBMJCECCA provider supports them by making use of other algorithms implemented in the cryptographic hardware.

Keystores for IBMJCECCA

The IBMJCECCA provider supports four keystores: JCECCAKS, JCE4758KS, JCECCARACFKS, and JCE4758RACFKS. The JCECCAKS uses strong encryption (triple DES) to protect the keys when stored in a file. The JCECCARACFKS keystore handles keys and certificates stored in RACF keyrings. The JCE4758KS and JCE4758RACFKS keystores are included for downward compatibility. The JCECCAKS keystore extends and replaces the JCE4758KS keystore. The JCECCARACFKS keystore extends and replaces the JCE4758RACFKS keystore.

JCECCAKS supports migration of keys from other keystores using normal keystore interfaces. The following is a list of keys that are supported by JCECCAKS for migration and for storage:

RSAPrivateHWKey

DSAPrivateHWKey

RSAPrivateKey

RSAPrivateCrtKey

DSAPrivateKey

any SecretKey

For an example of migrating keys from one keystore to another, see Migrate.java in the
$(java_home)/demo/jcecca/src
directory, where $(java_home) is the directory where the Java SDK is installed.

Default Keystore for IBMJCECCA
The default JCE keystore is named .keystore and is located in the user's home directory. The default JCECCAKS keystore is named .HWkeystore and is located in the user's home directory.
On the z/OS platform, the user with ID userid has a default home directory ("user.home") of /home/userid. For example, the user ID "U23LPTQ " would, by default, have a home directory of /home/U23LPTQ.
Configuring and using hardware cryptographic devices on z/OS

To use a hardware cryptographic device, the appropriate card must be installed and configured according to the specifications that are provided with the card. On some platforms it is also necessary for the user or application to set up the cryptographic environment and provide access control (log into the card).

z/OS specifics
On the z/OS platform, access to hardware cryptographic devices is controlled by the Integrated Cryptographic Service Facility (ICSF). The ICSF product provides IBM Common Cryptographic Architecture (CCA) interfaces to hardware devices. ICSF must be configured and running before the hardware cryptographic device is accessed. For more information about ICSF see the ICSF publications, including the following:

Integrated Cryptographic Service Facility Overview - SC23-3977

ICSF System Programmers Guide - SC23-3974

ICSF Administrator's Guide - SC23-3975

The hardware keytool application (hwkeytool)

With few exceptions, the hardware keytool application (hwkeytool) uses the same syntax and commands as the software version provided with JCA (keytool). The differences between hwkeytool and keytool are as follows:

hwkeytool provides additional parameters to the genkeypair, genseckey, and delete commands.
The default keystore is .HWkeystore, although the JCE default (.keystore) can be specified using the -keystore parameter.

The additional parameters for genkeypair are:

-keylabel
[-keylabel <keylabel>]

If -hardwaretype PKDS is specified, this optional parameter is used to specify the label that will identify the hardware key within the hardware storage. If -hardwaretype PKDS is specified and this parameter is not specified, a random label is generated.

-hardwaretype
[-hardwaretype <hardwaretype>]

This optional parameter is used to set the type of key pair generated (CLEAR, PKDS, RETAINED). If this parameter is not specified when generating a DSA key pair, the generated key pair is type PKDS. If this parameter is not specified when generating an RSA key pair, the generated key pair is type CLEAR.

-hardwareusage
[-hardwareusage <hardwareusage>]

This optional parameter is used to set the usage (SIGNATURE, KEYMANAGEMENT) for a generated key pair. If this parameter is not specified, when generating a DSA key pair, the generated key pair has usage SIGNATURE. If this parameter is not specified when generating an RSA key pair, the generated key pair has usage KEYMANAGEMENT.

-existinglabel
[-existinglabel <existinglabel>]

This optional parameter is used to specify the PKDS label for an existing PKDS key entry. When using this parameter, the genkeypair request will create a key object for this PKDS key entry. The -file parameter must be specified to include the certificate file associated with the PKDS key entry. The parameters -hardwaretype, -hardwareusage, -keysize, -dname, -sigalg, -keylabel and -validity are not required and must not be specified.

-file
[-file <cert_file>]

This optional parameter is used to specify the certificate file associated with a PKDS key entry. This parameter must be specified when -existinglabel is specified.

The additional parameters for genseckey are:

-hardwaretype
[-hardwaretype <hardwaretype>]

This optional parameter is used to set the type of secret key generated (CLEAR, PROTECTED, or CKDS). If this parameter is not specified, the generated key is type CLEAR.

-keylabel
[-keylabel <keylabel>]

If -hardwaretype CKDS is specified, this optional parameter is used to specify the label that will identify the hardware key within the hardware storage. If -hardwaretype CKDS is specified and the -keylabel parameter is specified, the request is for a new key to be generated and stored in the CKDS using the specified keylabel. If -hardwaretype CKDS is specified and neither this parameter nor the -existinglabel parameter is specified, the request is for a new key to be generated and a random CKDS label generated.

-existinglabel
[-existinglabel <existingkeylabel>]

If -hardwaretype CKDS is specified, this optional parameter is used to specify the label that identifies the hardware key within the hardware storage. If -hardwaretype CKDS is specified and the -existinglabel parameter is specified, the request is for a key object representing a key already stored in the CKDS with the specified keylabel.

The additional parameter for delete is:

-hardwarekey
[-hardwarekey]

This optional parameter is used to specify that the key pair be deleted from both the keystore and the hardware. If this parameter is not specified, the key is only deleted from the keystore.

The concept of -hardwareusage is introduced with the hwkeytool. By using this parameter when creating a key pair, you can specify the authority that key pair will have in the CCA provider. The hwkeytool interfaces support the hardwareusage values SIGNATURE and KEYMANAGEMENT. A key pair created with hardwareusage SIGNATURE is valid for signatures (sign and verify) only. A keypair created with hardwareusage KEYMANAGEMENT is valid for signatures and for key management functions. The Java Cryptography Architecture also defines hardwareusage type CCA, for keys used for key management only, but this is not supported by hwkeytool because it is not useful to applications. Key pairs with hardwareusage SIGNATURE and KEYMANAGEMENT behave similarly in JCE because both can be used for signatures. Key pairs with hardwareusage KEYMANAGEMENT are needed for other components of Java, including the Java Secure Sockets Layer (JSSE).

The concept of -keylabel is introduced with the hwkeytool. By using this parameter when creating a secret key or keypair, you can specify the label that will be used to identify the hardware key within the hardware storage. That is, -keylabel can be specified when creating a key or key pair to set a specific label that the CCA software will use to identify the key or key pair for storage and retrieval. This label is not used by normal JCE applications, but is made available for the advanced user who needs to control the label used by underlying CCA software to identify the key or key pair. In other words, a normal JCE application will identify the keypair by name (alias); this label is only used by the CCA software to identify CKDS, PKDS, and/or RETAINED key entries. By default, the JCE methods generate a random label to identify the key entry.

The concept of -existinglabel is introduced with the hwkeytool. By using this parameter when creating a key or key pair object, you indicate that the key or key pair is already stored within the hardware storage with the label you specify as the -existinglabel value. That is, -existinglabel can be used when creating a secret key or key pair object to specify the label that must be used to identify the secret key or key pair for retrieval. This label is not used by normal JCE applications, but is made available for the advanced user who needs to use keys stored in the underlying CCA software to identify the key or key pair. In other words, a normal JCE application will identify the keypair by name (alias); this label is only used by the CCA software to identify CKDS keys and PKDS and/or RETAINED key pairs.

The following illustrates creating and storing an RSA key pair with the name Test1 with PKDS hardware:
hwkeytool -genkeypair -alias Test1 -keyalg RSA -storetype JCECCAKS -dname "cn=Test one, ou=JCA, o=IBM, l=Endicott, st=NY" -keypass test123 -storepass 123test -hardwaretype PKDS -hardwareusage SIGNATURE

The following illustrates deleting that key entry from the keystore and also deleting the keys from hardware storage:
hwkeytool -delete -alias Test1 -keypass test123 -storepass 123test -hardwarekey

Software to Hardware Key Migration Aids
At times it might be desirable to migrate a software key into a JCECCAKS hardware keystore. To aid in this process, the class com.ibm.crypto.hdwrCCA.provider.WrapperKey has been created. An instance of this class is a wrapper that contains a software key and the hardware attributes to associate with the key when it is imported into the hardware keystore.

The following code snippet illustrates wrapping a software key "SoftwareKey" and inserting it into keystore "okeyStore":
     byte storeType = KeyHWAttributeValues.RETAIN;
     byte keyUsage = KeyHWAttributeValues.KEYMANAGEMENT;
     keyAttribs = new RSAKeyHWAttributes(storeType,keyUsage);
     WrapperKey wrappedKey =
          new WrapperKey((java.security.PrivateKey)SoftwareKey,keyAttribs);

     okeyStore.setKeyEntry(alias, wrappedKey, istorePass, certs);
    
SAF (RACF) Digital Certificate Support for z/OS Specifics
Introduction

The digital certificate support in the System Authorization Facility (SAF) and implementations in external security managers such as RACF provide applications with an alternative to storing certificates and/or keys in datasets or files. Previously, Java security providers on z/OS were unable to take advantage of the digital certificate support in SAF because there was no Java keystore that supported SAF. The JCECCARACFKS and JCERACFKS keystores now available in the SDK provides SAF digital certificate support, enabling the IBMJCE and IBMJCECCA providers to store and retrieve keys and certificates from SAF.
See Key Management for more information on keystores.

Digital certificate support is implemented as two Keystore types, JCERACFKS and JCECCARACFKS. An InputStream class called RACFInputStream, an OutputStream class called RACFOutputStream, and a URLStreamHandler class are also implemented. The URLStreamHandler class enables a RACFInputStream or RACFOutputStream to be accessed using a URL. URLStreamHandlers are also available for both the IBMJCE keytool program and the IBMJCECCA keytool program (hwkeytool) for z/OS. See the keytool users guide for more information on keytool.

The RACF keystore classes, JCERACFKS for the IBMJCE provider and JCECCARACFKS for the IBMJCECCA provider, are only available on the z/OS platform where SAF is available.

A keystore class, JceRACFKeyStore, is implemented in both the IBMJCE and IBMJCECCA providers. This class is available for storing and retrieving certificates and keys from a RACF key ring. The RACFInputStream and RACFOutputStream are only intended to be used with the JceRACFKeyStore. Use of the RACFInputStream or RACFOutputStream with other Key Stores may cause unexpected results.

All of the JAVA RACF services, including the JceRACFKeyStore, RACFInputStream and RACFOutputStream, make use of the R_datalib (IRRSDL00) service to retrieve and store certificates from RACF. In order to use this service certain authorizations must be granted to the user, depending on the desired setup. Be sure to have the correct authorizations set for R_datalib before using any Java RACF classes. For more information on how to set the necessary authorizations see the following publication:
z/OS Security Server RACF Callable Services - SA22-7691

There are two ways to access keys and certificates stored in an SAF external security manager implementation using the RACFInputStream and RACFOutputStream. The first is using the RACFInputStream or RACFOutputStream directly by passing a newly created instance of it to the JceRACFKeyStore. The second is indirect, using URLStreamHandler to call RACFInputStream or RACFOutputStream and then passing the instance into JceRACFKeyStore. These are described in more detail below.

The JCECCARACFKS and JCERACFKS keystores are able to store and retrieve certificates from a keyring honoring mixed case label and alias names. Users are encouraged to make use of alias or label names that contain at least one different character in their name than the rest of the alias or label names that are attached to the keyring. It is highly encouraged that users do not make use of same character alias or label names that differ only by case. A search mismatch can occur when storing or retrieving information from a JCECCARACFKS and JCERACFKS keystore when using same character label or alias names differing only by case.

Setting up a RACF keyring from RACF
When setting up a keyring, any certificate connected as a "PERSONAL" certificate is considered a KeyEntry and therefore can be used as an end user certificate (for example, in a SSL handshake) since the private key is available. Any certificate connected as "CERTAUTH" is considered a TrustedCertEntry and can be used, for example, as a Certificate Authority (CA) certificate in the authentication process of SSL. Any keyring that has a certificate that is not self signed and is connected as "PERSONAL" must also have the CA certificate of the "PERSONAL" certificate connected as "CERTAUTH". In the case of a self signed certificate, a "CERTAUTH" certificate is not required to be present. Certificates connected as "SITE" are not supported at this time. Below is an example setup of a RACF keyring that can be used by a JSSE client and server for both trust and key information.
            Certificate Label Name Cert Owner USAGE    DEFAULT
            ---------------------- ---------- -------- -------
            PersonalEndUserCert    ID(USERID) PERSONAL YES
            PersonalEndUserCACert  CERTAUTH   CERTAUTH NO
            
Using a RACFInputStream to load a RACF key ring into a Java RACF KeyStore

Creating a RACFInputStream requires these three parameters:

userID - a string containing the ID of the user that owns the keyring

ringid - a string containing the name of the RACF key ring

password - a character array containing the password for the keystore

The following is an example of using RACFInputSteam directly, passing it a user ID, a ring ID and a null password.
In the above example, the system property "user.name" is used to obtain the userid that will be passed to RACF. In an actual application, this will probably not be done.

Using a RACFOutputStream to store a Java RACF KeyStore into a RACF key ring

Creating a RACFOutputStream requires these three parameters:

userID - a string containing the ID of the user that owns the keyring

ringid - a string containing the name of the RACF key ring

password - a character array containing the password for the keystore

The following is an example of using RACFOutputStream directly, passing it a user ID, a ring ID and a null password.
In the above example, the system property "user.name" is used to obtain the userid that will be passed to RACF. In an actual application, this will probably not be done.

Storing keys into RACF using the RACFKeyStore

The RACF KeyStore can be used to update an existing RACF key ring or create a new RACF key ring. If the RACF key ring specified by the userid and ring name to the RACFOutputStream does not exist, the Key Ring will be created. If the RACF Key Ring already exists, then it will be updated. In either case, all certificates and keys in the KeyStore will be added to the RACF key ring when the store method is invoked. When updating an existing RACF key ring, any existing RACF certificates and keys that are deleted, will be removed from the RACF key ring when the store method is invoked.

Entries deleted from the RACF KeyStore will be removed from the RACF key ring, but the RACF certificate profile will not be deleted from RACF. If a certificate is added that already exists in RACF, but with a different label/alias, the certificate will be added to the RACF Key Ring with the existing label, and an IOException will be returned to indicate the certificate already exists with a different label/alias.

If an error is detected while updating a RACF Key Ring, all additional adds or deletes of entries are processed, but only the first error will be reported as an exception.
The following scenario demonstrates this property:

A RACFInputStream is created to specify an existing input RACF Key Ring.
The RACFInputStream is loaded into a RACFKeyStore using the RACFKeyStore.load() method.
The input ring contains 1 key entry named Key01 and 1 trusted certificate entry named Cert01.
Key01 is deleted using the RACFKeyStore.delete() method.
Two new key entries named Key02 and Key03 are added to the RACFKeyStore using the RACFKeyStore.setKeyEntry() method.
A RACFOutputStream is created to specify an output RACF Key Ring.
The updates are written to the RACF Key Ring specified in the RACFOutputStream using the RACFKeyStore.Store() method.

First, the delete entry is processed by successfully removing Key01 from the output RACF Key Ring.
Next, all entries from the RACFKeyStore are added to the output RACF Key Ring.
In this example, an error occurs while attempting to add Key02 to the output RACF Key Ring.
Cert01 is added successfully to the output RACF Key Ring.
An error occurs while attempting to add Key03 to the output RACF Key Ring.

An exception is thrown with the details of the error that occured while attempting to add Key02.

Accessing a RACFInputStream and RACFOutputStream using URLStreamHandler

In SDK 1.2 and above, the URLStreamHandler class enables access to data using user defined classes. The system property java.protocol.handler.pkgs allows the application to define the classes that access the data. The URL "safkeyring " and associated classes access data stored in an SAF (RACF) keyring.

The following java property must be defined to enable the URLStreamHandler class to create a RACFInputStream:

If the IBMJCE provider is being used to provide cryptographic support, the property must be set to the value com.ibm.crypto.provider. The following example illustrates setting this property on the java command line when running the Java class "myApplication":

If the IBMJCECCA provider is being used to provide cryptographic support, the property must be set to the value com.ibm.crypto.hdwrCCA.provider. The following example illustrates setting this property programatically in a Java application:

Supported key types for storing into a RACF KeyStore

The JCERACFKS RACF Key Store supports the following Java key types:

RSAPrivateKey - Software format

RSAPrivateCrtKey - Software CRT format

The JCECCARACFKS RACF Key Store supports the following Java key types:

RSAPrivateKey - Software key format
This key type is converted to RSAPrivateHWKey format

RSAPrivateCrtKey - Software CRT format
This key type is converted to an RSAPrivateHWKey format

RSAPrivateHWKey - CLEAR Format with External ICSF Token

RSAPrivateHWKey - PKDS Format

All other key formats are not supported.

Passwords and the RACF KeyStore

In file based KeyStores the password parameter is used for three primary reasons:

Protect the integrity of the KeyStore file

Protect keys in Java memory while being used in a KeyStore

Protect keys when at rest in the file based KeyStore

The password parameter is used differently by the RACF KeyStore. Since keys in the RACF KeyStore are stored in the RACF Data Base rather than in a file, the password is only used to protect keys while the KeyStore is in Java memory. Digital Certificates and Keys in RACF Key Rings are protected by RACF profiles.

All the following RACF KeyStore methods use the password parameter:
The RACFInputStream.RACFInputStream() method uses the input password to protect keys loaded from RACF in Java memory.

The JceRACFKeyStore.load() method uses the input password to validate that the input RACFInputStream is constructed with the same password.

The JceRACFKeyStore.setKeyEntry() method uses the input password to protect the input key.

The JceRACFKeyStore.getKeyEntry() method uses the input password to recover the protected key.

The JceRACFKeyStore.store() method uses the input password to validate that the input RACFOutputStream is constructed with the same password.

The RACFInputStream.RACFOutputStream() method uses the input password to recover any protected keys from Java memory before storing them to a RACF Key Ring.

In addition to KeyStore passwords, Java APIs enable an application to specify a password to protect an individual KeyStore entry. Within an instance of using the JceRACFKeyStore, RACFInputStream and RACFOutputStream to retrieve and set keys, the same password must be used. It is recommended that all passwords are left to default.

The password parameter defaults to "password" on all methods by passing in null.

hwkeytool and the ICSF CSFSERV and CSFKEYS RACF classes

If the user of hwkeytool is not authorized to create new profiles in the ICSF CSFKEYS RACF class, hwkeytool may create a key that the user is not able to access. To prevent this from happening, the user of hwkeytool should verify that they are authorized to the profiles in the ICSF CSFSERV RACF class including CSFPKG. A number of these ICSF services are used by hwkeytool. In addition, the user of hwkeytool should verify that they have authority to create new profiles in the ICSF CSFKEYS RACF class.

Developers and users of programs that invoke the Java security class KeyPairGenerator to generate an IBMJCECCA public and private key pair should also be aware of above item relating to the ICSF CSFKEYS and CSFSERV RACF classes.

Updates to a JCECCARACFKS KeyStore

A KeyStore is a Java object containing a collection of keys and certificates that are referenced by unique labels or alias names. For most Java keystores, the persistent data is stored in a file. However, the persistent data for a JCECCARACFKS keystore is stored in the RACF database and connected to a RACF keyring. Due to the nature of the RACF database and keyrings, the behavior of a JCECCARACFKS keystore during update operations differs from the behavior of file based keystores.

In the following discussion, "application" can refer to a user KeyStore application or can refer to the hwkeytool utility program.

KeyStore load and update operations

In order to access the contents of a keystore, an application uses the load() method to retrieve the persistent data from the keystore and create a KeyStore object. This object can be queried and updated by the application. KeyStore update methods include deleteEntry(), setEntry(), setCertificateEntry(), and setKeyEntry(). hwkeytool update commands supported for RACF keystores include -delete, -genkeypair, -importcert, and -importkeystore.

If the application intends to modify the persistent data for the keystore, it uses the store() method. The behavior of the store() method depends on the underlying storage of the persistent data.

File based keystores and the KeyStore store() method

The update model for file based keystores is a replace model. When the application uses the store() method for a file based keystore, the contents of the KeyStore object in the application memory replace the current persistent data for the keystore. In other words, any KeyStore update that has been successful will be reflected in the new version of the persistent data for the keystore.

One consequence of the replace model occurs if two applications are updating the same keystore at the same time. To illustrate, suppose application app1 and application app2 are modifying some keystore and

app1 loads the keystore into a KeyStore object and makes some updates
app2 loads the keystore into a KeyStore object and makes some updates
app1 stores the contents of the KeyStore object into the persistent keystore data
app2 stores the contents of the KeyStore object into the persistent keystore data
In this case, because the app1 changes were not stored in persistent data before app2 loaded the keystore, and because app2 replaced the persistent data after app1, updates made by app1 are overwritten by app2.

RACF keystores and the KeyStore store() method

The update model for a JCECCARACFKS keystore is an update model. It was implemented in this way to avoid the effect described above. If a change is made to an existing KeyStore entry, the existing version of the entry is disconnected from the keyring, the data for the new entry is added to the RACF database, and then the new entry is connected to the keyring. Even if the update is a delete operation, whether deleteEntry() or hwkeytool -delete, the data is not removed from the RACF database, it is only disconnected from the keyring represented by the KeyStore. To delete data from the RACF database, you must use the RACF utility RACDCERT.

Some RACF database and keyring updates that are not permitted are:

An entry with an expired certificate cannot be updated.
An entry cannot be updated with an expired certificate.
A certificate entry cannot be replaced with a key entry.
A key entry cannot be replaced with a certificate entry.
An entry cannot be updated unless the public key in the new version matches the public key in the existing version.
Although a single certificate can be connected to many keyrings, there can be only one copy of it in the RACF database and it will be stored with only one label.

When the IBMJCECCA security provider can detect an update that will not be allowed by RACF, an exception is thrown when the KeyStore entry update is attempted. In some cases, the IBMJCECCA security provider can not predict that a RACF database update will be unsuccessful. One consequence of this is that a KeyStore update may be successful but an error or warning is reported during the store() operation.

Some possible effects of this behavior are:

The previous version of the entry is disconnected from the keyring and the new version is not connected to the keyring.
A certificate may be connected to the keyring using a label other than the one specified in the KeyStore update.
If there are unintended and undesired changes to a keystore, it might be necessary to reconnect or to update keyring entries using the RACF utility RACDCERT.

Additional Information:

For more information on inserting or updating information in the RACF External Security Manager refer to the RACDCERT command. Publications available for RACF include:

z/OS Security Server RACF Security Administrator's Guide - SA22-7683

z/OS Security Server RACF Command Language Reference - SA22-7687

z/OS Security Server RACF Callable Services - SA22-7691
Trademarks
IBM is a trademark or registered trademark of International Business Machines Corporation in the United States, or other countries, or both.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
Other company, product, or service names may be trademarks or service marks of others.

Copyright © 1996-2005 Oracle and/or its affiliates. All Rights Reserved.

Copyright © 2001-2013 IBM Corporation, Inc. All Rights Reserved.

z/OS Unique Considerations

for the JavaTM SDK, Standard Edition, v 6

(last updated March, 2013)

Hardware Cryptographic devices for z/OS

Introduction

Types of cryptographic hardware utilization

RETAINED hardware key pairs

PKDS hardware key pairs

CKDS hardware symmetric keys

PROTECTED hardware symmetric keys

CLEAR hardware key pairs and symmetric keys

Key storage overview

Key generation and storage

RSA Signature and Verification

DSA Signature and Verification

MD2, MD5, SHA-1, SHA-256, SHA-384, and SHA-512 hashing algorithms

Random Number generation

IBMJCECCA provider package includes:

Overview of differences between the software JCE implementation and the hardware JCE implementation

Specific Changes and Requirements

The KeyFactory Class:

AES

DES

Triple DES (aka DESede and 3DES)

DSA

RSA

Algorithm Parameters Classes:

The Key Interface Class:

Key Specification Interfaces and Classes

The SecureRandom Class:

Reading Base64-Encoded Certificates

The Signature Class:

Data Encryption Standard (DES): Keys

Data Encryption Standard (DES): Operations

Triple DES (aka DESede or 3DES): Keys

Triple DES (aka DESede or 3DES): Operations

AES: Keys

AES: Operations

RSA: Keys

RSA: Operations

HMAC and PBE

Keystores for IBMJCECCA

Default Keystore for IBMJCECCA

Configuring and using hardware cryptographic devices on z/OS

z/OS specifics

The hardware keytool application (hwkeytool)

Software to Hardware Key Migration Aids

SAF (RACF) Digital Certificate Support for z/OS Specifics

Introduction

Setting up a RACF keyring from RACF

Using a RACFInputStream to load a RACF key ring into a Java RACF KeyStore

Using a RACFOutputStream to store a Java RACF KeyStore into a RACF key ring

Storing keys into RACF using the RACFKeyStore

Accessing a RACFInputStream and RACFOutputStream using URLStreamHandler

Supported key types for storing into a RACF KeyStore

Passwords and the RACF KeyStore

hwkeytool and the ICSF CSFSERV and CSFKEYS RACF classes

Updates to a JCECCARACFKS KeyStore

KeyStore load and update operations

File based keystores and the KeyStore store() method

RACF keystores and the KeyStore store() method

Additional Information:

Trademarks

for the Java^TM SDK, Standard Edition, v 6

The `SecureRandom` Class:

The `Signature` Class: