Setting up Q Replication using a MQ client connection secured with SSL

All of the steps involved are discussed in Chapter 2 of the Redbooks(R) WebSphere MQ V6, WebSphere Message Broker V6 and SSL.

Some additional information and heads-up are given that are unique to work with Q Replication and were encountered during setup.

Pre-requisites:

1. SystemA – location of the MQ Server containing the Q Manager (MYQMGR).

• Connectivity: IP address 192.168.0.10 on port 1414

2. SystemB – location where the Q Replication program (Q Capture or Q Apply) run and the corresponding database is located.

• Connectivity: IP address 192.168.0.11 on port 1414

These steps assume that the Q Replications programs are installed, the MQ client is installed, the Q Replication program is configured and non-client related MQ objects required for Q Replication have been created in MYQMGR.

Chapter 1

1. Create the basic connectivity using MQ client channel definition tables.
2. Verify setup using the MQ sample programs.
3. Verify setup using Q Replication program.

Chapter 2

1. Create the key store and certificate.
2. Enable SSL at the queue manager and channels.
3. Verify setup using the MQ sample programs.
4. Verify setup using Q Replication program.

1.1. Create the basic connectivity using MQ client channel definition tables.

Client channel definition table is a list of channels available to the MQ client to connect to. A client connection is made of two parts, the server connection channel and the client connection channel where a client connection channel map to a queue manager and receiving server connection channel. This channel definition table is a simple file that lists the client connection channels available to the MQ client. There can only be one such file at a time for an MQ client session in use.

The MQCHLLIB and MQCHLTAB environment variables define the location and file name correspondingly.

All channels are defined at the queue manager.

• Settting up the client-server connection channel pair between MYQMGR and MQ client:

MQ script:

# Definition of the server connection channel.

DEFINE CHANNEL (SSL.CLIENT) CHLTYPE(SVRCONN) TRPTYPE(TCP) REPLACE

# Definition of the corresponding client connection channel that points to the connection details of SystemA where the queue manager resides

# Note: the QMNAME is required for Q Replication.

DEFINE CHANNEL (SSL.CLIENT) CHLTYPE(CLNTCONN) CONNAME('192.168.0.10(1414)') TRPTYPE(TCP) QMNAME(MYQMGR) REPLACE

# Create a listener for the port.

DEFINE LISTENER (TCP.LISTENER) TRPTYPE(TCP) CONTROL(QMGR) REPLACE

# Start the listener.

START LISTENER (TCP.LISTENER)

# A local queue used for testing the connectivity.

DEFINE QL (MYQ)

# end script

Run from command line:

runmqsc MYQMGR < MQscript

The client channel definition table is created in the queue manager directory and can be found in MQ_INSTALL_DIR/qmgrs/MYQMGR/@ipcc. The default name is AMQCLCHL.TAB. This files contains our client connection channel.

Copy the file to a location at SystemB, for example $HOME of the Q Replication user.

Set MQCHLLIB to $HOME, e.g.

export MQCHLLIB=$HOME

Set MQCHLTAB to the file name of the client channel definition table, e.g.

export MQCHLTAB= AMQCLCHL.TAB

Note: Later in the document it is assumed all MQ objects required for Q replication are also defined on queue manager MYQMGR.

1.2 Verify client connection using MQ sample programs

The client is ready to connect. Go to MQ_INSTALL_DIR/samp/bin. It contains a number of sample programs. Two of the programs are of interest: amqsputc and amqsgetc. These programs load the MQ client libraries and connect to the queue manager.

Run:

amqsputc MYQ MYQMGR

Write something to the queue (Ctrl-c exists).

Then run (Ctrl-c exits):

amqsgetc MYQ MYQMGR

The contents written in amqsputc should be written.

Troubleshoot:

MQRC 2058: something is wrong with the setup. Verify the MQCHLLIB and MQCHLTAB settings as well as check if the listener is running. This error code is also returned if no QMNAME was specified in the client connection channel definition as we started the programs with an explicit queue manager name.

1.3 Verify client connection using Q Replication program (here Q Capture)

Note: It is assumed the MQ objects required for Q replciation were successfully created in queue manager MYQMGR. The program and queue being used to verify connectivity is the Q Capture program and the restart queue (named RESTARTQ) respectively.

Set ASNUSEMQCLIENT environment variable, i.e.

export ASNUSEMQCLIENT=true

This tells the Q Replication program to dynamically load the MQ client libraries. Otherwise, Q Capture will not start correctly and stop again.

Upon startup the restart message in the restart queue is created. Use asnqmfmt to retrieve the message from the restart queue:

asnqmfmt RESTARTQ MYQMGR

asnqmfmt also uses the MQ client libraries as set by ASNUSEMQCLIENT

This concludes chapter 1. In the next chapter the key store for the MQ server and client is created and the channels are changed to be encrypted.

Chapter 2

2.1 Setting up the keystore

Follow the instructions provided in the redbook WebSphere MQ V6, WebSphere Message Broker V6, and SSL section 2.4.1

The database key type MUST be CMS.

If you cannot see CMS in the Key "database type" drop down field, java.security file of your JAVA installation does not have the CMSProvider set up. Exit the IBM Key management program.

How to set up your JAVA installation to provide CMS key store capability:

When creating the CMS key store it could be that the CMSProvider is missing from the java.security file in the java JRE that is being used.

• assume $JAVA_HOME points to the install of the JRE/SDK that runs the java VM

• java.security is in $JAVA_HOME/jre/lib/security

• add the CMS provider com.ibm.security.cmskeystore.CMSProvider to the list:

  • e.g. security.provider.10=com.ibm.security.cmskeystore.CMSProvider

Start the IBM Key management program (strmqikm) again and try to create the CMS key repository.

2.1.1 setting up the self signed certificate

Follow the instructions in section 2.4.2.

Use as keylabel “ibmwebspheremqmyqmgr”.

2.1.2 setting up the certificate on the systemB

Follow instructions provided in the redbook in section 2.4.3

2.2 Setting up the encryption on the client and server connection channels where the server authenticates the client connection (one way authentication).

As encryption the example chooses TRIPLE_DES_SHA_US but any supported encryption can be chosen instead.

Verify that the queue manager MYQMGR uses the correct key repository by running:

runmqsq < “DISPLAY QMGR MYQMGR"

The output should point to the key repository created in step 2.1. If not correct alter the queue manager to point to the key repository:

ALTER QMGR SSLKEYR('install_directory/qmgrs/MYQMGR/ssl/key')

do not add the .kdb extension!

e.g. DISPLAY QMGR SSLKEYR results in

QMNAME(MYQMGR)

SSLKEYR(/var/mqm/qmgrs/MYQMGR/ssl/key)

MQ script to configure the client and server channels with SSL on systemA:

#set encryption method for the server channel

alter chl (SSL.CLIENT) chltype(SVRCONN) sslciph(TRIPLE_DES_SHA_US) sslcauth(OPTIONAL)

#sslcauth(optional) is chosen because only server authentication it set up.

#set encryption method for the client connection channel – must be identical to server encryption channel

alter chl (SSL.CLIENT) chltype(CLNTCONN) sslciph(TRIPLE_DES_SHA_US)

#end script

This script updates the AMQCLCHL.TAB file in the MQ_INSTALL_DIR/qmgrs/MYMQMGR/@ipcc directory. Copy the file to systemB and replace the existing AMQCLCHL.TAB with the new client channel definitions.

Before testing remember to check the MQCHLLIB, MQCHLTAB and MQSSLKEYR environment variables. MQSSLKEYR was introduced in 2.3 and points to the key repository file. Note: the filename is included in the path information but the “.kdb” extension is left out.

2.3 Verify the connection using the MQ sample programs

Again use the MQ sample programs amqsputc and amqsgetc to verify the connection as shown in step 1.2.

If the queue manager does not use the right key store the amqsputc call fails with:

$ amqsputc Q1 MYQMGR

Sample AMQSPUT0 start

MQCONN ended with reason code 2538 – MQRC_HOST_NOT_AVAILABLE

2.4 Verify client connection using Q Replication program (here Q Capture)

Then clear the RESTARTQ and start Q Capture on systemB in cold start mode (this generates a new restart message for verification that Q Capture has started correctly). Remember to have the environment variables MQCHLTAB, MQCHLLIB, MQSSLKEYR and ASNUSEMQCLIENT set to the appropriate values.

See step 1.3

Optiona/Addon

To setup of two-way authentication, where the client authenticates itself at the server is described in section 2.5 in the rebook. The steps are identical, except that the self signed certificate is created and exported from the client and then imported in to the queue managers key repository. In addition, the server connections SSLCAUTH option is set to REQUIRED.

Additional usage notes

After performing the steps above, you will have encryption of the data on the SSL channels but additional steps remain outstanding if the objective is to implement a secure system. A few examples include:

• Lock down or authenticate all of the other inbound channels on the queue manager, including SYSTEM.DEF.* and SYSTEM.AUTO.* channels. Otherwise, a malicious user will bypass the SSL channels and gain administrative access to the QMgr which would allow them to see the messages in plaintext (among other nefarious activities).
• Set SSLPEER on the channel. Otherwise anyone with a valid certificate can use that channel.
• Delete the unused certificate authorities from any keystores created.

A comprehensive discussion of WebSphere MQ security is beyond the scope of this Wiki article. To get started, download the latest version of the Hardening WMQ Security presentation and/or WMQ Security Hands-On Lab class materials from the IMPACT conference at https://t-rob.net/links.