(ZOS) RACF keyring setup

Use Java to create a RACFInputStream for a RACF keystore

During the SSL authentication process, WebSphere Application Server considers a certificate that connects as a PERSONAL certificate as a KeyEntry. Use the certificate as an end-user certificate in an SSL handshake because the private key is available.

WAS considers a certificate that connects as a CERTAUTH certificate as a TrustedCertEntry and treats the certificate as a Certificate Authority (CA). Keyrings require certificates that connect as PERSONAL and CA certificates that connect as CERTAUTH. Certificates that connect as SITE are not supported in this release.

A RACF keyring that a JSSE client and server can use for both trust and key information is shown in the following sample code:

Certificate Label Name Cert Owner USAGE    DEFAULT
---------------------- ---------- -------- -------
PersonalEndUserCert    ID(USERID) PERSONAL YES
PersonalEndUserCACert  CERTAUTH   CERTAUTH NO

We must add the certification path provider to your Java environment to construct certificate chains from certificates that WAS reads from the Resource Access Control Facility (RACF). Add the following line to your java.security file provider list:

security.provider.X=com.ibm.security.cert.IBMCertPath

If one of the RACF certificates fails to load, the keystore is not loaded. Remove any unwanted certificates from the keyring.

The RACFInputStream contains three parameters:

• userid - a string containing the ID of the user that owns the keyring
• ringid - a string containing the name of the RACF key ring
• password - a character array containing the password for the keystore

The following code example shows the RACFInputStream script passing in a user ID, a ring ID, and a null password directly:

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 example, the system property user.name is referenced to provide the userID that WAS passes to RACF. This example is not typical.

For more information about running the RACFInputStream script, see the document z/OS Unique Considerations for the Java 2 SDK, Standard Edition, v 6.0. A link to this z/OS document is provided in the Related Links section of this topic.

Access a RACFInputStream using URLStreamHandler

In this release, we can access data through user-defined classes with the URLStreamHandler object. WAS can define the classes that access the data with the system property java.protocol.handler.pkgs. To access data that resides in a Service Authorization Facility (SAF) RACF keyring, use the safkeyring URL with the associated classes.

To use the URLStreamHandler class to create a RACFInputStream, define the following Java property :

-Djava.protocol.handler.pkgs

If we are using the IBM Java Cryptography Extension (IBMJCE) provider to provide cryptographic support, set the property to the following value:

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

If we are using the IBMJCE4758 provider to provide cryptographic support, set the property to the following value:

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

Use a URL to specify a stream handler in the java.policy file. The jarsigner utility also accepts a URL for the -keystore parameter. When certificates from a RACF keyring verify signed jar files, we can specify that WAS must use the keyring as an input stream to the keystore in the java.policy file, as shown in the following example code:

keystore "safkeyring://myracfid/my_key_ring", " JCERACFKS";

In this example,

• safkeyring is the URL keyword that the server uses to access the URLStreamHandler code to read data from the keyring
• myracfid is the RACF userid that has authority to read data from the keyring
• my_key_ring is the name of the keyring from which the data is read
• JCERACFKS is the keystore type defined for a SAF (RACF) keyring keystore

The Java Virtual Machine (JVM) must be started with the java.protocol.handler.pkgs property set to one of the values described previously, so that WAS can call the appropriate URLStreamHandler. The following example shows the jarsigner utility using a safkeyring URL:

jarsigner -keystore safkeyring://myracfid/my_key_ring -signedjar ibmjceproviders.jar ibmjceprovider.jar ibmprovider -storetype JCERACFKS

For more information on inserting or updating information in the RACF External Security Manager, refer to the RACDCERT command in the following publications:

• z/OS SecureWay Security Server RACF Security Administrator's Guide - SA22-7683
• z/OS SecureWay Security Server RACF Command Language Reference - SA22-7687

Secure specific application servers

z/OS Unique Considerations for the Java 2 SDK, Standard Edition, v 6.0