JSSE2 z/OS unique considerations

Since the JSSE 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 JSSE can utilize. 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 JSSE by using keystores included in the IBMJCE and IBMJCECCA providers called JCERACFKS and JCECCARACFKS. For details on how to setup a RACF keyring for use with JSSE see the IBMJCECCA provider documentation found at here.

The following is an example of how to initialize the KeyManagerFactory with a JCERACFKS Keystore using the IBMJCE provider for cryptographic operations. 

KeyStore ks = KeyStore.getInstance("JCERACFKS");
com.ibm.crypto.provider.RACFInputStream inputStream = new
    com.ibm.crypto.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","safkeyring://Userid/Keyring");

System.setProperty("javax.net.ssl.trustStoreType","JCERACFKS");

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

Note that when using the URL support you will need to have the appropriate JCE provider installed on your system. Along with this provider a URL handler will need to be specified by defining the java.protocol.handler.pkgs environment variable.

For example to specify IBMJCE or IBMJCECCA provider for the URL handler either of the following defines could be added to the invocation of your java application.

For JCE:

-Djava.protocol.handler.pkgs=com.ibm.crypto.provider

For IBMJCECCA:

-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider

See the IBMJCECCA docs found here for more information on the JCERACFKS keystore.

Hardware Cryptographic devices for JSSE2 on z/OS

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

To use JSSE2 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 JSSE2 with the IBMJCE ( software cryptography ) provider the user must do the following:

  1. The IBMJCE provider must be the first JCE cryptographic provider within their java.security provider list.
  2. The user must use a keystore supported by the IBMJCE provider such as the JCEKS keystore.

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

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.