SSL configuration of the Websphere MQ Java/JMS client


This article shows you how to configure an Secure Sockets Layer (SSL) connection from a Java™/JMS client to an IBM® WebSphere® MQ Queue Manager. It covers the creation of test certificates but does not cover any MQ configuration information. It is purely a Java/JMS client guide and requires an IBM SDK.

Steps 1, 3, and 4 below are required to configure an SSL connection. Do Step 2 only if you wish to configure client authentication. To reduce complexity and simplify debugging of any potential problems, I recommend that you not use client authentication initially. After you have a basic SSL connection, you can move up to client authentication.

If you experience configuration problems, it may help to specify the debug flag:

1. Create trustStore

As its name suggests, the trustStore holds the certificate of a signing CA for a Queue Manager you trust. What this means in terms of the Java/JMS client is that when a connection is made to a Queue Manager, it will send its certificate to us as part of the initial SSL handshake. The JSSE, which handles all SSL communication, will look in the trustStore to validate the certificate it has just been sent. If it cannot validate the certificate, the connection will be terminated.

To create a trustStore and import a certificate, you can use the IBM Key Management tool, which is part of Websphere MQ V6:

  1. In the start bar, select Programs => IBM Websphere MQ => IBM Key Management.
  2. When IBM Key Management starts, click New and set the following values:
    Key database type
    File name
    Location of your choice
  3. Click OK to continue.
    Figure 1
    Set values
    Set values
  4. You will now be prompted to enter a password of your choice. The password is required to open the trustStore only if you wish to add certificates to it. The JSSE does not require a password if it is only being used as a trustStore. For this example, enter a password.
  5. Click OK to continue. You should now have a trustStore in which you can import certificates of trusted CAs.
  6. Select the drop-down box under the label Key database content.
  7. Select Signer Certificates.
    Figure 2
    Select Signer Certificates
    Select Signer Certificates
  8. Click Add. You will be prompted for the location of the certificate you wish to add. This certificate will either be the Queue Managers certificate if you are using self-sign certificates for testing, or the certificate of the CA, which issued your Queue Managers certificate. For information on configuring the Queue Manager for SSL, see the MQ Security manual, Chapter 13.
  9. Enter the following data:
    Data type
    Binary DER data
    Certificate file name
    <name of Queue Manager certificate>
    <location of the certificate>
  10. Click OK. You will be prompted for a label, which should be in the form <ibmwebspheremq<qmname lowercase>.
  11. Click OK to add the certificate.

2. Create keyStore

Complete this section only if you wish to have client authentication when a connection is made to a Queue Manager. If client authentication has not been specified on the channel, you do not need to complete this section.

The keyStore is essentially the same as a trustStore, except that it holds the client's personal certificate, and the JSSE requires a password for access. You can in fact add your personal certificate to the trustStore created earlier and it will act as both trustStore and keyStore, but the password that was not required before will now need to be passed to the JSSE in order for it to access your personal certificate.

To create a KeyStore, follow the steps in Section 1, replacing trustStore with keyStore, up to the point of adding a CAs certificate. At that point, complete these steps:

  1. Select the drop-down box under the label Key database content.
  2. Select Personal Certificates:
    Figure 3
    Select Personal Certificates
    Select Personal Certificates
  3. Click New Self-Signed. This will create a test certificate for yourself.
  4. If you already have a certificate issued to you, click Receive to add it:
    Figure 4

    Unlike creating a Queue Manager personal Certificate, there is no restriction on the Key Label that must be used.

  5. Enter the details as shown above.
  6. Click OK to finish.

The last part of setting up the keyStore is to add your certificate or your CAs certificate to the Queue Managers key repository, so that when the client sends its certificate, the Queue Manager can validate it. Here is how to extract your certificate from the keyStore so that you can add it to the Queue Managers key repository:

  1. Select the drop-down box under the label Key database content.
  2. Select Personal Certificates.
  3. Select your certificate.
  4. Click Extract Certificate.
    Figure 5
    Click Extract Certificate
    Click Extract Certificate
  5. Enter name for certificate.
  6. Specify a location.
  7. Click OK to finish.

Once you have completed this task, all you need to do is to add it to your Queue Managers repository.

3. Assign trustStore and keyStore to application

You can pass the location of the trustStore and KeyStore to the JSSE using either system properties set within the application, or the -D flag on the command line. To set them within the application, use the code below. The location of the trustStore and the keyStore can point to the same file:

         System.setProperty("","<location of trustStore>");
         System.setProperty("","<location of keyStore>");

To use the the -D flag:

java<location of trustStore><location of keyStore><password><app>

4. Configure CipherSuite

The Channel you wish to connect to should have a CipherSpec defined. Within the Java/JMS application a CipherSuite needs to be specified that matches the CipherSpec. The following table will help you do this:

CipherSpecs and CipherSuites
CipherSpec CipherSuite

You can specify the CipherSuite in a number of places.

If you are using the MQ Java Client, you can specify the String in MQEnvironment.SSLCipherSuite:

MQEnvironment.sslCipherSuite = "SSL_RSA_WITH_NULL_MD5";

You can also pass the String within a Hashtable using the key MQC.SSL_CIPHER_SUITE_PROPERTY to the QueueManager constructor or the Hashtable:, "SSL_RSA_WITH_NULL_MD5");


Hashtable properties = new Hashtable();
MQQueueManager myQM = new MQQueueManager("MyQMgr", properties);

If you are using the MQ JMS client, you can set the CipherSuite on the connection factory using the setSSLCipherSuite() method:

MQConnectionFactory factory = new MQConnectionFactory();
MQConnection connection = factory.createConnection();


This article has shown you how to:

  • Create a TrustStore and import the Queue Managers certificate into it.
  • Create a KeyStore in which to hold the test certificate you have created.
  • Assign these to your application and configure the Websphere MQ JMS client to use them.

Downloadable resources

Related topics

  • WebSphere MQ V7 information center
    A single Web portal to all WebSphere MQ V7 documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere MQ V7.
  • WebSphere MQ developer resources page
    Technical resources to help you design, develop, and deploy messaging middleware with WebSphere MQ to integrate applications, Web services, and transactions on almost any platform.
  • WebSphere MQ product page
    Product descriptions, product news, training information, support information, trial download, and more.
  • WebSphere MQ product family
    A description of the ten or so different editions of WebSphere MQ.
  • WebSphere MQ documentation library
    WebSphere MQ information centers and product manuals.
  • IBM Redbook: WebSphere MQ V7 features and enhancements
    Describes the fundamental concepts and benefits of message queuing technology, describes the new features in V7, and provides a business scenario that shows those features in action.
  • Search for MQ SupportPacs
    Downloadable code, documentation, and performance reports for WebSphere MQ products. The majority of SupportPacs are available at no charge, while others can be purchased as fee-based services from IBM.


Sign in or register to add and subscribe to comments.

Zone=Java development, Middleware
ArticleTitle=SSL configuration of the Websphere MQ Java/JMS client