Hardware Cryptographic devices for z/OS

Introduction

The IBMJCECCA provider replaces the IBMJCE4758 provider from earlier releases.

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

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

For more information about the cryptographic features supported, refer to the zSeries machine's reference or technical guide and your service / support organization. See http://www-03.ibm.com/systems/z/os/zos/tools/java/products/j6jcecca.html#over for more information about the cryptographic services which are supported by the hardware cryptographic devices you have installed. 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 lib/ext/java.security file.

Types of cryptographic hardware utilization

In the cryptography environment there are multiple ways to take advantage of cryptographic hardware. The IBMJCECCA provider supports 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 two types supported only for asymmetric key pairs are RETAINED and PKDS. The two types supported only for symmetric keys are CKDS and PROTECTED. Type CLEAR is supported both for asymmetric key pairs and for symmetric keys. Each type is described in 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.

RETAINED hardware key pairs

Cryptographic hardware can be used to maximize the security of the environment. The most secure implementation of cryptography supported by the IBMJCECCA provider stores the keys on the actual hardware cryptographic device and never allows the private key (the sensitive part of the key pair) to be retrieved or viewed. This is called a RETAINED key pair because the private key is retained on the actual hardware device and can never be viewed or retrieved in the clear. What is stored in the JCE keystore or returned to the application at key pair generation is only a reference to the private key, called a label. When the actual key is needed for a cryptographic operation, the operation request is submitted to the hardware card where the key is retained, accompanied by the key label. The cryptographic operation is performed on the card using the retained key and only the results are returned.

This is the most secure of the hardware key types, but also tends to be the slowest. This is because the cryptographic calls for a specific key pair must go to the particular hardware device that retains that key pair. Consequently, the request can not take advantage of multiple (functionally equivalent) cryptographic devices that might be available on the system.

Note that new RETAINED hardware key pairs may only be created on z/OS V1R8 and earlier versions of the operating system. Existing RETAINED hardware key pairs may be read and deleted on all versions of z/OS.

PKDS hardware key pairs

These keys are known to ICSF as encrypted DATA keys. In this case the encrypted DATA key is subsequently stored in the PKDS.

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

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

CKDS hardware symmetric keys

These keys are known to ICSF as encrypted DATA keys. In this case the encrypted DATA key is subsequently stored in the CKDS.

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. This key storage area is a RACF-protected data set. The clear text version of this key can never be viewed or retrieved. What is stored in the JCE keystore or returned to the application at key generation is only a reference to the key, called a label. Because the key is stored in a data set instead of on a particular hardware device, cryptographic operations using CKDS keys can take advantage of multiple cryptographic hardware devices. When a cryptographic operation request is received, the key is decrypted by the CCA software layer and the request is submitted to the next available cryptographic device.

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

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

PROTECTED hardware symmetric keys

These keys are known to ICSF as encrypted DATA keys.

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

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

The PROTECTED key type has the highest level of security supported by the IBMJCECCA provider for symmetric keys. Operations using PROTECTED 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 ICSF as clear DATA 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 PKDS or CKDS, no overhead for decrypting the 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 RETAINED, CKDS and PKDS keys, the application will have only a label. For PROTECTED 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 PROTECTED keys for performance reasons, they can be stored in keystore entries that are password protected. While password protection is provided for all keystore entries, regardless of the type of key stored in the entry, it is not as important for RETAINED, PKDS and CKDS keys. This is because, for RETAINED, PKDS and CKDS keys, the keystore entry contains only a key label and no sensitive key information.

Key generation and storage

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

RSA Signature and Verification

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

An additional benefit provided by cryptographic hardware is the choice of three levels of security: CLEAR key pairs, PKDS based key pairs and RETAINED key pairs. 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.

MD2, MD5, and SHA hashing algorithms

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

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

Note the following regarding the SHA algorithms.

Random Number Generation

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

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 ICSF. 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 ICSF. If a user enables ICSF 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 then 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 next 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 or DSA with appropriate attributes (described in the next 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. 

Specific Changes and Requirements

The following sections discuss the restrictions and features that differ from the basic software JCE provider (IBMJCE) to the hardware assisted JCE provider (IBMJCECCA).

The KeyFactory Class:

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

AES

The IBMJCECCA provider supports a key type for AES keys that have been stored previously in the host CKDS. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CKDS label for the key.

Other keySpec classes supported by the AES KeyFactory include the AESKeySpec and the SecretKeySpec.

DES

The IBMJCECCA provider supports a key type for DES keys that have been stored previously in the host CKDS. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CKDS label for the key.

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

Triple DES (aka DESede and 3DES)

The IBMJCECCA provider supports a key type for triple DES keys that have been stored previously in the host CKDS. The keys are objects of type SecretKey. The SecretKeyFactory can be used to generate a key of this type from a KeyLabelKeySpec containing the CKDS label for the key.

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

DSA

The IBMJCECCA provider supports a key type for DSA private hardware keys that is similar to the DSA Private keys available in software providers. DSA private hardware keys are objects of type DSAPrivateHWKey. The corresponding DSA public keys are objects of type DSAPublicKey.

The KeyFactory class can be used to generate a DSA Private hardware key from a DSAPrivateKeyHWSpec. The KeyFactory can also be used to generate a DSA public key from a DSAPublicKeySpec or an X509EncodedKeySpec.

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

RSA

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

The KeyFactory class can be used to generate an RSA private hardware key from a RSAPrivateHWKeySpec, RSAPrivateCrtKeySpec, RSAPrivateKeySpec, or KeyLabelKeySpec. The KeyFactory can also be used to generate an RSA public key from an RSAPublicKeySpec, X509EncodedKeySpec, or KeyLabelKeySpec. Keys that already in the PKDS can also be created by passing a KeyLabelKeySpec to the RSA KeyFactory.

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

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

Algorithm Parameters Classes:

The CCAAlgorithmParameterSpec class:

This class (which implements the AlgorithmParameterSpec interface) specifies whether the AES, DES, or triple DES key to be generated or unwrapped will be a secret hardware key and whether it will be stored in the CKDS.

In the default case, an object of this class is created without specifying a key type, and this object is passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() will return a key object containing the requested key encrypted using the host master key.

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

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

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

CCAAlgorithmParameterSpec has the following constructors:

Parameters that can be passed to the constructors:

CCAAlgorithmParameterSpec has the following methods:

public int getKeySize()

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

public byte getHwType()

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

public String getLabel()

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

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

The KeyParameterSpec class for DSA hardware (DSAHWKeyParameterSpec):

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

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 Key Interface Class:

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

A software reference to a private hardware key of type PKDS or RETAINED is not a key or a key specification, but instead is a label that can be specified to the IBMJCECCA provider in place of a key. The following method can be used to retrieve the representation of a hardware key pair:

public byte [] getToken()

For a DSA key pair, getToken() returns the label that represents the key stored in the PKDS associated with the hardware.

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

Key Specification Interfaces and Classes

The KeyLabelKeySpec Class

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

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

It has the following methods:

public String getLabel()

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

public byte[] getLabelBytes()

This method returns the IBM-1047 byte representation of the CKDS label for the key or the PKDS label for the key pair.
The DSAPrivateHWKeySpec Class

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

public byte[] getLabel()

This method returns the private key label.

public DSAKeyHWAttributes getAttributes()

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

public DSAParameterSpec getDSAParamSpec()

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

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

The RSAPrivateHWKeySpec Class

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

public byte[] getToken()

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

public RSAKeyHWAttributes getAttributes()

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

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

The SecureRandom Class:

The SecureRandom class in this provider is a true random number generator that does not need seeding. Therefore, calls to setSeed(), getSeed() and generateSeed() will throw an exception.

The following illustrates using SecureRandom: 

java.security.SecureRandom random = null;
random = java.security.SecureRandom.getInstance( "IBMSecureRandom");
byte[] testData = new byte[1024];
random.nextBytes(testData);

In this example, an instance of the SecureRandom class is obtained, a byte array is instantiated, and a random number of size 1024 bytes is generated.

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

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 only support the Cipher Block Chaining (CBC) and Electronic Code Book (ECB) versions of DES. That is, all of the DES ciphers are supported by the IBMJCECCA provider, but only CBC and ECB modes use hardware cryptography.

It is not always more efficient to use hardware cryptography instead of software cryptography. The DES algorithm is not as compute intensive as some asymmetric algorithms such as RSA. For smaller data sizes, software DES cryptography can be faster than hardware cryptography. Because of this, a software version of DES with CBC and ECB also were implemented in the IBMJCECCA provider. For small amounts of data, software DES (CBC or ECB) is sometimes faster than hardware DES (CBC or ECB) cryptography, The exact size of the data at which the performance trade off is found varies from system to system. Therefore, a "clip level" is used to specify the data size at which hardware cryptography is used. Any data length below the clip level will use software cryptography. The clip level is a system property called "ibm.DES.usehdwr.size" and has a default value of 60. Thus, by default, any DES CBC or ECB processing where the data size is less than 60 bytes will be performed using software cryptography and any data size of 60 bytes or more will be performed using hardware cryptography. For ciphers other than DES CBC and DES ECB this system property has no function.

You can adjust the clip level by changing the system property to the desired level. If you set the system property to 0, all DES CBC and DES ECB processing will be performed using hardware cryptography. If you set the system property to -1, all DES CBC and DES ECB processing will be performed using software cryptography. This system property applies to both DES and triple DES CBC and ECB processing.

Note that the data size comparison to the clip level is done when the first data is passed to the cipher for encryption or decryption. For example, consider an application that decrypts the contents of a tape by reading each record and passing it to the cipher before reading the next record. In this case, the first record passed to the cipher object will be the tape header. If the tape header is smaller than the current clip level, the decryption will be done using software, even though the subsequent records may be very large. This is a case where you might choose to set the clip level to 0 so that hardware cryptography will be used, regardless of the size of the first record processed.

The 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 only support the Cipher Block Chaining (CBC) and Electronic Code Book (ECB) version of triple DES. That is, all of the triple DES ciphers are supported by the IBMJCECCA provider, but only CBC and ECB use hardware cryptography.

Triple DES is slightly more compute intensive than DES, but like DES is less compute intensive than asymmetric algorithms such as RSA. Therefore, for smaller data sizes, software triple DES cryptography can be faster than hardware triple DES cryptography. For this reason, triple DES with CBC or ECB is also implemented in software within the 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) and the Electronic Code Book (ECB) versions of AES. Software failover support, as provided for DES and DESede, is available for AES ECB ciphers and AES CBC ciphers only.

RSA: Keys

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

RSA: Operations

Both RSA encryption and decryption are available in the IBMJCECCA provider using hardware cryptography. Because the RSA algorithm is quite compute intensive, using hardware cryptography provides significant performance improvements over software cryptography. Using hardware to perform the RSA encryption and decryption also allows use of the more secure PKDS stored key pairs and RETAINED key pairs. With a PKDS stored key pair or a RETAINED key pair, the sensitive private key is never made available in the clear.

In software implementations of JCE providers (such as IBMJCE), RSA encryption and decryption are implemented with PKCS 1 type 2 padding. RSA encryption and decryption with PKCS 1 type 2 padding is also implemented in hardware cryptography and available with the IBMJCECCA provider.

However, there are two restrictions imposed by the hardware:

The 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 following keys are not supported for RSA wrapping with AMODE(64):

The IBMJCECCA provider supports RSA unwrapping of a symmetric key for import from another host. By default, the resulting (unwrapped) key object will contain a clear key.

If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.PROTECTED, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain a hardware token. This token will contain the key encrypted with the host master key. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object will contain the label for a CKDS entry that contains a hardware token. This token will contain the key encrypted with the host master key. Unwrapping to a key object containing a hardware token is not supported with AMODE(64).

The following illustrates generating a triple DES key object containing a clear key, wrapping it, then unwrapping it to a triple DES key object containing a clear key. 

// Generate a clear triple DES key
//
KeyGenerator keyGen =
        KeyGenerator.getInstance("DESede", "IBMJCECCA");
Key tdesKey = keyGen.generateKey();

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

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

// Unwrap the triple DES key as for import
// Unwrap to a clear key
//
Key unwrappedDesKey =
        rsaCipher.unwrap(wrappedKey, "DESede", Cipher.SECRET_KEY);

The following illustrates generating a triple DES key object containing a hardware key token, wrapping it, then unwrapping it to a triple DES key object containing a hardware key token. 

// Generate a secure triple DES hardware key
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec();
KeyGenerator keyGen =
        KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGen.init(ccaAlgParmSpec, null);
Key tdesKey = keyGen.generateKey();

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

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

// Unwrap the triple DES key as for import
// Unwrap to a secure hardware key
//
CCAAlgorithmParameterSpec ccaAlgParmSpec_forUnwrap =
        new CCAAlgorithmParameterSpec();
rsaCipher.init(Cipher.UNWRAP_MODE, rsaPriv,
               ccaAlgParmSpec_forUnwrap, null);
Key unwrappedDesKey =
        rsaCipher.unwrap(wrappedKey, "DESede", Cipher.SECRET_KEY);

The following illustrates deleting a RSA hardware key object for a key stored in PKDS, with the label "MYRSAKEY". 

// Get the key store instance, open an input stream to the
// keystore file and load the key store.
//
KeyStore jceccaks = KeyStore.getInstance("JCECCAKS", "IBMJCECCA");
InputStream istream = new FileInputStream("keyStore.cca");
jceccaks.load(istream, "keystorePW".toCharArray());

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

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

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

// Write the modified key store contents to the key store file.
//
OutputStream ostream = new FileOutputStream("keyStore.cca");
jceccaks.store(ostream, "keystorePW".toCharArray());

NOTE: The DSAPrivateHWKey class also has a deletePKDSEntry method. The code previously described can be followed to delete DSA private hardware PKDS key entries by substituting the DSAPrivateHWKey class for the RSAPrivateHWKey class.

HMAC and PBE

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

Keystores for IBMJCECCA

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

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

For an example of migrating keys from one keystore to another, see Migrate.java in the

$(java_home)/demo/jcecca/src

directory, where $(java_home) is the directory where the Java SDK is installed.

Default Keystore for IBMJCECCA

The default JCE keystore is named .keystore and is located in the user's home directory. The default JCECCAKS keystore is named .HWkeystore and is located in the user's home directory.

On the z/OS platform, the user with ID userid has a default home directory (user.home) of /home/userid. For example, the user ID U23LPTQ would, by default, have a home directory of /home/U23LPTQ.

Configuring and using IBMJCECCA

To use the IBMJCECCA provider, you must add it to the java.security file in the ${java-home}/lib/security directory. 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 in the ${java-home}/lib/security directory: 

                    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.

It is also necessary to start ICSF before attempting to use IBMJCECCA. If IBMJCECCA is used and ICSF is not started some cryptographic operations may fail.

Specifying full function versus limited key size cryptography

Files US_export_policy.jar and local_policy.jar, in directory ${java-home}/lib/security, give you the ability to do limited function cryptography and are installed by default.

For full function cryptography you need an unrestricted policy that gives the ability to do full function cryptography. The policy files may be downloaded. Replace US_export_policy.jar and local_policy.jar in the ${java-home}/lib/security directory with the new files.

Representation of ICSF error code values

When calls are made by the IBMJCECCA provider to ICSF 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). See Appendix A for a list of Return Codes and Reason Codes from the ICSF Callable Services.

CSFSERV access permissions required for ICSF services used by IBMJCECCA provider

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]
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 & CSNFSYI (64bit) Symmetric Key Import
-> CSFSYI [symmetric key import callable service]
CSNDSYX & CSNFSYX (64bit) 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]

Configuring and using hardware cryptographic devices on z/OS

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

z/OS specifics

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

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 CKDS, PKDS, and/or RETAINED key entries. By default, the JCE methods generate a random label to identify the key entry. 

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

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

hwkeytool -genkeypair -alias Test1 -keyalg RSA -storetype JCECCAKS 
-dname "cn=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.RETAIN;
     byte keyUsage = KeyHWAttributeValues.KEYMANAGEMENT;
     keyAttribs = new RSAKeyHWAttributes(storeType,keyUsage);
     WrapperKey wrappedKey =
          new WrapperKey((java.security.PrivateKey)SoftwareKey,keyAttribs);

     okeyStore.setKeyEntry(alias, wrappedKey, istorePass, certs);

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

Introduction

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

See Key Management for more information on keystores.

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

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

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

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

z/OS Security Server RACF Callable Services - SA22-7691

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

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 left to default.

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

hwkeytool and the ICSF CSFSERV and CSFKEYS RACF classes

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

Developers and users of programs that invoke the Java security class KeyPairGenerator to generate an IBMJCECCA public and private key pair should also be aware of 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.

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

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