Step 5. Configuring an HTTPS Connection

A client application must use an appropriately configured connection factory administered object to make an HTTPS connection to a broker.

However, the client must also have access to SSL libraries provided by the Java Secure Socket Extension (JSSE) and must also have a root certificate. The SSL libraries are bundled with JDK 1.4. If you have an earlier JDK version, see Configuring JSSE otherwise proceed to Importing a Root Certificate

Once these issues are resolved, you can proceed to configuring the HTTPS connection.

Configuring JSSE

To Configure JSSE

1. Copy the JSSE .jar files to the JRE_HOME/lib/ext directory.

   jsse.jar, jnet.jar, jcert.jar

2. Statically add the JSSE security provider by adding

   security.provider.n=com.sun.net.ssl.internal.ssl.Provider

   to the JRE_HOME/lib/security/java.security file (where n is the next available priority number for security provider package).

3. If not using JDK1.4, you need to set the following JSSE property using the -D option to the command that launches the client application:

   java.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol

Importing a Root Certificate

If the root certificate of the CA who signed your Web server’s certificate is not in the trust database by default or if you are using a proprietary Web server/application server certificate, you must add that certificate to the trust database. If this is the case, follow the instruction below, otherwise go to Configuring the Connection Factory

Assuming that the certificate is saved in certFile and that trustStoreFile is your key store, run the following command:

JRE_HOME/bin/keytool -import -trustcacerts
 -alias aliasForCertificate -file certFile

-keystore trustStoreFile

Answer YES to the question: Trust this certificate?

You also need to specify the following JSSE properties using the -D option to the command that launches the client application:

javax.net.ssl.trustStore=trustStoreFile
javax.net.ssl.trustStorePassword=trustStorePasswd

Configuring the Connection Factory

To enable HTTPS support, you need to set the connection factory’s imqAddressList attribute to the HTTPS tunnel servlet URL. The general syntax of the HTTPS tunnel servlet URL is the following:

https://hostName:portNumber

/contextRoot/tunnel

where hostName:portNumber is the name and port of the Web server hosting the HTTPS tunnel servlet and contextRoot is a path set when deploying the tunnel servlet on the Web server.

For more information on connection factory attributes in general, and the imqAddressList attribute in particular, see the Message Queue Developer's Guide for Java Clients.

You can set connection factory attributes in one of the following ways:

• Using the -o option to the imqobjmgr command that creates the connection factory administered object (see Adding a Connection Factory), or set the attribute when creating the connection factory administered object using the Administration Console (imqadmin).

• Using the -D option to the command that launches the client application (see the Message Queue Developer's Guide for Java Clients).

• Using an API call to set the attributes of a connection factory after you create it programmatically in client application code (see the Message Queue Developer's Guide for Java Clients).

Using a Single Servlet to Access Multiple Brokers

You do not need to configure multiple Web servers and servlet instances if you are running multiple brokers. You can share a single Web server and HTTPS tunnel servlet instance among concurrently running brokers. If multiple broker instances are sharing a single tunnel servlet, you must configure the imqAddressList connection factory attribute as shown below:

https://hostName:portNumber

/contextRoot/tunnel?ServerName=
bkrHostName:instanceName

Where bkrHostName is the broker instance host name and instanceName is the name of the specific broker instance you want your client to access.

To check that you have entered the correct strings for bkrhostName and instanceName, generate a status report for the HTTPS tunnel servlet by accessing the servlet URL from a browser. The report lists all brokers being accessed by the servlet:

HTTPS tunnel servlet ready.
Servlet Start Time : Thu May 30 01:08:18 PDT 2002
Accepting secured connections from brokers on port : 7674
Total available brokers = 2
Broker List :
   jpgserv:broker2
   cochin:broker1

Using an HTTP Proxy

If you are using an HTTP proxy to access the HTTPS tunnel servlet:

• Set http.proxyHost system property to the proxy server host name.

• Set http.proxyPort system property to the proxy server port number.

You can set these properties using the -D option to the command that launches the client application.