Example: Programmatically specifying an outbound SSL configuration using JSSEHelper API

 

WAS provides a way to specify programmatically which SSL configurations to use prior to making an outbound connection. The com.ibm.websphere.ssl.JSSEHelper interface provides a complete set of APIs for handling SSL configurations. You must perform the following steps for your application when using the JSSEHelper API to establish an SSL properties object on the thread for use by the runtime. Some of these APIs have Java 2 Security permission requirements. See the JSSEHelper API documentation for more information about the permissions required by your application.

1. Obtain an instance of the JSSEHelper API by typing the following command:

   com.ibm.websphere.ssl.JSSEHelper jsseHelper 
   = com.ibm.websphere.ssl.JSSEHelper.getInstance();
   

2. Obtain SSL properties from the WAS configuration or use those provided by your application. You can obtain these properties in several ways:

   • By direction selection of an alias name, within the same management scope or higher as in the following example:

     try
     {
       String alias = "NodeAServer1SSLSettings";  
     // As specified in the WebSphere SSL configuration   Properties sslProps = jsseHelper.getProperties(alias);
     } catch (com.ibm.websphere.ssl.SSLException e)
     {
       e.printStackTrace();   // handle exception
     }
     

   • By using the getProperties API for programmatic, direction, dynamic outbound, or management scope selection (based on precedence rules and inheritance). The SSL runtime uses the getProperties API to determine which SSL configuration to use for a particular protocol. This decision is based on both the input (sslAlias and connectionInfo) and the management scope from which the property is called. The getProperties API makes decisions in the following order:

     1. The API checks the thread to see if properties already exist.

     2. The API checks for a dynamic outbound configuration that matches the ENDPOINT_NAME, REMOTE_HOST, and or REMOTE_PORT.

     3. The API checks to see if the optional sslAlias property is specified. You can configure any protocol as direct or centrally managed. When a protocol is configured as direct, the sslAlias parameter is null. When a protocol is configured as centrally managed, the sslAlias parameter is also null.

     4. If no selection has been made, the API chooses the dynamic outbound configuration based on the management scope it was called from. If the dynamic outbound configuration is not defined in the same scope, it then searches the hierarchy to locate one.

     The last choice is the cell-scoped SSL configuration (in ND) or the node-scoped SSL configuration (in Base Application Server). The com.ibm.websphere.ssl.SSLConfigChangeListener parameter is notified when the SSL configuration that is chosen by a call to the getProperties API changes. The protocol can then call the API again to obtain the new properties as in the following example:

     try
     {
       String sslAlias = null;  // The sslAlias is not specified directly at this time.
       String host = "myhost.austin.ibm.com";  // the target host
       String port = "443";  // the target port
     
       HashMap connectionInfo = new HashMap();
       connectionInfo.put(JSSEHelper.CONNECTION_INFO_DIRECTION, 
       JSSEHelper.DIRECTION_OUTBOUND);
       connectionInfo.put(JSSEHelper.CONNECTION_INFO_REMOTE_HOST, host);
       connectionInfo.put(JSSEHelper.CONNECTION_INFO_REMOTE_PORT, 
       Integer.toString(port));
       connectionInfo.put(JSSEHelper.CONNECTION_INFO_ENDPOINT_NAME, 
       JSSEHelper.ENDPOINT_IIOP);
                
       java.util.Properties props = jsseHelper.getProperties(sslAlias, 
       connectionInfo, null);
     } catch (com.ibm.websphere.ssl.SSLException e)
     {
       e.printStackTrace();   // handle exception
     }
     

   • By creating your own SSL properties and then passing them to the runtime, as in the following example:

     try
     {
       // This is the recommended "minimum" set of SSL properties. The trustStore can 
       // be the same as the keyStore.
       Properties sslProps = new Properties();
       sslProps.setProperty("com.ibm.ssl.trustStore", "some value");
       sslProps.setProperty("com.ibm.ssl.trustStorePassword", "some value");
       sslProps.setProperty("com.ibm.ssl.trustStoreType", "some value");
       sslProps.setProperty("com.ibm.ssl.keyStore", "some value");
       sslProps.setProperty("com.ibm.ssl.keyStorePassword", "some value");
       sslProps.setProperty("com.ibm.ssl.keyStoreType", "some value");
     
       jsseHelper.setSSLPropertiesOnThread(sslProps);
     } catch (com.ibm.websphere.ssl.SSLException e)
     {
       e.printStackTrace();   // handle exception
     }
     
     

3. Use the JSSEHelper.setSSLPropertiesOnThread(props) API to set the Properties object on the thread so that the runtime picks it up and uses the same JSSEHelper.getProperties API. You can also obtain properties from the thread after they are set with the jsseHelper.getSSLPropertiesOnThread() API, as in the following example:

   try
   {
     Properties sslProps = jsseHelper.getProperties(null, 
     connectionInfo, null); jsseHelper.setSSLPropertiesOnThread(sslProps);
   } catch (com.ibm.websphere.ssl.SSLException e)
   {
     e.printStackTrace();   // handle exception
   }
   

4. When the connection is completed, clear the SSL properties from the thread by passing the null value to the setPropertiesOnThread API, as in the following example:

   try
   {
     jsseHelper.setSSLPropertiesOnThread(null);
   } catch (com.ibm.websphere.ssl.SSLException e)
   {
     e.printStackTrace();   // handle exception
   }
   

Select the approach that best fits your connection situation when you specify programmatically which SSL configurations to use prior to making an outbound connection.

---

 

Related tasks

Associating a Secure Sockets Layer configuration dynamically with an outbound protocol and remote secure endpoint

 

Reference topic