JSSE unique considerations

Since the SunJSSE code is 100% Java™, it is platform independent and does not have z/OS® specific code. However, there are a couple of functions in other Java security components that provide z/OS specific capabilities that SunJSSE can use. The functions help you take advantage of the hardware cryptographic providers that might be present on the z/OS platform along with storing certificates in RACF®.

Hardware cryptography 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, do the following.
  1. The IBMJCECCA provider must be the first JCE cryptographic provider within your java.security provider list.
  2. Use a keystore that is supported by the IBMJCECCA provider such as the JCECCAKS keystore.
To use SunJSSE with the OpenJCEPlus (hardware-accelerated cryptography) provider, do the following.
  1. The OpenJCEPlus provider must be the first JCE cryptographic provider within your java.security provider list.
  2. Use a keystore that is implemented by another JCE provider such as IBMZSecurity, SUN, or SunJCE.

For more information about OpenJCEPlus, see OpenJCEPlus provider

Note: Make sure to use the unrestricted policy files, which are required to use the IBMJCECCA provider.

RACF key rings for private keys and certificates

RACF key rings can be used by SunJSSE by using keystores that are included in the IBMJCECCA provider that is called JCECCARACFKS, IBMZSecurity provider that is called JCERACFKS, and IBMJCEHYBRID provider called JCEHYBRIDRACFKS.

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

An example here shows how to initialize the KeyManagerFactory with a JCECCARACFKS keystore by 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 key rings can also be accessed by using URLs to specify the wanted RACF key ring. For example, the following code shows that an application might specify a RACF key ring 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);

To specify either the IBMZSecurity, IBMJCECCA, or IBMJCEHYBRID provider, the following 3 URL safkeyring options are available. In this method, the safkeyring URLs depend on the type of RACF keystore. The java.protocol.handler.pkgs is not required in this method.

  • The URL for a JCERACFKS keystore is safkeyringjce.
  • The URL for a JCECCARACFKS keystore is safkeyringjcecca.
  • The URL for a JCEHYBRIDRACFKS keystore is safkeyringjcehybrid.

Ability to specify safkeyring along with java.protocol.handler.pkgs is supported as another method.

The RACF keystore-independent URL safkeyring safkeyring:// can be used to specify the RACF key ring and user ID along with the option java.protocol.handler.pkgs.

To summarize, the following options are available to access RACF key rings from different providers.
  • From IBMZSecurity provider, use safkeyringjce:// or safkeyring:// + java.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider
  • From IBMJCECCA provider, use safkeyringjcecca:// or safkeyring:// + java.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider
  • From IBMJCEHYBRID provider, use safkeyringjcehybrid:// or safkeyring:// + java.protocol.handler.pkgs=com.ibm.crypto.ibmjcehybrid.provider