+

Search Tips   |   Advanced Search

(ZOS) Use System Authorization Facility keyrings with Java Secure Sockets Extension

WebSphere Application Server for z/OS customers running server W50100x or later, with Java Development Kit 1.3 level SR20 or later, can modify their WAS systems to use System Authorization Facility (SAF) for JSSE as well as SSL, which eliminates the need to maintain duplicate certificates in the hierarchical file system (HFS).

WAS for z/OS running at maintenance levels before W502000 stored digital certificate information in two different places because of the following Software Development Kit (SDK) restrictions:

Systems customized at W502000 or later use the single SAF digital certificate repository by default, and do not need the following modifications.

WAS for z/OS customers running server W50100x or later, with Java Development Kit 1.3 level SR20 or later, can modify their WAS systems to use SAF for JSSE as well as SSL (eliminating the need to maintain duplicate certificates in the HFS). The following instructions describe how to enable this support.

Systems that are customized at maintenance levels at or after W502000 use the single (SAF digital certificate repository by default, and these systems do not need the following modifications.

To use SAF certificates with JSSE:


Tasks

  1. Update the JMX connector settings to indicate the SAF keyring names for the node.

    1. Log in to the administrative console using an identity with administrator authority.

    2. Click Servers > Application servers > server.

    3. Under Server infrastructure, click Administration > Administration services.

    4. Under Additional properties, click JMX connectors.

    5. On the JMX Connectors panel, click SOAPConnector.

    6. Under Additional Properties, click Custom Properties.

    7. On the Custom properties page, click sslConfig.

    8. On the sslConfig page, look at the Value field. Verify that this field says node/DefaultSSLSettings, where nodename represents the node name where the application server resides. Record the node name for a subsequent step.

    9. Select node/RACFJSSESettings from the list next to the Value field, where node is the same as the node name that you previously recorded.

    10. Click OK. The Custom Properties page appears with a message indicating that changes are made to the local configuration. Do not click Save because additional changes required.

  2. Click Servers > Application servers and repeat the previous substeps for each of the other application servers in the cell.
  3. Update the JMX connector settings to indicate the SAF keyring names for the deployment manager node.

    1. Click System administration > Deployment manager.

    2. Under Additional properties, click Administration services > JMX Connectors.

    3. On the JMX Connectors panel, click SOAPConnector.

    4. Under Additional properties, click Custom properties.

    5. On the Custom properties page, click sslConfig.

    6. On the sslConfig page, look at the Value field. This field displays dmnode/DefaultSSLSettings, where dmnode represents the deployment manager node name. Record the node name for a subsequent step.

    7. Select dmnode/RACFJSSESettings from the list next to the Value field, where dmnode represents the Deployment Manager node name.

    8. Click OK. After a short time the Custom Properties page appears with a message indicating that changes have been made to the local configuration. Do not click Save at this point because there are additional changes required.
  4. Update the JMX connector settings to indicate the SAF keyring names for the node agent.

    1. Click System administration > Node agents > Node_name. Record the node agent name for the next step.

    2. Under Additional properties, click Administration services > JMX Connectors.

    3. On the JMX Connectors panel, click SOAPConnector.

    4. Under Additional properties, click Custom properties.

    5. On the Custom properties page, click sslConfig.

    6. On the sslConfig page, look at the Value field. This field displays nodename/DefaultSSLSettings, where nodename is the node name where the node agent resides. Record the node name for a subsequent step.

    7. Select nodename/RACFJSSESettings from the list next to the Value field, where nodename is the node name that you previously recorded.

    8. Click OK. The Custom Properties page is displayed with a message indicating that changes have been made to the local configuration. Do not click Save at this point because additional changes are required.

  5. Click System administration > Node agents and repeat the previous substeps for each of the other node agents servers in the cell.

  6. Click Save when the Changes have been made to the local configuration. Click Save to apply changes to the master configuration message is displayed.

  7. On the Save page, select the Synchronize changes with Nodes option and click Save. After the changes are saved, the administrative console returns to the home page.
  8. Update the soap.client.props file in the profile_root/properties directory to indicate the SAF keyring names that are appropriate for our configuration. The soap.client.props file is used by the wsadmin.sh script and is located in the application server or deployment manager (user.install.root)/properties file. The purpose of the soap.client.props file is to specify the values used by SOAP clients such as wsadmin.sh. In a cell configured before WAS for z/OS maintenance level W502000, the soap.client.props file indicates the names of the Java key stores used by JSSE. Once your cell is using SAF keyrings for JSSE administration, verify that SAF keyrings are being used for SOAP clients.

    The soap.client.props file is used by the wsadmin.sh script.

    Changes to wsadmin client SAF keyrings require updates to the soap.client.props file and the creation of a keyring for administrators. Specify the following values: 

    com.ibm.ssl.protocol=SSL
com.ibm.ssl.keyStoreType=JCERACFKS
com.ibm.ssl.keyStore=safkeyring:///yourkeyringName
com.ibm.ssl.keyStorePassword=password
com.ibm.ssl.trustStoreType=JCERACFKS
com.ibm.ssl.trustStore=safkeyring:///yourKeyringName
com.ibm.ssl.trustStorePassword=password
    =

    The password value specified does not represent a real password because we can use any string. Replace the string yourKeyringName with the administrative SAF keyring. The keyring name used by all WebSphere administrators and the administrative started task user ID (default WSADMSH) must be the same. Additionally, a keyring must be created for each user that uses the wsadmin.sh file with the SOAP connector when using SAF keyrings and security is enabled. (A keyring is created by the customization process for our initial administrative user ID, such as WSADMIN.)

    A description of how to create keyrings for administrative users in SAF is described in SSL considerations for WAS administrators.

  9. Recycle the cell.


Related:

  • Server and administrative security
  • Developing extensions to the WebSphere security infrastructure
  • SSL considerations for WAS administrators