Modify the Example to use SSL Communications


This section describes how to modify the above example to use SSL communications between the TIBCO Enterprise Message Service server, JBoss, and the client program. This section assumes you have already set up and run the example detailed in the previous sections.

Adding the SSL JAR Files to the CLASSPATH for the JBoss Server

The following JAR files, distributed with TIBCO Enterprise Message Service, must be added to the CLASSPATH of the JBoss server, in the same manner that you added the non-SSL jar files to the JBoss CLASSPATH in the previous example:

jcert.jar  
jnet.jar  
jsse.jar  
tibcrypt.jar  

Add the following line under the <server> element in jms-service.xml:

 
<classpath codebase="file://C:\TIBCO\EMS\clients\java" 
   archives="jcert.jar, jnet.jar, jsse.jar, tibcrypt.jar" /> 

Configuring the TIBCO Enterprise Message Service Server for SSL

  1. Enter the following commands in tibemsadmin:
  2. >create factory SSLXAQueueConnectionFactory xaqueue url=ssl://7243  
     

    This creates a new XAQueueConnectionFactory that establishes SSL connections.

    >setprop factory SSLXAQueueConnectionFactory ssl_verify_host=disabled

    This turns off host verification for connections created by this connection factory. This is the simplest SSL configuration.

  3. In C:\Tibco\EMS\bin\tibemsd.conf, add the following lines:
  4.    listen = ssl://localhost:7243  
     
       ssl_server_identity = certs/server.cert.pem  
       ssl_server_key = certs/server.key.pem  
       ssl_password = password  
     
       listen = tcp://localhost:7222  
     

    These lines explicitly set the tcp and ssl listen ports and specify the three required server-side SSL parameters: identity, private key, and password.

    Save the file, stop and restart the TIBCO Enterprise Message Service server. When it restarts you should see messages like the following in the console window confirming SSL is enabled:

       2002-03-19 13:48:34 Secure Socket Layer is enabled.    2002-03-19 13:48:34 Accepting connections on    ssl://localhost:7243.    2002-03-19 13:48:34 Accepting connections on    tcp://localhost:7222.

Configuring JBoss for SSL-based JMS Communications

There are two aspects to SSL communications between JBoss and the TIBCO EMS server. The first is for messaging between the JBoss and TIBCO servers to occur over SSL. The second is for JNDI lookups from JBoss to the TIBCO JNDI provider to occur over SSL. The following two sections separately describe the required steps for each.

JMS Messaging over SSL

  1. Modify the line you added to jms-service.xml in the previous section which specifies the QueueFactoryRef attribute of the JMS Provider Loader to be the be the new connection factory you just created that establishes SSL connections:
  2.    <attribute name="QueueFactoryRef"> 
          SSLXAQueueConnectionFactory</attribute> 
    
  3. Modify the line you added to jms-service.xml in the previous section to create the JNDI LinkRef ToName to the new connection factory:
  4.    <attribute name="ToName">  
          tibjmsnaming://localhost/SSLXAQueueConnectionFactory  
       </attribute>  
     

    and the name is changed to SSLXAQueueConnectionFactory, the SSL-based XAQueueConnectionFactory that you just created.

JNDI Lookups over SSL

The following steps arrange for the JBoss server to do JNDI lookup using SSL. However, a defect in JBoss 3.0.0 (and later releases) requires TCP for JNDI lookup—SSL is not currently available. In the meantime, we retain these instructions, as we expect a future JBoss release to correct this defect.

  1. In the file %JBOSS_CONF%\jndi.properties, add the following line:
  2.    com.tibco.tibjms.naming.security_protocol=ssl 
     

    This property specifies that the "SSL" protocol should be used for JNDI lookups.

  3. Add the following line in the JMSProviderLoader mbean in jms-service.xml:
  4.    <attribute name="ProviderUrl"> 
          tibjmsnaming://localhost:7243</attribute>  
     

    The new line creates an additional attribute ProviderUrl, that explicitly states the JNDI provider URL (rather than using the default built into the TIBCO Enterprise Message Service JBoss adapter class) with a port number of 7243 for SSL. Note that attribute names are case sensitive and must be entered exactly as shown above.

  5. Modify the line you previously added to jms-service.xml to explicitly specify the SSL port of 7243 in the JNDI LinkRef ToName:
  6.    <attribute name="ToName">  
          tibjmsnaming://localhost:7243/SSLXAQueueConnectionFactory 
       </attribute>  
    
  7. Modify the line in file standardjboss.xml where you specified the TIBCO Enterprise Message Service JNDI name of the DLQ to explicitly specify the SSL port of 7243:
  8. <DestinationQueue>tibjmsnaming://localhost:7243/queue/DLQ</DestinationQueue> 
    

Stop and restart the JBoss server

You should see the same messages in the JBoss console during startup that you saw in the previous section.

Adding the SSL JAR Files to the CLASSPATH for the Client Program

The following JAR files, distributed with TIBCO Enterprise Message Service, must be added to the CLASSPATH of the client program, in the same manner that you added the non-SSL jar files to the CLASSPATH in the previous example:

jcert.jar  
jnet.jar  
jsse.jar  
tibcrypt.jar  

Adding the SSL JNDI Properties for the Client Program

The following changes must be made to the file %JBOSS_CLIENT%\jndi.properties that you modified in the previous section for the client:

  1. Modify the provider url property to specify the SSL port number, as follows:
  2.    java.naming.provider.url=tibjmsnaming://localhost:7243  
    
  3. Add the following lines:
  4.    com.tibco.tibjms.naming.security_protocol=ssl 
       com.tibco.tibjms.naming.ssl_enable_verify_host=false 

    Be sure there are no trailing spaces on either line above (particularly after security_protocol=ssl).

     
     

    These properties specify that the "SSL" protocol should be used for JNDI lookups, and that host verification is turned off (the client will trust any host).

Modify and Rebuild the Client

Modify the client program (SendRecvClient) to look up SSLXAQueueConnectionFactory instead of QueueConnectionFactory. Rebuild the program.

Re-Run the Client Program

Run the client program as you did in the previous section. You should see the same output.

To prove that SSL communications are occurring, you could remove the SSL settings you added to tibemsd.conf in Configuring the TIBCO Enterprise Message Service Server for SSL, and restart the TIBCO Enterprise Message Service server. Then stop and restart JBoss. You should see the following exception in the JBoss console:

javax.jms.JMSException: Failed to connect to the server at  
ssl://localhost:7243  

If you now run the test program again, you should see that it throws the same exception. This shows that when the TIBCO Enterprise Message Service server was set up to accept SSL connections, both clients successfully connected and communicated using SSL.

Alternatively, you could start the TIBCO Enterprise Message Service server from a command prompt window and turn SSL debug tracing on, as follows:

> tibemsd -ssl_debug_trace  

Then when you restart JBoss and re-run the client program, you will see SSL debugging output on the tibemsd console window.


TIBCO Enterprise Message Service™ Application Integration Guide
Software Release 4.3, February 2006
Copyright © TIBCO Software Inc. All rights reserved
www.tibco.com