Hardware Cryptographic Devices for the IBM z® Platform

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 on both Linux for IBM z® and z/OS operating systems. 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). On IBM z® servers running Linux, access to hardware cryptographic devices is controlled by the IBM PCIe Cryptographic Coprocessor software. Both of these software packages, on IBM z® servers running Linux or z/OS, provide IBM Common Cryptographic Architecture interfaces to hardware devices that are leveraged by the IBMJCECCA provider. One or more of these hardware cryptography features must be installed in order to use the IBMJCECCA provider.

Please note that the IBMJCECCA provider is only available on 64 bit SDKs for IBM z® servers running Linux. IBMJCECCA is not supported for 31 bit mode for IBM z® servers running Linux. IBMJCECCA provider is available in both 31 and 64 bit modes for IBM z® servers running z/OS.

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 on z/OS section of this document should be consulted for configuring the correct hardware environment.

The IBMJCECCA provider supports the following:

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 $JAVA_HOME/lib/security/java.security file on z/OS and the $JAVA_HOME/jre/lib/security/java.security file on Linux.

Types of cryptographic hardware utilization

In the cryptography environment there are multiple ways to take advantage of cryptographic hardware. The IBMJCECCA provider supports multiple 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 type supported for asymmetric key pairs is PKDS. The two types supported only for symmetric keys are CKDS and SECURE_INTERNAL_TOKEN. Type CLEAR is supported both for asymmetric key pairs and for symmetric keys. Each type is described in the following sections. 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 than similar cryptographic functions provided by a provider implemented to use only software cryptography.

PKDS hardware key pairs

These keys are known in the CCA architecture as Public Key Algorithm (PKA) key tokens. In this case the PKA key token is subsequently stored in a secure data area. On z/OS the secure data area is the ICSF PKDS dataset. On Linux the secure data area is the key storage file.

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 high 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. On z/OS this key storage area is a RACF-protected data set managed by ICSF. On Linux this key storage area is a file in the filesystem protected by Unix file protection mechanisms and permissions. On z/OS clear key values may be used that are stored within the PKDS. The clear text version of this key can never be viewed or retrieved. What is stored in the JCE keystore file or returned to the application at key pair generation time is only a reference to the private key, called a label. Because the key is stored in a key storage area, 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 provides the highest level of security supported by the IBMJCECCA provider. Operations using PKDS key types are more secure and generally slower than similar operations using the CLEAR type key pairs.

CKDS hardware symmetric keys

These keys are known in the CCA architecture as internal symmetric key tokens. In this case the internal symmetric key token is subsequently stored in a secure data area. On z/OS the secure data area is the ICSF CKDS dataset. On Linux the secure data area is the key storage file.

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 high 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. On z/OS this key storage area is a RACF-protected data set managed by ICSF. On Linux this key storage area is a file in the filesystem protected by Unix file protection mechanisms and permissions. 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 key storage area, 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.

When running on z/OS, the system master key, used to protect the key material, can only be changed using the ICSF component of z/OS. When running on Linux, the system master key, used to protect the key material, can only be changed using the secure key software solution verbs or the key storage initialization utility. When the system master key is changed, all the key entries are re-encrypted such that the keys it contains will be encrypted using the new system master key. This ensures that CKDS type keys remain usable even if the system master key is changed.

The CKDS key type provides 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.

Please note that when running on z/OS, ICSF version HCR7780 or higher is required for creating CKDS hardware symmetric keys.

SECURE_INTERNAL_TOKEN hardware symmetric keys

These keys are known to CCA architecture as internal symmetric key tokens.

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 SECURE_INTERNAL_TOKEN keys. When a SECURE_INTERNAL_TOKEN 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 SECURE_INTERNAL_TOKEN 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.

When running on z/OS the system master key, used to protect the key material, can only be changed using the ICSF component of z/OS. When running on Linux the system master key, used to protect the key material, can only be changed using the secure key software solution verbs or the key storage initialization utility. SECURE_INTERNAL_TOKEN keys are encrypted using the host master key and then stored outside the key storage area, that is, outside the control of CCA spaces. This means that if the system master key is changed, any SECURE_INTERNAL_TOKEN key created using the old system master key becomes unusable and data encrypted using it cannot be decrypted. For this reason, SECURE_INTERNAL_TOKEN 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 SECURE_INTERNAL_TOKEN key type has the highest level of security supported by the IBMJCECCA provider for symmetric keys. Operations using SECURE_INTERNAL_TOKEN key types are more secure and generally slower than similar operations using CLEAR keys.

CLEAR hardware key pairs and symmetric keys

These keys are known to the CCA architecture as clear 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. 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. There is no overhead for retrieving the key from the key storage area, no overhead for decrypting the key using the master key, and no requirement for the cryptographic operation to be processed by a specific hardware device.

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 CKDS and PKDS keys, the application will have only a label. For SECURE_INTERNAL_TOKEN keys, the application will have only an encrypted 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 SECURE_INTERNAL_TOKEN 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 PKDS and CKDS keys. This is because, for 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, DSA (note that DSA is only supported on z800 and z900 hardware) and ECDSA (note that ECDSA is only supported on Crypto Express 3 Coprocessor (CEX3C) and newer cryptographic coprocessor cards) algorithms. 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 two levels of security, CLEAR key pairs and PKDS based key pairs. Cryptographic hardware capabilities increase the base security of the operation (by having the hardware process the algorithm and data), reduce the load on general purpose CPs, potentially increase the throughput rate of the request, and (optionally) permit use of 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.

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.

ECDSA Signature and Verification

Elliptic Curve Cryptography (ECC) is an encryption system that uses the properties of elliptic curves to provide the same functionality as other public cryptographic systems. The primary benefit provided by ECC is reduced key sizes, and is therefore faster and less compute intensive than equivalent RSA operations.

Note that the ECDSA algorithm is only supported on Crypto Express 3 Coprocessor (CEX3C) and newer cryptographic coprocessor cards.

MD2, MD5, and SHA hashing algorithms

Hashing algorithms are not as compute intensive as the RSA, DSA and ECDSA 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, DSA or ECDSA 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.

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.

There are two optional Java properties, ibm.hwrandom.useicsfcache and ibm.hwrandom.cachesize, that can be used to configure a caching implementation of the CCA hardware random number generator. Upon the load of the IBMJCECCA provider, these properties will be used to configure the default SecureRandom implementation for the remainder of the JVM lifespan unless the property states are changed programatically and then the IBMJCECCA provider is reloaded. By using the caching implementation a user may experience improved performance. The potential for performance improvement depends on the type of workload being run. Experimentation with the cachesize property may be necessary to see what benefits (if any) may be visible for any given workload.

ibm.hwrandom.useicsfcache=[true|false]

Used to specify caching of secure random numbers fetched from CCA APIs. To set the SecureRandom implementation to use caching set the ibm.hwrandom.useicsfcache java property to true. For example:

java -Dibm.hwrandom.useicsfcache=true MyApplication

ibm.hwrandom.cachesize=[size]

Used to specify the size ( in bytes ) of the cache for caching secure random numbers fetched from CCA APIs. If a user enables CCA caching they can optionally specify the desired size of the cache (in number of bytes). For example:

java -Dibm.hwrandom.cachesize=14400 -Dibm.hwrandom.useicsfcache=true MyApplication

If not specified the cache size will default to 14400 bytes. This variable must be set to a value that is an integer value greater than 0. If the ibm.hwrandom.useicsfcache Java property is not set to true the ibm.hwrandom.cachesize Java property variable will be ignored.

IBMJCECCA provider package includes:

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, described in detail in the Specific Changes and Requirements section, 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 provider 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, DSA or EC with appropriate attributes (described in the Specific Changes and Requirements section) 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 smaller 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. 

Overview of differences between servers running Linux for IBM z® and z/OS

The IBMJCECCA provider supports IBM z® servers running either Linux or z/OS. There are a few differences between execution on the two operating systems:

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 CCA key storage areas such as the CKDS on z/OS and the key storage files on Linux. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CCA 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 CCA key storage areas such as the CKDS on z/OS and the key storage files on Linux. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CCA 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 been stored previously in CCA key storage areas such as the CKDS on z/OS and the key storage files on Linux. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CCA label for the key.

Other keySpec classes supported by the triple DES KeyFactory include the DESedeKeySpec and the SecretKeySpec.

HMAC

The IBMJCECCA provider supports a key type for HMAC keys that have been stored previously in CCA key storage areas such as the CKDS on z/OS and the key storage files on Linux. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CCA label for the key.

SecretKeyFactory HMAC algorithms supported by the IBMJCECCA provider are HMACSHA1, HMACSHA224, HMACSHA256, HMACSHA384, and HMACSHA512.

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 CCA key storage area 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.

EC

The IBMJCECCA provider adds a new key type for EC private hardware keys that is similar to the EC Private keys available in software providers. EC private hardware keys are objects of type ECPrivateHWKey. The corresponding EC public keys are objects of type ECPublicKey.

The KeyFactory class can be used to generate an EC private hardware key from an ECPrivateHWKeySpec, PKCS8EncodedKeySpec, ECPrivateKeySpec or KeyLabelKeySpec. The KeyFactory class can also be used to generate an EC public key from an ECPublicKeySpec, X509EncodedKeySpec or KeyLabelKeySpec. Keys that are already in the CCA key storage area can be created by passing a KeyLabelKeySpec to the EC KeyFactory class.

The KeyFactory class can also derive an ECPrivateHWKeySpec or KeyLabelKeySpec from an EC private hardware key, or an ECPublicKeySpec or X509EncodedKeySpec from an EC public key.

Note that a RSAPrivateKeyHWSpec, DSAPrivateKeyHWSpec and ECPrivateHWKeySpec 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 or unwrapped will be a secret hardware key and whether it will be stored in the CCA key storage area.

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.

A CCAAlgorithmParameterSpec object can be used to specify the type of CCA key token wrapping to be used for a DES or DESede key that is of type CKDS or SECURE_INTERNAL_TOKEN.

If the CCAAlgorithmParameterSpec object is being used to generate a CKDS type key, the CCAAlgorithmParameterSpec can be used to specify the desired label that is to be used to store the key within the CCA key storage area. If a label is specified, it must be unique in the CCA key storage area and must follow the CCA rules for labels. If no label is specifed for a new CCA 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 has the following constructors:

Parameters that can be passed to the constructors:

CCAAlgorithmParameterSpec has the following methods:

public int getKeySize()
public void setKeySize(int size)

These methods set or return the key size optionally specified to the CCAAlgorithmParameterSpec constructor. If no key size was specified, this value is set to 0.

public byte getHwType()
public void setHwType(byte hwTypeVal)

These methods set or return the key type optionally specified to the CCAAlgorithmParameterSpec constructor. The value will be one of the following constant values:
  • CCAAlgorithmParameterSpec.CLEAR
  • CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN
  • CCAAlgorithmParameterSpec.CKDS

public String getLabel()
public void setLabel(String label)

These methods set or return the CCA key storage label optionally specified to the CCAAlgorithmParameterSpec constructor. If no CCA label was specified, this value is null.

public byte getTokenWrappingMode()
public void setTokenWrappingMode(byte wrappingMode)

These methods set or return the CCA token wrapping mode optionally specified to the CCAAlgorithmParameterSpec constructor. If no wrapping mode specified, this value is DEFAULT.

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:

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:

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

The KeyParameterSpec class for EC hardware (ECHWKeyParameterSpec):

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

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

The Key Interface Class:

As discussed the clear key material for private hardware keys of type PKDS 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 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. One of the following methods can be used to retrieve a representation of a hardware key pair:

public byte [] getToken()

public byte [] getLabelString()

For a DSA key pair, getLabelString() returns the label that represents the key stored in the CCA key storage area.

For a RSA or EC key pair of type CLEAR, getToken() should be used to return an internal CCA token. For a RSA or EC key pair of type PKDS, getLabelString() should be used to return the label that represents the key stored in the CCA key storage area.

Key Specification Interfaces and Classes

The KeyLabelKeySpec Class

This class (which implements the KeySpec Interface) specifies the CCA label for an AES, DES, or DESede key stored in the CCA key storage area. 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 CCA key storage area. Note that generateSecret() does not create a new key in the CCA key storage area and also does not verify that such an entry currently exists in the CCA key storage area.

This class also specifies the CCA key storage area label for a DSA, RSA or EC key pair stored in the system key storage area. If a KeyLabelKeySpec is passed to the generatePrivate() or the generatePublic() method of a RSAKeyFactory or an ECKeyFactory, or to the generatePrivate() method of a DSAKeyFactory, then the key object returned will represent the corresponding key of a key pair already stored in the CCA key storage area. Note that generatePublic() and generatePrivate() do not create a new key in the CCA key storage area and also does not verify that such an entry currently exists in the CCA key storage area.

It has the following methods:

public String getLabelString()

This method returns the CCA label for the key or 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 CCA key storage area key record 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 ECPrivateHWKeySpec Class

This class (which implements the KeySpec Interface) specifies an EC 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 external CCA token or a CCA key storage area key record label.

public ECHWKeyAttributes getAttributes()

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

public ECParameterSpec getParams()

This method returns the the elliptic curve domain parameters 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

See also the Random Number Generation section for further details on configuring the caching version of the SecureRandom implementation for the IBMJCECCA provider.

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:

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:

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 support the Cipher Block Chaining (CBC), Cipher feedback (CFB), Output Feedback (OFB), and Electronic Code Book (ECB) versions of DES. That is, all of the DES ciphers are supported by the IBMJCECCA provider, but only CBC, CFB, OFB, and ECB modes can 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, CFB, OFB, and ECB also were implemented in the IBMJCECCA provider. For small amounts of data, software DES (CBC, CFB, OFB, or ECB) is sometimes faster than hardware DES (CBC, CFB, OFB, or ECB) cryptograhpy. 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 smaller then the configured 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, CFB, OFB, or ECB processing where the data size less than 60 bytes will be performed using software cryptography and any data size 60 bytes or greater will be performed using hardware cryptography. For ciphers other than DES CBC, CFB, OFB, and 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, CFB, OFB, and ECB processing will be performed using hardware cryptography. If you set the system property to -1, all DES CBC, CFB, OFB and ECB processing will be performed using software cryptography. This system property applies to both DES and triple DES CBC, CFB, OFB, 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 following example 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:

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 support the Cipher Block Chaining (CBC), Cipher feedback (CFB), Output feedback (OFB), 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, CFB, OFB, and ECB can 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, CFB, OFB, or ECB is also implemented in software within the IBMJCECCA 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 previous discussion.

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:

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), Output Feedback (OFB), Galois/Counter Mode (GCM), 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.

Symmetric Transport Keys (Key Encrypting Keys)

The IBM Common Cryptographic Architecture (CCA) has a feature called key separation, where it controls the use of keys by separating them into unique usage types, allowing the use of a specific type of key only for its intended purpose. For example, a key used to protect data cannot be used to protect a key.

The IBMJCECCA provider supports symmetric key generation of DATA encrypting keys by default. This key usage type is the most commonly used among symmetric keys, and is used to protect data privacy. In addition to DATA encrypting keys, the IBMJCECCA provider is also capable of generating transport keys, also known as key encrypting keys. Transport keys are used to protect keys during distribution from one system to another. The following types of transport keys are supported by the IBMJCECCA provider:

Transport keys may be generated through a key generator or derived through a Diffie-Hellman key agreement. In both cases, the key generator or key agreement must be initialized with an AlgorithmParameterSpec that contains cryptographic parameters relevant for transport key generation or key derivation, respectively.

On z/OS, CKDS type AES transport keys require a CKDS that supports variable length records. Refer to the section titled Converting a CKDS from fixed length to variable length record format in the ICSF System Programmer's Guide for more information or contact your system administrator.

In general, keys protected with transport keys generated through the IBMJCECCA provider may only be distributed among z systems. Because of the additional security provided by the use of control vectors on a z system, it is unlikely that a key protected with a transport key on a z system will be correctly reconstructed on a non-z system, even when the correct IMPORTER key is used.

A Triple DES transport key with the NoCvKEK option can be used to exchange keys with non-z systems. A Triple DES transport key with the NoCvKEK option can also be used to exchange keys with z systems, but the security of the key exchange is weakened because a transport key with the NoCvKEK option will not use control vectors. The NoCvKEK option can be specified for a Triple DES transport key when the key is created or when the key is imported. Only Triple DES transport keys in the CCA key storage area can have the NoCvKEK option.

The IBMJCECCA key generator generates transport keys in OPEX form consisting of either an EXPORTER/IMPORTER pair or an IMPORTER/EXPORTER pair. OPEX refers to a pair of keys where the first key is in an operational (OP) form and usable by the local system, and the second key is in an exportable (EX) form that needs to be imported prior to being usable on a system. Operational (OP) keys are enciphered directly by the local master key and are represented in Java as Key objects. Exportable (EX) keys, on the other hand, are similar to wrapped keys in Java. Exportable (EX) keys are enciphered by an existing operational (OP) EXPORTER key and are represented in Java as an array of bytes.

For a detailed explanation of key usage types and key forms supported by the IBM Common Cryptographic Architecture (CCA), refer to the section titled Functions of the Symmetric Cryptographic Keys in the Cryptographic Services Integrated Cryptographic Service Facility Application Programmer's Guide. Please note that not all key usage types and key forms that are available in CCA are supported by the IBMJCECCA provider. Furthermore, the IBMJCECCA provider only supports a portion of the transport key functionalities that are available in the CCA.

Generating transport keys with the IBMJCECCA key generator requires an existing transport key. As a result, systems that do not have transport keys will not be able to use the key generator to generate transport keys. A solution for such systems is to utilize IBMJCECCA's Diffie-Hellman key agreement functionality to derive their initial transport keys.

In a two party Diffie-Hellman key agreement scheme using Elliptic Curve keys, which is the only type of Diffie-Hellman key agreement currently supported by the IBMJCECCA provider, one system derives an operational (OP) EXPORTER key while the other system derives the matching operational (OP) IMPORTER key. Keys derived through the key agreement are all operational keys, so existing transport keys are not required in this case. For more information on Diffie-Hellman key agreement using Elliptic Curve keys, please see EC Operations.

When generating Triple DES or AES transport keys using an instance of the IBMJCECCA KeyGenerator class, the com.ibm.crypto.hdwrCCA.provider.DESedeKey or com.ibm.crypto.hdwrCCA.provider.AESKey object returned by the key generator represents the operational (OP) key in the OPEX key pairing. This operational key, like any other Java key, can be used directly on the system.

The matching exportable (EX) key generated by the key generator, on the other hand, is not an actual Java key object and cannot be used directly on the system. Similar to other keys that are wrapped using a cryptographic cipher, it is in an external key token format for export to another system and is represented in Java as an array of bytes. On return from the key generator, this matching exportable (EX) key token may be retrieved by calling the getPairedExternalToken() public method on the returned operational (OP) key. It may then be imported or unwrapped on another system to create an equivalent operational Java key object.

Although the IBMJCECCA key generator stores the generated exportable (EX) key token in the returned Java key object representing the operational (OP) key, the exportable (EX) key is not considered part of the operational (OP) key. As a result, the key token value representing the exportable (EX) key stored in the returned operational (OP) Java key object will not persist when the operational (OP) key is reconstructed, whether through a SecretKeyFactory instance using the key specification of the operational (OP) key or through wrapping and unwrapping of the operational key (OP) with a cryptographic cipher. Calling the getPairedExternalToken() method on the reconstructed operational (OP) key will return null. It is highly recommended to retrieve the external key token of the exportable (EX) key immediately after it is generated by the key generator.

Generating Symmetric Transport Keys (Key Encrypting Keys)

The following illustrates generating an 168-bit Triple DES DATA key containing a hardware key token: 

// use CCAAlgorithmParameterSpec to specify key size of 168
//
CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(168);

// request that an operational DATA key is to be generated
//
ccaAlgParmSpec.setKeyUsage(KeyUsage.OP_DATA);

KeyGenerator keyGenerator = KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGenerator.init(ccaAlgParmSpec, null);

// this key object represents the generated operational (OP) DATA key
//
SecretKey tdesDataKey = keyGenerator.generateKey();

The following illustrates generating a Triple DES hardware EXPORTER/IMPORTER transport key pair where the operational (OP) EXPORTER key contains a hardware key token enciphered by the local master key and the exportable (EX) IMPORTER key is a hardware key token enciphered under an existing triple DES EXPORTER key named tdesPrimaryExporter: 

// use CCAAlgorithmParameterSpec to specify key size of 112
//
CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(112);

// request that a transport key pair is to be generated
// first key is an operational (OP) EXPORTER key
// second key is an exportable (EX) IMPORTER key
//
ccaAlgParmSpec.setKeyUsage(KeyUsage.OPEX_EXPORTER_IMPORTER);

// specify an existing triple DES EXPORTER key to be used for
// enciphering the generated IMPORTER key
//
ccaAlgParmSpec.setKey2KeyEncryptingKey(tdesPrimaryExporter);

KeyGenerator keyGenerator = KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGenerator.init(ccaAlgParmSpec, null);

// this key object represents the generated operational (OP) EXPORTER key
//
DESedeKey tdesExporterKey = (com.ibm.crypto.hdwrCCA.provider.DESedeKey) keyGenerator.generateKey();

// this is the exportable (EX) IMPORTER hardware key token, which is
// enciphered (wrapped) under an existing triple DES EXPORTER key named tdesPrimaryExporter
//
byte[] tdesImporterToken = tdesExporterKey.getPairedExternalToken();

The following illustrates generating a Triple DES hardware IMPORTER/EXPORTER transport key pair where the operational (OP) IMPORTER key is stored in the CCA key storage area and the exportable (EX) EXPORTER key is a hardware key token enciphered under an existing triple DES EXPORTER key named tdesPrimaryExporter: 

// use CCAAlgorithmParameterSpec to specify key size of 112, in
// addition, specify that the generated operational key is to be stored
// in the CCA key storage area
//
CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(
        112, CCAAlgorithmParameterSpec.CKDS);

// request that a transport key pair is to be generated
// first key is an operational (OP) IMPORTER key
// second key is an exportable (EX) EXPORTER key
//
ccaAlgParmSpec.setKeyUsage(KeyUsage.OPEX_IMPORTER_EXPORTER);

// specify an existing triple DES EXPORTER key to be used for
// enciphering the generated EXPORTER key
//
ccaAlgParmSpec.setKey2KeyEncryptingKey(tdesPrimaryExporter);

KeyGenerator keyGenerator = KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGenerator.init(ccaAlgParmSpec, null);

// this key object represents the generated operational (OP) IMPORTER
// key, and contains a label for the corresponding CCA key storage area entry
//
DESedeKey tdesImporterKey = (com.ibm.crypto.hdwrCCA.provider.DESedeKey) keyGenerator.generateKey();

// this is the exportable (EX) EXPORTER hardware key token, which is
// enciphered under an existing triple DES EXPORTER key named tdesPrimaryExporter
//
byte[] tdesExporterToken = tdesImporterKey.getPairedExternalToken();

The following illustrates generating an 192-bit AES DATA key containing a hardware key token: 

// use CCAAlgorithmParameterSpec to specify key size of 192
//
CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(192);

// request that an operational DATA key is to be generated
//
ccaAlgParmSpec.setKeyUsage(KeyUsage.OP_DATA);

KeyGenerator keyGenerator = KeyGenerator.getInstance("AES", "IBMJCECCA");
keyGenerator.init(ccaAlgParmSpec, null);

// this key object represents the generated operational (OP) DATA key
//
SecretKey aesDataKey = keyGenerator.generateKey();

The following illustrates generating a 256-bit AES hardware EXPORTER/IMPORTER transport key pair where the operational (OP) EXPORTER key contains a hardware key token enciphered by the local master key and the exportable (EX) IMPORTER key is a hardware key token enciphered under an existing AES EXPORTER key named aesPrimaryExporter: 

// use CCAAlgorithmParameterSpec to specify key size of 256
//
CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(256);

// request that a transport key pair is to be generated
// first key is an operational (OP) EXPORTER key
// second key is an exportable (EX) IMPORTER key
//
ccaAlgParmSpec.setKeyUsage(KeyUsage.OPEX_EXPORTER_IMPORTER);

// specify an existing AES EXPORTER key to be used for
// enciphering the generated IMPORTER key
//
ccaAlgParmSpec.setKey2KeyEncryptingKey(aesPrimaryExporter);

KeyGenerator keyGenerator = KeyGenerator.getInstance("AES", "IBMJCECCA");
keyGenerator.init(ccaAlgParmSpec, null);

// this key object represents the generated operational (OP) EXPORTER key
//
AESKey aesExporterKey = (com.ibm.crypto.hdwrCCA.provider.AESKey) keyGenerator.generateKey();

// this is the exportable (EX) IMPORTER hardware key token, which is
// enciphered (wrapped) under an existing AES EXPORTER key named aesPrimaryExporter
//
byte[] aesImporterToken = aesExporterKey.getPairedExternalToken();

The following illustrates generating an 128-bit AES hardware IMPORTER/EXPORTER transport key pair where the operational (OP) IMPORTER key is stored in the CCA key storage area and the exportable (EX) EXPORTER key is a hardware key token enciphered under an existing AES EXPORTER key named aesPrimaryExporter: 

// use CCAAlgorithmParameterSpec to specify key size of 128, in
// addition, specify that the generated operational key is to be stored
// in the CCA key storage area
//
CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(
        128, CCAAlgorithmParameterSpec.CKDS);

// request that a transport key pair is to be generated
// first key is an operational (OP) IMPORTER key
// second key is an exportable (EX) EXPORTER key
//
ccaAlgParmSpec.setKeyUsage(KeyUsage.OPEX_IMPORTER_EXPORTER);

// specify an existing AES EXPORTER key to be used for
// enciphering the generated EXPORTER key
//
ccaAlgParmSpec.setKey2KeyEncryptingKey(aesPrimaryExporter);

KeyGenerator keyGenerator = KeyGenerator.getInstance("AES", "IBMJCECCA");
keyGenerator.init(ccaAlgParmSpec, null);

// this key object represents the generated operational (OP) IMPORTER
// key, and contains a label for the corresponding CCA key storage area entry
//
AESKey aesImporterKey = (com.ibm.crypto.hdwrCCA.provider.AESKey) keyGenerator.generateKey();

// this is the exportable (EX) EXPORTER hardware key token, which is
// enciphered under an existing AES EXPORTER key named aesPrimaryExporter
//
byte[] aesExporterToken = aesImporterKey.getPairedExternalToken();
Generating Symmetric Transport Keys with NoCvKEK option

The following illustrates generating a Triple DES hardware EXPORTER/IMPORTER transport key pair where the operational (OP) EXPORTER key has the NoCvKEK option and is stored in the CCA key storage area and the exportable (EX) IMPORTER key is a hardware key token enciphered under an existing triple DES EXPORTER key named tdesPrimaryExporter: 

// Use CCAAlgorithmParameterSpec to specify key size of 112 and that
// the generated operational key is to be stored in the CCA key storage area.
// Only a Triple DES transport key in the CCA key storage area can have the NoCvKEK
// option enabled.
//
CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(
        112, CCAAlgorithmParameterSpec.CKDS);

// request that a transport key pair is to be generated
// first key is an operational (OP) EXPORTER key
// second key is an exportable (EX) IMPORTER key
//
ccaAlgParmSpec.setKeyUsage(KeyUsage.OPEX_EXPORTER_IMPORTER);

// request that the operational (OP) EXPORTER key have
// the NoCvKEK option
//
ccaAlgParmSpec.setNoCvKEK(true);

// specify an existing triple DES EXPORTER key to be used for
// enciphering the generated IMPORTER key
//
ccaAlgParmSpec.setKey2KeyEncryptingKey(tdesPrimaryExporter);

KeyGenerator keyGenerator = KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGenerator.init(ccaAlgParmSpec, null);

// This key object represents the generated operational (OP) EXPORTER key.
// Because the NoCvKEK option was specified when it was created,
// it is suitable for exchanging keys with non-z systems.
//
DESedeKey tdesExporterKey = (com.ibm.crypto.hdwrCCA.provider.DESedeKey) keyGenerator.generateKey();

// this is the exportable (EX) IMPORTER hardware key token, which is
// enciphered (wrapped) under an existing triple DES EXPORTER key named tdesPrimaryExporter
//
byte[] tdesImporterToken = tdesExporterKey.getPairedExternalToken();

The following illustrates generating a Triple DES hardware IMPORTER/EXPORTER transport key pair where the operational (OP) IMPORTER key has the NoCvKEK option and is stored in the CCA key storage area and the exportable (EX) EXPORTER key is a hardware key token enciphered under an existing triple DES EXPORTER key named tdesPrimaryExporter: 

// Use CCAAlgorithmParameterSpec to specify key size of 112 and that
// the generated operational key is to be stored in the CCA key storage area.
// Only a Triple DES transport key in the CCA key storage area can have the NoCvKEK
// option enabled.
//
CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(
        112, CCAAlgorithmParameterSpec.CKDS);

// request that a transport key pair is to be generated
// first key is an operational (OP) IMPORTER key
// second key is an exportable (EX) EXPORTER key
//
ccaAlgParmSpec.setKeyUsage(KeyUsage.OPEX_IMPORTER_EXPORTER);

// request that the operational (OP) IMPORTER key have
// the NoCvKEK option
//
ccaAlgParmSpec.setNoCvKEK(true);

// specify an existing triple DES EXPORTER key to be used for
// enciphering the generated EXPORTER key
//
ccaAlgParmSpec.setKey2KeyEncryptingKey(tdesPrimaryExporter);

KeyGenerator keyGenerator = KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGenerator.init(ccaAlgParmSpec, null);

// This key object represents the generated operational (OP) IMPORTER
// key, and contains a label for the corresponding CCA key storage area entry.
// Because the NoCvKEK option was specified when it was created,
// it is suitable for exchanging keys with non-z systems.
//
DESedeKey tdesImporterKey = (com.ibm.crypto.hdwrCCA.provider.DESedeKey) keyGenerator.generateKey();

// this is the exportable (EX) EXPORTER hardware key token, which is
// enciphered under an existing triple DES EXPORTER key named tdesPrimaryExporter
//
byte[] tdesExporterToken = tdesImporterKey.getPairedExternalToken();

Symmetric Transport Keys (Key Encrypting Keys): wrap and unwrap operations

The IBMJCECCA provider supports wrapping a hardware DES or Triple DES key for export to another host using an existing Triple DES EXPORTER key with the "DESedeKeyWrap" cipher algorithm. In addition, this cipher algorithm supports unwrapping a Triple DES EXPORTER wrapped hardware DES or Triple DES key for import from another host using an existing Triple DES IMPORTER key.

The "DESedeKeyWrap" cipher algorithm supports either the ECB key wrap method or the newer CBC key wrap method, which is ANSI X9.24 compliant. In a key wrap operation, the operational DES or Triple DES key, which is already wrapped by the host master key using a specific wrapping method, is first unwrapped. It is then wrapped with the provided EXPORTER key using the same wrapping method used when the key was wrapped by the host master key. In a key unwrap operation, the wrapped key is first unwrapped with the provided IMPORTER key. The unwrapped key is then wrapped by the host master key using the default wrapping method. The default wrapping method is set by the Integrated Cryptographic Service Facility (ICSF) when running on z/OS and is set by the IBM PCIe Cryptographic Coprocessor software when running on Linux for IBM z®.

The IBMJCECCA provider also supports wrapping a hardware DES, Triple DES, or AES key for export to another host using an existing AES EXPORTER key with the "AESKeyWrap" cipher algorithm. In addition, this cipher algorithm supports unwrapping of an AES EXPORTER wrapped hardware DES, Triple DES, or AES key for import from another host using an existing AES IMPORTER key.

Please note that when running on z/OS the underlying support for wrapping and unwrapping of DES and Triple DES keys with AES transport keys is only available on ICSF version HCR77A1 or higher.

The "AESKeyWrap" cipher algorithm supports the AESKW key wrapping method. A detailed specification of this algorithm is documented in the American Standards Committee ANSI X9.102-2008 publication titled Symmetric Key Cryptography for the Financial Services Industry - Wrapping of Keys and Associated Data. This is an extension to the AES Key Wrap algorithm referenced by the Java Cryptography Architecture. The main difference between the wrapping algorithm referenced by the Java Cryptography Architecture and the one used by the IBMJCECCA provider is that the wrapping algorithm used by the IBMJCECCA provider associates additional integrity information and data during key wrapping.

As mentioned earlier under Symmetric Transport Keys, keys wrapped with transport keys generated through the IBMJCECCA provider without the NoCvKEK option may only be distributed among z systems. Keys wrapped with Triple DES transport keys that have the NoCvKEK option enabled can be distributed among z systems and non-z systems.

You must specify usage of a key being imported if one or more of the following is true:

For more information on the different types of key wrapping methods supported by the IBM Common Cryptographic Architecture (CCA), refer to the section titled Functions of the Symmetric Cryptographic Keys in the Cryptographic Services Integrated Cryptographic Service Facility Application Programmer's Guide.

By default, and with both "DESedeKeyWrap" and "AESKeyWrap" cipher algorithms, the unwrapped or imported key object will contain the label for a CCA key storage area entry that contains a hardware token. This token will contain the key encrypted with the host master key.

If a CCAAlgorithmParameterSpec is constructed with type CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN, and the "DESedeKeyWrap" or "AESKeyWrap" cipher is initialized for unwrap with this CCAAlgorithmParameterSpec, the resulting unwrapped or imported 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 no type specified, or with type CAAlgorithmParameterSpec.CKDS, and the "DESedeKeyWrap" or "AESKeyWrap" cipher is initialized for unwrap with this CCAAlgorithmParameterSpec, the resulting unwrapped or imported key object will contain the label for a CCA key storage area entry that contains a hardware token. This token will contain the key encrypted with the host master key.

Unwrapping to a CLEAR key is not supported by either cipher algorithms.

The IBMJCECCA provider does not implement any restrictions preventing a symmetric key from being wrapped by a weaker transport key. Such configurations should be done through ICSF when running on z/OS.

The following illustrates wrapping or exporting a hardware DES key named desDataKey with a Triple DES EXPORTER key named tdesPrimaryExporter: 

// obtain a cipher with the "DESedeKeyWrap" cipher algorithm
//
Cipher wrapCipher = Cipher.getInstance("DESedeKeyWrap", "IBMJCECCA");

// initialize the cipher for key wrapping using a triple DES EXPORTER key
//
wrapCipher.init(Cipher.WRAP_MODE, tdesPrimaryExporter, (SecureRandom) null);

// wrap an existing DES DATA key
// the resulting wrapped key is an exportable (EX) DATA hardware key token
// enciphered under a triple DES EXPORTER key named tdesPrimaryExporter
//
byte[] desWrappedDataKey = wrapCipher.wrap(desDataKey);

An IMPORTER key is needed to to unwrap or import desWrappedDataKey. This IMPORTER key should have been generated with tdesPrimaryExporter as an EXPORTER/IMPORTER pair, either through a key generator or through the key derivation step of a Diffie-Hellman key agreement operation.

The following illustrates unwrapping the previously wrapped hardware DES key named desWrappedDataKey with a Triple DES IMPORTER key named tdesPrimaryImporter, where the resulting unwrapped hardware key token is stored in the CCA key storage area and the returned key object contains the label identifying that CCA key storage area entry: 

// obtain a cipher with the "DESedeKeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("DESedeKeyWrap", "IBMJCECCA");

// specify that the unwrapped (imported) key is to be stored in the CCA key storage area
//
CCAAlgorithmParameterSpec spec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);

// initialize the cipher for key unwrapping using a triple DES IMPORTER key
//
unwrapCipher.init(Cipher.UNWRAP_MODE, tdesPrimaryImporter, spec, (SecureRandom) null);

// unwrap (import) the wrapped DES DATA key
// the resulting unwrapped key is an operational (OP) DATA hardware key token
// enciphered under the local master key and stored in the CCA key storage area
//
SecretKey desUnwrappedDataKey = (SecretKey) unwrapCipher.unwrap(
        desWrappedDataKey, "DES", Cipher.SECRET_KEY);

The above wrap and unwrap scenario assumes that tdesPrimaryExporter and tdesPrimaryImporter are matching EXPORTER/IMPORTER keys.

The following sample illustrates unwrapping a previously wrapped hardware Triple DES IMPORTER key named tdesWrappedImporterKey with a triple DES IMPORTER key named tdesPrimaryImporter, where the resulting unwrapped key object contains an operational (OP) IMPORTER hardware key token enciphered under the local master key: 

// obtain a cipher with the "DESedeKeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("DESedeKeyWrap", "IBMJCECCA");

// specify that the unwrapped key is to be enciphered under the local master key
//
CCAAlgorithmParameterSpec spec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN);

// initialize the cipher for key unwrapping using a triple DES IMPORTER key
//
unwrapCipher.init(Cipher.UNWRAP_MODE, tdesPrimaryImporter, spec, (SecureRandom) null);

// unwrap (import) the wrapped triple DES IMPORTER key
// the resulting unwrapped key is an operational (OP) IMPORTER hardware
// key token enciphered under the local master key
//
SecretKey tdesUnwrappedImporterKey = (SecretKey) unwrapCipher.unwrap(
        tdesWrappedImporterKey, "DESede", Cipher.SECRET_KEY);

The following illustrates wrapping or exporting a hardware DES key named desDataKey with an 128-bit AES EXPORTER key named aes128BitExporter: 

// obtain a cipher with the "AESKeyWrap" cipher algorithm
//
Cipher wrapCipher = Cipher.getInstance("AESKeyWrap", "IBMJCECCA");

// initialize the cipher for key wrapping using an 128-bit AES
// EXPORTER key
//
wrapCipher.init(Cipher.WRAP_MODE, aes128BitExporter, (SecureRandom) null);

// wrap an existing DES DATA key
// the resulting wrapped key is an exportable (EX) DATA hardware key
// token enciphered under an 128-bit AES EXPORTER key named
// aes128BitExporter
//
byte[] aesWrappedDESDataKey = wrapCipher.wrap(desDataKey);

An 128-bit AES IMPORTER key is needed to to unwrap or import aesWrappedDESDataKey. This IMPORTER key should have been generated with aes128BitExporter as an EXPORTER/IMPORTER pair, either through a key generator or through the key derivation step of a Diffie-Hellman key agreement operation.

The following illustrates unwrapping of a previously wrapped hardware Triple DES key named aesWrapedTripleDESKey with an 192-bit AES IMPORTER key named aes192BitImporter, where the resulting unwrapped key object contains an operational (OP) hardware key token enciphered under the local master key: 

// obtain a cipher with the "AESKeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("AESKeyWrap", "IBMJCECCA");

// specify that the unwrapped key is to be enciphered under the local master key
//
CCAAlgorithmParameterSpec spec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN);

// initialize the cipher for key unwrapping using an 192-bit AES
// IMPORTER key
//
unwrapCipher.init(Cipher.UNWRAP_MODE, aes192BitImporter, spec, (SecureRandom) null);

// unwrap (import) the wrapped triple DES key
// the resulting unwrapped key is an operational (OP) hardware
// key token enciphered under the local master key
//
SecretKey unwrappedTripleDESKey = (SecretKey) unwrapCipher.unwrap(
        aesWrapedTripleDESKey, "DESede", Cipher.SECRET_KEY);

The above unwrap scenario assumes that the original 192-bit AES EXPORTER key used to wrap the Triple DES key and the aes192BitImporter key used for the unwrap operation are matching EXPORTER/IMPORTER keys.

The following illustrates wrapping a hardware 192-bit AES key named aes192BitKey with a 256-bit AES EXPORTER key named aes256BitExporter: 

// obtain a cipher with the "AESKeyWrap" cipher algorithm
//
Cipher wrapCipher = Cipher.getInstance("AESKeyWrap", "IBMJCECCA");

// initialize the cipher for key wrapping using a 256-bit AES
// EXPORTER key
//
wrapCipher.init(Cipher.WRAP_MODE, aes256BitExporter, (SecureRandom) null);

// wrap an existing 192-bit AES key
// the resulting wrapped key is an exportable (EX) hardware key token
// enciphered under a 256-bit AES EXPORTER key named aes256BitExporter
//
byte[] aesWrappedAES192BitKey = wrapCipher.wrap(aes192BitKey);

A 256-bit AES IMPORTER key is needed to to unwrap or import aesWrappedAES192BitKey. This IMPORTER key should have been generated with aes256BitExporter as an EXPORTER/IMPORTER pair, either through a key generator or through the key derivation step of a Diffie-Hellman key agreement operation.

The following illustrates unwrapping the previously wrapped hardware 192-bit AES key named aesWrappedAES192BitKey with a 256-bit AES IMPORTER key named aes256BitImporter, where the resulting unwrapped hardware key token is stored in the CCA key storage area and the returned key object contains the label identifying that CCA key storage area entry: 

// obtain a cipher with the "AESKeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("AESKeyWrap", "IBMJCECCA");

// specify that the unwrapped (imported) key is to be stored in the CCA key storage area
//
CCAAlgorithmParameterSpec spec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);

// initialize the cipher for key unwrapping using a 256-bit AES
// IMPORTER key
//
unwrapCipher.init(Cipher.UNWRAP_MODE, aes256BitImporter, spec, (SecureRandom) null);

// unwrap (import) the wrapped 192-bit AES key
// the resulting unwrapped key is an operational (OP) hardware key token
// enciphered under the local master key and stored in the CCA key storage area
//
SecretKey unwrappedAES192BitKey = (SecretKey) unwrapCipher.unwrap(
        aesWrappedAES192BitKey , "AES", Cipher.SECRET_KEY);

The above wrap and unwrap scenario assumes that aes256BitExporter and aes256BitImporter are matching EXPORTER/IMPORTER keys.

Importing with Symmetric Transport Keys: the NoCvKEK option

The following sample illustrates unwrapping a previously wrapped hardware Triple DES IMPORTER key named tdesWrappedImporterKey with a triple DES IMPORTER key named tdesPrimaryImporter, where the resulting unwrapped key object contains an operational (OP) IMPORTER hardware key token in the CCA key storage area with the NoCvKEK option: 

// obtain a cipher with the "DESedeKeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("DESedeKeyWrap", "IBMJCECCA");

// Specify that the unwrapped key is to be enciphered under the 
// local master key and stored in the CCA key storage area.
// Only a Triple DES transport key in the CCA key storage area can have the NoCvKEK
// option enabled.
//
CCAAlgorithmParameterSpec spec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);

// specify that the unwrapped key is to have the NoCvKEK option enabled
//
spec.setNoCvKEK(true);

// because the unwrapped key will have the NoCvKEK option enabled, 
// it is necessary to specify key usage for it.
//
spec.setKeyUsage(KeyUsage.OP_IMPORTER);

// initialize the cipher for key unwrapping using a triple DES IMPORTER key
//
unwrapCipher.init(Cipher.UNWRAP_MODE, tdesPrimaryImporter, spec, (SecureRandom) null);

// unwrap (import) the wrapped triple DES IMPORTER key
// the resulting unwrapped key is an operational (OP) IMPORTER hardware
// key token with the NoCvKEK option stored in the CCA key storage area.
//
SecretKey tdesUnwrappedImporterKey = (SecretKey) unwrapCipher.unwrap(
        tdesWrappedImporterKey, "DESede", Cipher.SECRET_KEY);

The following sample illustrates unwrapping a previously wrapped hardware Triple DES EXPORTER key named tdesWrappedExporterKey with a triple DES IMPORTER key named tdesPrimaryImporter that has NoCvKEK enabled. The resulting unwrapped key object contains an operational (OP) EXPORTER hardware key token in the CCA key storage area. 

// obtain a cipher with the "DESedeKeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("DESedeKeyWrap", "IBMJCECCA");

// Specify that the unwrapped key is to be enciphered under the 
// local master key and stored in the CCA key storage area.
//
CCAAlgorithmParameterSpec spec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);

// because the importer key has NoCvKEK enabled it is necessary to specify
// the usage of the unwrapped key
//
spec.setKeyUsage(KeyUsage.OP_EXPORTER);

// initialize the cipher for key unwrapping using a triple DES IMPORTER key
//
unwrapCipher.init(Cipher.UNWRAP_MODE, tdesPrimaryImporter, spec, (SecureRandom) null);

// unwrap (import) the wrapped triple DES EXPORTER key
// the resulting unwrapped key is an operational (OP) EXPORTER hardware
// key token stored in the CCA key storage area.
//
SecretKey tdesUnwrappedExporterKey = (SecretKey) unwrapCipher.unwrap(
        tdesWrappedImporterKey, "DESede", Cipher.SECRET_KEY);

Symmetric Transport Keys (Key Encrypting Keys): ANSI TR-31 Key Block operations

In a secure environment such as banking, it is important that each symmetric key have a specific set of attributes attached to it, specifying such things as the cryptographic operations for which that key can be used. Different cryptographic architectures implement these attributes in different ways and, as a result, the normal approach when exchanging keys with different vendors has been to strip the attributes and just send the key material.

ANSI TR-31 provides a standardized way to securely exchange key material and its attributes between differing cryptographic systems. The TR-31 key block has two important features:

The key is protected in a way that meets the "key bundling" requirements of various standards which state that the individual 8-byte pieces of a double-length or triple-length triple DES key must be bound in such a way that they cannot be individually manipulated. In TR-31 this is accomplished mainly by computation of a MAC across the entire structure.

The key usage attributes, which define how the key can be used, are securely bound to the key itself. Thus, when a key is sent from one party to another, the attributes are also transferred and cannot be modified to suit the needs of an attacker.

In addition to the encoding defined in ANSI TR-31, the TR-31 key block can have a number of optional data blocks where each has a two character string key and a variable length string value. Any optional data blocks included in a TR-31 key block are securely bound to the key in the same the same way as the TR-31 defined usage attributes are bound to it.

The TR-31 key block can be used to export keys for encrypting/decrypting data as well as transport keys (key encrypting keys). Only DES and triple DES keys can be transported in TR-31 key blocks. There is no support for transporting AES keys in TR-31 key blocks.

The keys used to protect a TR-31 key block are transport keys. For information on transport keys, see Symmetric Transport Keys.

Exporting (Wrapping) a key in a TR-31 Key Block

The following sample illustrates the simplest case for exporting a key in a TR-31 key block. A triple DES key named tdesDataKey used for encrypting/decrypting data is wrapped using an EXPORTER transport key named tdesExporterKey. 

// obtain a cipher with the "DESedeTR31KeyWrap" cipher algorithm
//
Cipher wrapCipher = Cipher.getInstance("DESedeTR31KeyWrap", "IBMJCECCA");

// initialize the cipher, specifying WRAP_MODE and the transport key
//
wrapCipher.init(Cipher.WRAP_MODE, tdesExporterKey);

// create the TR-31 key block
//
byte[] keyBlock = wrapCipher.wrap(tdesDataKey);

The following sample illustrates creating a TR-31 key block to export an operational triple DES IMPORTER transport key tdesImporterKey2Wrap using an EXPORTER transport key named tdesExporterKey. 

// obtain a cipher with the "DESedeTR31KeyWrap" cipher algorithm
//
Cipher wrapCipher = Cipher.getInstance("DESedeTR31KeyWrap", "IBMJCECCA");

// because the key being exported is a transport key, it is necessary
// to create a parameterSpec object to specify its usage
//
CCAAlgorithmParameterSpec ccaParmSpec = new CCAAlgorithmParameterSpec();
ccaParmSpec.setKeyUsage(KeyUsage.OP_IMPORTER);

// initialize the cipher by specifying WRAP_MODE, the transport key,
// and the parameterSpec
//
wrapCipher.init(Cipher.WRAP_MODE, tdesExporterKey, ccaParmSpec);

// create the TR-31 key block
//
byte[] keyBlock = wrapCipher.wrap(tdesImporterKey2Wrap);

The following sample illustrates creating a TR-31 key block to export an operational triple DES EXPORTER transport key tdesExporterKey2Wrap using an EXPORTER transport key named tdesExporterKey. 

// obtain a cipher with the "DESedeTR31KeyWrap" cipher algorithm
//
Cipher wrapCipher = Cipher.getInstance("DESedeTR31KeyWrap", "IBMJCECCA");

// because the key being exported is a transport key, it is necessary
// to create a parameterSpec object to specify its usage
//
CCAAlgorithmParameterSpec ccaParmSpec = new CCAAlgorithmParameterSpec();
ccaParmSpec.setKeyUsage(KeyUsage.OP_EXPORTER);

// initialize the cipher by specifying WRAP_MODE, the transport key,
// and the parameterSpec
//
wrapCipher.init(Cipher.WRAP_MODE, tdesExporterKey, ccaParmSpec);

// create the TR-31 key block
//
byte[] keyBlock = wrapCipher.wrap(tdesExporterKey2Wrap);

The following sample illustrates creating a TR-31 key block to export a key and specifying optional data blocks. 

// define some data for the optional data blocks
//
String optData_ID1 = "AB";
String optData_1 = "Some data required by the receiving system";
String optData_ID2 = "CD";
String optData_2 = "Some information to make this block self-documenting";

// create an array of optional data blocks 
//
TR31OptionalDataBlock[] optDatablocks = new TR31OptionalDataBlock[2];
optDataBlocks[0] = new TR31OptionalDataBlock(optData_ID1, optData_1);
optDataBlocks[1] = new TR31OptionalDataBlock(optData_ID2, optData_2);

// Store the optional data blocks in a ParameterSpec
//
// (If the key being exported were a transport key it would also
// be necessary to call ccaParmSpec.setKeyUsage() as shown in 
// the previous samples.)
//
CCAAlgorithmParameterSpec ccaParmSpec = new CCAAlgorithmParameterSpec();
ccaParmSpec.setTR31OptionalDataBlocks(optDatBlocks);

// obtain a cipher with the "DESedeTR31KeyWrap" cipher algorithm
//
Cipher wrapCipher = Cipher.getInstance("DESedeTR31KeyWrap", "IBMJCECCA");

// initialize the cipher, specifying WRAP_MODE, the transport key,
// and the ParameterSpec
//
wrapCipher.init(Cipher.WRAP_MODE, tdesExporterKey, ccaParmSpec);

// create the TR-31 key block
//
byte[] keyBlock = wrapCipher.wrap(tdesDataKey);
Importing (Unwrapping) a key from a TR-31 Key Block

The following sample illustrates the simplest case for importing a key from a TR-31 key block. A DES key named desDataKey used for encrypting/decrypting data is unwrapped from a TR-31 key block tr31KeyBlock using an IMPORTER transport key named tdesImporterKey and is stored in the CCA key storage area. 

// obtain a cipher with the "DESedeTR31KeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("DESedeTR31KeyWrap", "IBMJCECCA");

// initialize the cipher, specifying UNWRAP_MODE and the transport key
//
unwrapCipher.init(Cipher.UNWRAP_MODE, tdesImporterKey);

// extract the key from the TR-31 key block
//
DESKey desDataKey = unwrapCipher.unwrap(tr31KeyBlock, "DES", Cipher.SECRETKEY);

The following sample illustrates importing a triple DES key named tdesDataKey used for encrypting/decrypting data from a TR-31 key block tr31KeyBlock using an IMPORTER transport key named tdesImporterKey. The resulting key is encoded using the host master key. 

// obtain a cipher with the "DESedeTR31KeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("DESedeTR31KeyWrap", "IBMJCECCA");

// specify that the unwrapped key is to be enciphered under the local master key
//
CCAAlgorithmParameterSpec ccaParmSpec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN);

// initialize the cipher, specifying UNWRAP_MODE, the transport key, and the parameterSpec
//
unwrapCipher.init(Cipher.UNWRAP_MODE, tdesImporterKey, ccaParmSpec);

// extract the key from the TR-31 key block
//
DESedeKey tdesDataKey = unwrapCipher.unwrap(tr31KeyBlock, "DESede", Cipher.SECRETKEY);

The following sample illustrates importing a triple DES IMPORTER transport key named tdesImporterKey2Import from a TR-31 key block tr31KeyBlock using an IMPORTER transport key named tdesImporterKey. The resulting key is encoded using the host master key. 

// obtain a cipher with the "DESedeTR31KeyWrap" cipher algorithm
//
Cipher unwrapCipher = Cipher.getInstance("DESedeTR31KeyWrap", "IBMJCECCA");

// specify that the unwrapped key is to be enciphered under the local master key
//
CCAAlgorithmParameterSpec ccaParmSpec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN);

// specify that the key being imported is an IMPORTER transport key
//
ccaParmSpec.setKeyUsage( KeyUsage.OP_IMPORTER );

// initialize the cipher, specifying UNWRAP_MODE, the transport key, and the parameterSpec
//
unwrapCipher.init(Cipher.UNWRAP_MODE, tdesImporterKey, ccaParmSpec);

// extract the key from the TR-31 key block
//
DESedeKey tdesImporterKey2Import = unwrapCipher.unwrap(tr31KeyBlock, "DESede", Cipher.SECRETKEY);
Extracting non-key data from a TR-31 Key Block

A TR-31 key block is a byte array and, as such, it is not easily parsed. Therefore, a convenience class TR31KeyBlock is provided for extracting the non-key information from a TR-31 key block. The toString() method formats the data for printing. When possible, fields in the TR-31 header are displayed with their encoded value and a string interpreting them. In addition, methods are provided to enable extracting data programmatically.

The following sample illustrates printing the non-key data in TR-31 key block. 

//
// a TR-31 key block is a byte[]
// For this illustration we assume that tr31Block is a TR-31 key block created using 
// one of the previous examples.
//

// Get an instance of the TR31KeyBlock convenience class, passing the 
// actual TR-31 key block to the constructor.
//
TR31KeyBlock kblk = new TR31KeyBlock( tr31Block );

// call toString()
//
System.out.println( kblk.toString() );

If the key wrapped in the TR-31 key block is an data encrypting/decrypting key and the TR-31 key block contains 2 optional data blocks, the resulting output might look like the following: 

TR31KeyBlock: 
    keyBlockVersion:   A
    keyBlockLength:    128
    keyUsage:          D0 ( DataEncryptionKey )
    keyAlgorithm:      T  ( Triple-DES )
    keyMode:           B  ( EncryptDecrypt )
    keyVersion:        00
    keyExportablility: S  ( Exportable under any key )
    numOptDataBlocks:     2
        TR31OptionalDataBlock: 
            OptDataID: 01
            OptData:   Now is the time for all good men
        TR31OptionalDataBlock: 
            OptDataID: PB
            OptData:

If the key wrapped in the TR-31 key block is an EXPORTER transport key and the TR-31 key block contains no optional data blocks, the resulting output might look like the following: 

TR31KeyBlock: 
    keyBlockVersion:   A
    keyBlockLength:    88
    keyUsage:          K0 ( KeyEcryptingKey )
    keyAlgorithm:      T  ( Triple-DES )
    keyMode:           E  ( Exporter )
    keyVersion:        00
    keyExportablility: S  ( Exportable under any key )
    numOptDataBlocks:     0

The following sample illustrates programatically extracting the non-key data from a TR-31 key block. 

//
// a TR-31 key block is a byte[]
// For this illustration we assume that tr31Block is a TR-31 key block created using 
// one of the previous examples.
//

// Get an instance of the TR31KeyBlock convenience class, passing the 
// actual TR-31 key block to the constructor.
//
TR31KeyBlock kblk = new TR31KeyBlock( tr31Block );

// Extract the data as stored in the TR-31 key block
//
String keyBlkVersion = kblk.getKeyBlockVersion();
int keyBlkLength = kblk.getKeyBlockLength();
String keyUsage = kblk.getKeyUsage();
String keyAlgorithm = kblk.getKeyAlgorithm();
String keyMode = kblk.getKeyMode();
String keyVersion = kblk.getKeyVersion();
String keyExportability = kblk.getKeyExportability();
int numOptionalBlocks = kblk.getNumOptDataBlocks();

// Get descriptions of the data stored in the TR-31 key block
//
String keyUsageDescript = kblk.getKeyUsageAsString();
String keyAlgorithmDescript = kblk.getKeyAlgorithmAsString();
String keyModeDescript = kblk.getKeyModeAsString();
String keyExportabilityDescript = kblk.getKeyExportabilityAsString();

// Extract the contents of the optional data blocks,
// if any
//
TR31OptionalDataBlock[] optblks = kblk.getOptDataBlocks();
String[] optionalDataIDs = new String[numOptionalBlocks];
String[] optionalData = new String[numOptionalBlocks];
for( int idx=0; idx < numOptionalBlocks; idx++ ) {
    optionalDataIDs[idx] = optblks[idx].getOptDataID();
    optionalData[idx] = optblks[idx].getOptData();
} // end for

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:

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 CCA key storage area stored key pairs. With a CCA key storage area stored 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 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:

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.SECURE_INTERNAL_TOKEN, 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 CCA key storage area entry that contains a hardware token. This token will contain the key encrypted with the host master key.

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 CCA key storage area, 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 CCA key storage area key entry, retrieve the private
// hardware key from the key store.
//
PrivateKey privateKey = (PrivateKey) jceccaks.getKey("MYRSAKEY", "myrsakeyPW".toCharArray());

// Delete the RSA hardware CCA key storage area 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 code previously described can be followed to delete DSA private hardware CCA key storage area key entries by substituting the DSAPrivateHWKey class for the RSAPrivateHWKey class.

Like IBMJCE, the IBMJCECCA provider implements RSA wrapping/unwrapping with OAEP (Optimal Asymmetric Encryption Padding). The IBMJCECCA support differs from the IBMJCE support in the following ways:

The following examples illustrate creating an instance of an RSA Cipher with the OAEP SHA-1 and the OAEP SHA-256 padding algorithm

Cipher rsaCipher = Cipher.getInstance("RSA/ /OAEPPADDINGSHA-1", "IBMJCECCA");

Cipher rsaCipher = Cipher.getInstance("RSA/ /OAEPPADDINGSHA-256", "IBMJCECCA");

The following illustrates wrapping a DES key token using RSA with OAEP and SHA-256 padding 

OAEPParameterSpec oaepSpec = new OAEPParameterSpec(
       "SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSource.PSpecified.DEFAULT);
CCAAlgorithmParameterSpec ccaSpec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN);
ccaSpec.setOAEPParameterSpec(oaepSpec);
rsaCipher.init(Cipher.WRAP_MODE, rsaPub,ccaSpec, null);
byte[] wrappedKey = rsaCipher.wrap(desKey);

The following illustrates unwrapping a DES key to an encrypted key stored in the CCA key storage area, when the key was wrapped using RSA with OAEP and SHA-256 padding 

OAEPParameterSpec oaepSpec = new OAEPParameterSpec(
       "SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSource.PSpecified.DEFAULT); 
CCAAlgorithmParameterSpec ccaSpec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);
ccaSpec.setOAEPParameterSpec(oaepSpec);
rsaCipher.init(Cipher.UNWRAP_MODE, rsaPriv, ccaSpec, null);
Key unwrappedKey = rsaCipher.unwrap(wrappedKey, "DES" Cipher.SECRET_KEY);

The RSA cipher in the IBMJCECCA provider supports wrapping and unwrapping of AES transport keys, such as AES EXPORTER and AES IMPORTER keys, using RSA with OAEP. Please note that IBMJCECCA transport key objects contain transient fields that may not persist through wrap and unwrap operations, refer to Symmetric Transport Keys for addition information.

The RSA cipher in the IBMJCECCA provider supports wrapping and unwrapping of DES and Triple DES keys, but only if they are DATA keys.

EC: Keys

The hardware JCE implementation (IBMJCECCA) extends the EC keys available in the software JCE implementation (IBMJCE). In the IBMJCE implementation, the actual EC key material is stored in the key object. The IBMJCECCA implementation extends this by adding the following alternative representations:

EC: Operations

The IBMJCECCA provider supports Diffie-Hellman Key Agreement with elliptic curve keys (Elliptic Curve Diffie-Hellman) using hardware cryptography, which allows the use of the more secure CCA key storage area stored elliptic curve key pairs. With a CCA key storage area stored elliptic curve key pair, the sensitive private key is never made available in the clear.

Performing Diffie-Hellman Key Agreement using elliptic curve keys with the IBMJCECCA provider allows the generation of raw secret from the Diffie-Hellman process and, in addition, allows the key derivation of symmetric hardware keys using the static unified model of key agreement scheme. By default, the resulting derived key object will contain a SECURE_INTERNAL_TOKEN key.

If a KDFParameterSpec is created with no type specified, or with type KeyType.SECURE_INTERNAL_TOKEN, and the Elliptic Curve Diffie-Hellman Key Agreement is initialized with this KDFParameterSpec, the resulting derived symmetric key object will contain a SECURE_INTERNAL_TOKEN hardware token. This token will contain the key encrypted with the host master key. If a KDFParameterSpec is created with type KeyType.CKDS, and the Elliptic Curve Diffie-Hellman Key Agreement is initialized with this KDFParameterSpec, the resulting derived symmetric key object will contain the label for a CCA key storage area entry that contains a hardware token. This token will contain the key encrypted with the host master key.

Elliptic Curve Diffie-Hellman supports key derivation of symmetric hardware keys with different key usage attributes. The following is a list of key algorithm and usage types that are supported:

For a detailed explanation of symmetric key usage types, refer to the section titled Functions of the Symmetric Cryptographic Keys in the Cryptographic Services Integrated Cryptographic Service Facility Application Programmer's Guide. Please note that not all symmetric key usage types that are available in CCA are supported by the IBMJCECCA provider.

When initializing Elliptic Curve Diffie-Hellman Key Agreement for key derivation, ensure that a KDFParameterSpec with shared info is constructed and used. A unique shared info accompanying each Elliptic Curve Diffie-Hellman Key Agreement ensures the same keying material is not derived more than once. Refer to the NIST SP 800-56A publication for more information and recommendations on the formatting of this field.

The following illustrates generating a raw secret from the Diffie-Hellman process: 

// Party A generates a shared secret by using his or her own private
// EC key and the public EC key of party B
//
KeyAgreement partyAKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");
partyAKeyAgreement.init(partyAPrivateKey, (SecureRandom) null);
partyAKeyAgreement.doPhase(partyBPublicKey, true);
byte[] partyASharedSecret = partyAKeyAgreement.generateSecret();

// Party B generates a shared secret by using his or her own private
// EC key and the public EC key of party A
//
KeyAgreement partyBKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");
partyBKeyAgreement.init(partyBPrivateKey, (SecureRandom) null);
partyBKeyAgreement.doPhase(partyAPublicKey, true);
byte[] partyBSharedSecret = partyBKeyAgreement.generateSecret();

// The shared secret generated through this key agreement process
// by both party A and party B should have the same byte array contents

The following illustrates key derivation of DES CIPHER hardware keys using the static unified model of Key Agreement scheme: 

import com.ibm.crypto.hdwrCCA.provider.SymmetricKeyConstants.KeyType;
import com.ibm.crypto.hdwrCCA.provider.SymmetricKeyConstants.KeyUsage;

// Party A
//
KeyAgreement partyAKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");

// Party A wants to derive a 56-bit hardware CIPHER key enciphered
// under the local master key, the sharedInfo byte array is uniquely
// constructed for this key derivation and shared with party B
//
KDFParameterSpec partyASpec = new KDFParameterSpec(
        56, sharedInfo, KeyType.SECURE_INTERNAL_TOKEN, null, KeyUsage.OP_CIPHER);

// Party A derives a hardware DES key by using his or her own private
// EC key and the public EC key of party B
//
partyAKeyAgreement.init(partyAPrivateKey, partyASpec, (SecureRandom) null);
partyAKeyAgreement.doPhase(partyBPublicKey, true);
SecretKey partyASecretKey = partyAKeyAgreement.generateSecret("DES");


// Party B
//
KeyAgreement partyBKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");

// Party B uses the exact same key derivation specification as party A
// Party B must also use the exact same sharedInfo byte array as party A
//
KDFParameterSpec partyBSpec = new KDFParameterSpec(
        56, sharedInfo, KeyType.SECURE_INTERNAL_TOKEN, null, KeyUsage.OP_CIPHER);

// Party B derives a hardware DES key by using his or her own private
// EC key and the public EC key of party A
//
partyBKeyAgreement.init(partyBPrivateKey, partyBSpec, (SecureRandom) null);
partyBKeyAgreement.doPhase(partyAPublicKey, true);
SecretKey partyBSecretKey = partyBKeyAgreement.generateSecret("DES");

// The same hardware DES key is generated through this key derivation
// process by both party A and party B

The following illustrates key derivation of a double length (112-bit) Triple DES EXPORTER key and a double length (112-bit) Triple DES IMPORTER key using the static unified model of Key Agreement scheme. Both keys are stored in the CCA key storage area: 

import com.ibm.crypto.hdwrCCA.provider.SymmetricKeyConstants.KeyType;
import com.ibm.crypto.hdwrCCA.provider.SymmetricKeyConstants.KeyUsage;

// Party A
//
KeyAgreement partyAKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");

// Party A wants to derive an 112-bit hardware EXPORTER key enciphered
// under the local master key and stored in the CCA key storage area, the sharedInfo
// byte array is uniquely constructed for this key derivation and shared
// with party B
//
KDFParameterSpec partyASpec = new KDFParameterSpec(
        112, sharedInfo, KeyType.CKDS, null, KeyUsage.OP_EXPORTER);

// Party A derives a double length Triple DES EXPORTER key by using
// his or her own private EC key and the public EC key of party B
//
partyAKeyAgreement.init(partyAPrivateKey, partyASpec, (SecureRandom) null);
partyAKeyAgreement.doPhase(partyBPublicKey, true);
SecretKey partyAExporterKey = partyAKeyAgreement.generateSecret("DESede");


// Party B
//
KeyAgreement partyBKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");

// Party B uses mostly the same key derivation specification as
// party A, with the exception that he or she is deriving an IMPORTER
// key instead of an EXPORTER key. With an IMPORTER key, party B is
// able to import keys that are exported with party A's EXPORTER key

// Party B must use the exact same sharedInfo byte array as party A
//
KDFParameterSpec partyBSpec = new KDFParameterSpec(
        112, sharedInfo, KeyType.CKDS, null, KeyUsage.OP_IMPORTER);

// Party B derives a double length Triple DES IMPORTER key by using
// his or her own private EC key and the public EC key of party A.
//
partyBKeyAgreement.init(partyBPrivateKey, partyBSpec, (SecureRandom) null);
partyBKeyAgreement.doPhase(partyAPublicKey, true);
SecretKey partyBImporterKey = partyBKeyAgreement.generateSecret("DESede");

// The hardware Triple DES keys generated through this key derivation
// process by party A and party B are an EXPORTER/IMPORTER key pair

// Keys exported or wrapped by party A's EXPORTER key may be imported
// or unwrapped by party B's IMPORTER key

The following illustrates key derivation of a double length (112-bit) Triple DES EXPORTER key and a double length (112-bit) Triple DES IMPORTER key using the static unified model of Key Agreement scheme. In this example the EXPORTER key and the IMPORTER key are created with the NoCvKEK option enabled. Both keys are stored in the CCA key storage area: 

import com.ibm.crypto.hdwrCCA.provider.SymmetricKeyConstants.KeyType;
import com.ibm.crypto.hdwrCCA.provider.SymmetricKeyConstants.KeyUsage;

// Party A
//
KeyAgreement partyAKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");

// Party A wants to derive an 112-bit hardware EXPORTER key enciphered
// under the local master key and stored in the CCA key storage area, the sharedInfo
// byte array is uniquely constructed for this key derivation and shared
// with party B.
// The last parameter specifies that the NoCvKEK option should be
// enabled.
//
KDFParameterSpec partyASpec = new KDFParameterSpec(
        112, sharedInfo, KeyType.CKDS, null, KeyUsage.OP_EXPORTER, true);

// Party A derives a double length Triple DES EXPORTER key by using
// his or her own private EC key and the public EC key of party B
//
partyAKeyAgreement.init(partyAPrivateKey, partyASpec, (SecureRandom) null);
partyAKeyAgreement.doPhase(partyBPublicKey, true);
SecretKey partyAExporterKey = partyAKeyAgreement.generateSecret("DESede");


// Party B
//
KeyAgreement partyBKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");

// Party B uses mostly the same key derivation specification as
// party A, with the exception that he or she is deriving an IMPORTER
// key instead of an EXPORTER key. With an IMPORTER key, party B is
// able to import keys that are exported with party A's EXPORTER key

// Party B must use the exact same sharedInfo byte array as party A
// The last parameter specifies that the NoCvKEK option should be
// enabled.
//
KDFParameterSpec partyBSpec = new KDFParameterSpec(
        112, sharedInfo, KeyType.CKDS, null, KeyUsage.OP_IMPORTER, true);

// Party B derives a double length Triple DES IMPORTER key by using
// his or her own private EC key and the public EC key of party A
//
partyBKeyAgreement.init(partyBPrivateKey, partyBSpec, (SecureRandom) null);
partyBKeyAgreement.doPhase(partyAPublicKey, true);
SecretKey partyBImporterKey = partyBKeyAgreement.generateSecret("DESede");

// The hardware Triple DES keys generated through this key derivation
// process by party A and party B are an EXPORTER/IMPORTER key pair

// Keys exported or wrapped by party A's EXPORTER key may be imported
// or unwrapped by party B's IMPORTER key.  Because the keys have the
// NoCvKEK option enabled, they are suitable for exchanging keys with
// non-z systems.

For information on EXPORTER and IMPORTER keys, see Symmetric Transport Keys.

The following illustrates key derivation of a 256-bit AES DATA hardware key using the static unified model of Key Agreement scheme: 

import com.ibm.crypto.hdwrCCA.provider.SymmetricKeyConstants.KeyType;
import com.ibm.crypto.hdwrCCA.provider.SymmetricKeyConstants.KeyUsage;

// Party A
//
KeyAgreement partyAKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");

// Party A wants to derive a 256-bit hardware DATA key enciphered
// under the local master key, the sharedInfo byte array is uniquely
// constructed for this key derivation and shared with party B
//
KDFParameterSpec partyASpec = new KDFParameterSpec(
        256, sharedInfo, KeyType.SECURE_INTERNAL_TOKEN, null, KeyUsage.OP_DATA);

// Party A derives a 256-bit hardware AES key by using his or her own
// private EC key and the public EC key of party B
//
partyAKeyAgreement.init(partyAPrivateKey, partyASpec, (SecureRandom) null);
partyAKeyAgreement.doPhase(partyBPublicKey, true);
SecretKey partyASecretKey = partyAKeyAgreement.generateSecret("AES");


// Party B
//
KeyAgreement partyBKeyAgreement = KeyAgreement.getInstance("ECDH", "IBMJCECCA");

// Party B uses the exact same key derivation specification as party A
// Party B must use the exact same sharedInfo byte array as party A
//
KDFParameterSpec partyBSpec = new KDFParameterSpec(
        256, sharedInfo, KeyType.SECURE_INTERNAL_TOKEN, null, KeyUsage.OP_DATA);

// Party B derives a 256-bit hardware AES key by using his or her own
// private EC key and the public EC key of party A
//
partyBKeyAgreement.init(partyBPrivateKey, partyBSpec, (SecureRandom) null);
partyBKeyAgreement.doPhase(partyAPublicKey, true);
SecretKey partyBSecretKey = partyBKeyAgreement.generateSecret("AES");

// The same hardware AES key is generated through this key derivation
// process by both party A and party B

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. Please note that the JCECCARACFKS and JCE4758RACFKS keystore types are only supported on z/OS. 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:

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.

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.

IBMJCECCA Runtime Exception Handler

In the event of a CCA error, an application can retrieve error data from the CCA API call using the runtime exception class.

The JCECCARuntimeException class:

The IBMJCECCA provider might throw an instance of this class (which extends RuntimeException) during operations calling a CCA interface. The class includes methods to retrieve the following data from the CCA API call:

For example, an application can catch this exception and display CCA API call data as: 

catch (Exception e) {
    if (e instanceof JCECCARuntimeException) {
             JCECCARuntimeException jcre = (JCECCARuntimeException)e;
                System.err.println("API name: " + jcre.getAPIName());
                System.err.println("Message: " + jcre.getExceptionMessage());
                System.err.println("RC: " + jcre.getReturnCode());
                System.err.println("RS: " + jcre.getReasonCode());
    }
    e.printStackTrace();

Configuring and using IBMJCECCA

To use the IBMJCECCA provider, you must add it to the java.security file in the $JAVA_HOME/lib/security directory on z/OS and the $JAVA_HOME/jre/lib/security directory on Linux. If you add it as the first JCE provider in the list, it will be selected automatically for any service and algorithm that it supports if no provider is specified when you invoke getInstance(). If you add it later in the list, you may have to specify it when you invoke getInstance(). To add the IBMJCECCA provider as the first JCE provider, add the following to the java.security file: 

                    security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
                    security.provider.2=com.ibm.crypto.provider.IBMJCE

Note that, if you update the provider list in the java.security file, you must update the sequence numbers as needed so that there are no duplicate sequence numbers or gaps in the sequence numbers.

On z/OS it is necessary to install and start ICSF before attempting to use IBMJCECCA. When running on z/OS see the "z/OS Cryptographic Services ICSF Administrator's Guide" for instructions on installing ICSF.

On Linux for IBM z® it is necessary to install the IBM PCIe Cryptographic Coprocessor software. When running on Linux for IBM z® see the "Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide" guide for software installation instructions. IBMJCECCA is supported on the following minimum Linux distributions and versions of the IBM PCIe Cryptographic Coprocessor software:

If IBMJCECCA is used and ICSF is not started or the IBM PCIe Cryptographic Coprocessor software is not installed some cryptographic operations may fail.

Specifying full function versus limited key size cryptography

For full function cryptography the unrestricted policy files must be installed. By default, the IBM® SDK provides unlimited jurisdiction policy files. To use the limited jurisdiction policy files, set the property crypto.policy=limited in the java.security file. See IBM SDK Policy Files for further information.

Representation of CCA API error code values

When calls are made by the IBMJCECCA provider to CCA services to perform cryptographic operations, return/reason codes are displayed in error messages using the decimal values of the error codes. The codes are documented in the "z/OS Cryptographic Services ICSF Application Programmer's Guide (SA22-7522)" for z/OS and documented in the "Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide" for Linux for IBM z®.

CSFSERV access permissions required for ICSF services used by IBMJCECCA provider

Please note that this section only applies to running IBMJCECCA on z/OS, not for running IBMJCECCA on Linux for IBM z®.

Applications invoking cryptographic operations through the IBMJCECCA provider require various RACF access permissions granted to the exploiter, based upon which services they are exercising in the underlying ICSF code. In situations where an application is invoking cryptographic services which are provided by ICSF through the IBMJCECCA provider, the CSFSERV Access Permissions listed in the table below must be granted for those services to the application userid. Also note that if an application is moved or reconfigured into an environment which will use hardware cryptographic support where it did not use that support previously (for example, it previously invoked cryptographic operations through a pure Java software provider such as IBMJCE), these permissions will be needed to permit execution of those ICSF services providing the requested cryptographic support.

The following are ICSF APIs called by IBMJCECCA provider. The CSFSERV access for each of these ICSF calls is also given below:

ICSF APIs in JCECCA ICSF API Description
-> CSFSERV Access[Access Description]
CSFIQF & CSFIQF6 (64bit) ICSF Query Facility
-> CSFIQF [ICSF Query Facility callable service]
CSNBSYE & CSNESYE (64bit) Symmetric Key Encipher
-> CSFENC [encipher callable service]
-> CSFCVE [cryptographic variable encipher callable]
CSNBSYD & CSNESYD (64bit) Symmetric Key Decipher
-> CSFDEC [decipher callable service]
CSNBSAE & CSNESAE (64bit) Symmetric Algorithm Encipher
-> CSFSAE [symmetric algorithm encipher callable service]
CSNBSAD & CSNESAD (64bit) Symmetric Algorithm Decipher
-> CSFSAD [symmetric algorithm decipher callable service]
CSNBOWH & CSNEOWH (64bit) One-Way Hash Generate
-> CSFOWH [one-way hash generate callable service]
CSNBRNG & CSNERNG (64bit) Random Number Generate
-> CSFRNG [random number generate callable service]
CSNBRNGL & CSNERNGL (64bit) Random Number Generate Long
-> CSFRNGL [random number generate long callable service]
CSNBT31I & CSNET31I (64bit) TR-31 import callable service
-> CSFT31I [TR-31 import]
CSNBT31X & CSNET31X (64bit) TR-31 export callable service
-> CSFT31X [TR-31 export]
CSNDKRC & CSNFKRC (64bit) PKDS Record Create
-> CSFPKRC [PKDS record create callable service]
-> CSFKRC [key record create callable service]
CSNDKRD & CSNFKRD (64bit) PKDS Record Delete
-> CSFPKRD [PKDS record delete callable service]
-> CSFKRD [key record delete callable service]
CSNDRKD & CSNFRKD (64bit) Retained Key Delete
-> CSFRKD [retained key delete callable service]
CSNDPKG & CSNFPKG (64bit) PKA Key Generate
-> CSFPKG [PKA key generate callable service]
CSNDDSG & CSNFDSG (64bit) Digital Signature Generate
-> CSFDSG [digital signature generate service]
CSNDDSV & CSNFDSV (64bit) Digital Signature Verify
-> CSFDSV [digital signature verify callable service]
CSNDPKB & CSNFPKB (64bit) PKA Key Token Build
-> CSFPKG [PKA key generate callable service]
-> CSFPKT [PKA key token change callable service]
CSNDRKL & CSNFRKL (64bit) Retained Key List
-> CSFRKL [retained key list callable service]
CSNDPKX & CSNFPKX (64bit) PKA Public Key Extract
-> CSFPKX [PKA Public Key Extract callable service]
CSNBENC & CSNEENC (64bit) Encipher
-> CSFENC [encipher callable service]
CSNBDEC & CSNEDEC (64bit) Decipher
-> CSFDEC [decipher callable service]
CSNDPKE & CSNFPKE (64bit) PKA Encrypt
-> CSFPKE [PKA encrypt callable service]
CSNDPKD & CSNFPKD (64bit) PKA Decrypt
-> CSFPKD [PKA decrypt callable service]]
CSNDPKI & CSNFPKI (64bit) PKA Key Import
-> CSFPKI [PKA key import callable service]
CSNBCKM & CSNECKM (64bit) Multiple Clear Key Import
-> CSFCKM [multiple clear key import callable service]
CSNBKGN & CSNEKGN (64bit) Key Generate
-> CSFKGN [key generate callable service]
CSNDSYI Symmetric Key Import
-> CSFSYI [symmetric key import callable service]
CSNDSYX Symmetric Key Export
-> CSFSYX [symmetric key export callable service]
CSNDEDH & CSNFEDH (64bit) ECC Diffie-Hellman
-> CSFEDH [ECC Diffie-Hellman callable service]
CSNBKTB & CSNEKTB (64bit) Key Token Build
-> CSFKTB [key token build callable service]
CSNBKGN2 & CSNEKGN2 (64bit) Key Generate2
-> CSFKGN2 [key generate2 callable service]
CSNBKEX & CSNEKEX (64bit) Key Export
-> CSFKEX [key export callable service]
CSNBKIM & CSNEKIM (64bit) Key Import
-> CSFKIM [key import callable service]
CSNDSYI2 & CSNFSYI2 (64bit) Symmetric Key Import2
-> CSFSYI2 [symmetric key import2 callable service]
CSNBKTR2 & CSNEKTR2 (64bit) Key Translate2
-> CSFKTR2 [key translate2 callable service]
CSNBKRC2 & CSNEKRC2 (64bit) Key Record Create2
-> CSFKRC2 [key record create2 callable service]
CSNBKRR2 & CSNEKRR2 (64bit) Key Record Read2
-> CSFKRR2 [key record read2 callable service]
CSNBHMG & CSNEHMG (64bit) HMAC Generate
-> CSFHMG [HMAC generate callable service]

Configuring and using hardware cryptographic devices on IBM z® Platform

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:

Linux for IBM z® specifics

On the Linux for IBM z® platform, access to hardware cryptographic devices is controlled by the IBM PCIe Cryptographic Coprocessor software. The IBM PCIe Cryptographic Coprocessor software provides IBM Common Cryptographic Architecture (CCA) interfaces to hardware devices. IBM PCIe Cryptographic Coprocessor software must be configured and running before the hardware cryptographic device is accessed. For more information about the IBM PCIe Cryptographic Coprocessor software see the publications, including the following:

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 JCE (keytool). The differences between hwkeytool and keytool are as follows:

The additional parameters for genkeypair are:

The additional parameters for genseckey are:

The additional parameter for delete is:

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 CCA key storage area 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 CCA key storage area key pairs.  

The following illustrates creating and storing an RSA key pair with the name Test1 with CCA key storage area hardware: 

hwkeytool -genkeypair -alias Test1 -keyalg RSA -storetype JCECCAKS 
-dname "cn=Testone, 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.PKDS;
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

Please note that this support for RACF only applies to IBM z® servers running z/OS. This function does not apply to IBM z® servers running Linux.

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.

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 in the next section.

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". Unless the java property ibm.hw.racfkeystore.trustchaincheck for the JCECCARACFKS RACF keystore or the java property ibm.racfkeystore.trustchaincheck for the JCERACFKS RACF keystore has been set to false. 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. The following 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

The trustchaincheck property for JCECCARACFKS

ibm.hw.racfkeystore.trustchaincheck=[true|false]

Default: true

The trustchaincheck property for JCERACFKS

ibm.racfkeystore.trustchaincheck=[true|false]

Default: true

A check is done when a RACF keyring is loaded. If there is only one key in the keyring and that key is not self signed then an exception is thrown. To override this default behavior and not perform the check, set the Java property to false. For example:

java -Dibm.hw.racfkeystore.trustchaincheck=false MyApplication

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

Creating a RACFInputStream requires these three parameters:

The following is an example of using RACFInputSteam directly, passing it a user ID, a ring ID and a null password. 

import com.ibm.crypto.provider.RACFInputStream;

String ksfname;
char[] storePass = null;

RACFInputStream riStream = new RACFInputStream(System.getProperty("user.name"),
                                               ksfname,
                                               storePass);
KeyStore racfKeyStore = KeyStore.getInstance("JCERACFKS");
racfKeyStore.load(riStream, storePass);
riStream.close();

In the previous code 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:

The following is an example of using RACFOutputStream directly, passing it a user ID, a ring ID and a null password. 

import com.ibm.crypto.provider.RACFOutputStream;

String ksfname;
char[] storePass = null;

RACFOutputStream roStream = new RACFOutputStream(System.getProperty("user.name"),
                                                 ksfname,
                                                 storePass);
KeyStore racfKeyStore = KeyStore.getInstance("JCERACFKS");
racfKeyStore.store(roStream, storePass);
roStream.close();

In the previous code 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:

  1. A RACFInputStream is created to specify an existing input RACF Key Ring.
  2. The RACFInputStream is loaded into a RACFKeyStore using the RACFKeyStore.load() method.
  3. The input ring contains 1 key entry named Key01 and 1 trusted certificate entry named Cert01.
  4. Key01 is deleted using the RACFKeyStore.delete() method.
  5. Two new key entries named Key02 and Key03 are added to the RACFKeyStore using the RACFKeyStore.setKeyEntry() method.
  6. A RACFOutputStream is created to specify an output RACF Key Ring.
  7. The updates are written to the RACF Key Ring specified in the RACFOutputStream using the RACFKeyStore.Store() method.
    1. First, the delete entry is processed by successfully removing Key01 from the output RACF Key Ring.
    2. Next, all entries from the RACFKeyStore are added to the output RACF Key Ring.
    3. In this example, an error occurs while attempting to add Key02 to the output RACF Key Ring.
    4. Cert01 is added successfully to the output RACF Key Ring.
    5. An error occurs while attempting to add Key03 to the output RACF Key Ring.
  8. 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 releases greater than SDK 1.2, 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: 

java.protocol.handler.pkgs

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: 

java -Djava.protocol.handler.pkgs=com.ibm.crypto.provider 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: 

System.setProperty( "java.protocol.handler.pkgs",
                    "com.ibm.crypto.hdwrCCA.provider" );

Supported key types for storing into a RACF KeyStore

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

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

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:

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: 

RACFInputStream.RACFInputStream()
JceRACFKeyStore.load()
JceRACFKeyStore.setKeyEntry()
JceRACFKeyStore.getKeyEntry()
JceRACFKeyStore.store()
RACFOutputStream.RACFOutputStream()

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 allowed to use the default value.

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 previously described items 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

  1. app1 loads the keystore into a KeyStore object and makes some updates
  2. app2 loads the keystore into a KeyStore object and makes some updates
  3. app1 stores the contents of the KeyStore object into the persistent keystore data
  4. 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 previously. 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:

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:

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:

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.

© Portions Copyright 2003, 2019 IBM Corporation. All rights reserved.

© Portions Copyright 2003, 2019 Oracle and/or its affiliates. All rights reserved.