JSSE Unique Considerations

Since the SunJSSE code is 100% Java™ it is platform independent and there is no z/OS® specific code. However, there are a couple of functions in other Java Security components that do provide z/OS specific capabilities that SunJSSE can use. This includes the ability to take advantage of the hardware cryptographic devices that can be present on the z/OS platform along with storing certificates in RACF®.

RACF Keyrings for private keys and certificates

RACF keyrings can be used by SunJSSE by using keystores included in the IBMJCECCA provider called JCECCARACFKS and IBMZSecurity provider called JCERACFKS:

Note: The OpenJCEPlus provider is used for the crypto workloads using software/clear keys and the IBMZSecurity provider for RACF software keystore support..

The following is an example of how to initialize the KeyManagerFactory with a JCECCARACFKS keystore using the IBMJCECCA provider for cryptographic operations.:

KeyStore ks = KeyStore.getInstance("JCECCARACFKS");
com.ibm.crypto.hdwrCCA.provider.RACFInputStream inputStream = new
    com.ibm.crypto.hdwrCCA.provider.RACFInputStream(username,keyring,password.toCharArray());
ks.load(inputStream,password.toCharArray());
KeyManagerFactory kmf = KeyManagerFactory.getInstance("IbmX509");
kmf.init(ks, password.toCharArray());

RACF keyrings can also be accessed by using URL's to specify the desired RACF keyring. For example the following shows how an application could specify a RACF keyring as a truststore:

KeyStore ks = null;
...
// Setup properties for TrustManagerFactory
System.setProperty("javax.net.ssl.trustStore","safkeyringjce://Userid/Keyring");
 
System.setProperty("javax.net.ssl.trustStoreType","JCERACFKS");

System.setProperty("javax.net.ssl.trustStorePassword", "password");
...
TrustManagerFactory tmf = TrustManagerFactory.getInstance("IbmX509");
tmf.init(ks);

For example to specify either the IBMZSecurity, IBMJCECCA, or IBMJCEHYBRID provider, the following 3 new URL safkeyring options are available:

The "safkeyring" URLs are now dependent on the type of RACF keystore.

The URL for a JCECCARACFKS keystore is now "safkeyringjcecca"

The URL for a JCERACFKS keystore is now "safkeyringjce"

The URL for a JCEHYBRIDRACFKS keystore is now "safkeyringjcehybrid"

The java.protocol.handler.pkgs is no longer required in IBM® Semeru Runtime Certified Edition for z/OS, Version 11.0.

Hardware Cryptographic devices for SunJSSE on z/OS

SunJSSE is able to take advantage of using the IBMJCECCA hardware cryptographic provider which allows your SunJSSE application to take advantage of cryptographic devices.

To use SunJSSE with the IBMJCECCA ( hardware cryptography ) provider the user must do the following:

  1. The IBMJCECCA provider must be the first JCE cryptographic provider within their java.security provider list.
  2. The user must use a keystore supported by the IBMJCECCA provider such as the JCECCAKS keystore.
To use SunJSSE with the OpenJCEPlus (software cryptography) provider the user must do the following:
  1. The OpenJCEPlus provider must be the first JCE cryptographic provider within their java.security provider list.
  2. The user must use a keystore implemented by another JCE provider such as IBMZSecurity, SUN, or SunJCE.
The algorithms which are not yet supported by OpenJCEPlus are:
  • The AES-CTR algorithm for data encryption and decryption is not supported.

Documentation for OpenJCEPlus can be found here: OpenJCEPlus provider

Note: Please be sure to use the unrestricted policy files which are required to use the IBMJCECCA provider.