Niklas Tech Blog

Time for another IBM MQ example. This time it is for connecting to IBM MQ with a Java client over SSL. I’m going to use self-signed certificates in this example to eliminate any certificate chain problems. The source code for the Java client can be found below. Time to start creating the user to use for this

A. Create a new user that the client can use to connect with. Let’s call him “bob”
* Bob needs to be created on OS level since this is what IBM MQ uses to authorise users
* Bob should NOT be a member of the mqm group since it would make him a privileged user (and privileged users are blocked by default)
* Bob does not need login privileges on OS level (/sbin/nologin)

B. Now we need to grant this user some basic privileges
I am here going to use the setmqaut program but you can also use MQExplorer if you like a GUI more

setmqaut -m MYQM01 -t qmgr -p bob -all +connect +inq
setmqaut -m MYQM01 -t queue -n MYQUEUE -p bob -all +put +get

Connect and inquiry for the queue manager and get and put on our example queue.

C. Time to create the client certificate and place it into a jks
For this I am going to use the ikeycmd program shipped with MQ (<mqserver installation dir>/java/jre64/jre/bin/ikeycmd)
Create client database

ikeycmd -keydb -create -db "client.jks" -pw clientpass -type jks  

Create client certificate

ikeycmd -cert -create -db "client.jks" -pw clientpass -label ibmwebspheremqbob -dn "CN=bob,OU=bob,O=Bobs Company,C=SE" -expire 365  

One thing to note here is the label for the client certificate. This has to be in the form of: ‘ibmwebspheremq’ + ‘client username’ (all lower case)
In our case ‘ibmwebspheremqbob’ since our user is called Bob

To check that the certificate is in the jks

ikeycmd -cert -list -db "client.jks" -pw clientpass 

This will give you the label of the certificates in the jks. In our case: ‘ibmwebpsheremqbob’

D. Let us create the server certificate now
Create server database

ikeycmd -keydb -create -db "/var/mqm/qmgrs/MYQM01/ssl/MYQM01.kdb" -pw serverpass -type cms -expire 1000 -stash  

Create server certificate

ikeycmd -cert -create -db "/var/mqm/qmgrs/MYQM01/ssl/MYQM01.kdb" -pw serverpass -label ibmwebspheremqmyqm01 -dn "CN=MYQM01,OU=ICC,O=GU,C=SE" -expire 1000 -sig_alg SHA256_WITH_RSA  

A word about the certificate label here. Default name for this certificate is in the form of: ‘ibmwebspheremq’ + ‘queue manager name’ (all lower case)
In our case this becomes: ‘ibmwebpsheremqmyqm01’

If you need to change the label (or want to be able to present different certificates on different channels) you can set the CERTLABL property on the queue manager (or channel). The CERTLABL label should then correspond to the label in the .kbd file

To check that the certificate is in the kbd

ikeycmd -cert -list -db "/var/mqm/qmgrs/MYQM01/ssl/MYQM01.kdb" -pw serverpass  

This will give you the label of the certificates in the kbd. In our case: ‘ibmwebpsheremqmyqm01’

E. Time for the certificate exchange between client and server
Extract the public part of the client certificate

ikeycmd -cert -extract -db "client.jks" -pw clientpass -label ibmwebspheremqbob -target client.crt -format ascii  

Add the client cert to the server

ikeycmd -cert -add -db "/var/mqm/qmgrs/MYQM01/ssl/MYQM01.kdb" -pw serverpass -label ibmwebspheremqbob -file client.crt -format ascii  

Check so that both certificates are in the kbd

ikeycmd -cert -list -db "/var/mqm/qmgrs/MYQM01/ssl/MYQM01.kdb" -pw serverpass  

This should yield the result:

ibmwebspheremqbob
ibmwebspheremqmyqm01

F. and now from the server to the client
Extract the public part of the server certificate

ikeycmd -cert -extract -db "/var/mqm/qmgrs/MYQM01/ssl/MYQM01.kdb" -pw serverpass -label ibmwebspheremqmyqm01 -target MYQM01.crt -format ascii  

Add the server certificate to the client jks

ikeycmd -cert -add -db "client.jks" -pw clientpass -label ibmwebspheremqmyqm01 -file MYQM01.crt -format ascii  

Check so that both certificates are in the jks

ikeycmd -cert -list -db "client.jks" -pw clientpass  

This should now yield the result:

ibmwebspheremqmyqm01
ibmwebspheremqbob

Certificates are now done. Time to setup the MQ objects. For this I’m going to use the runmqsc program, eq. runmqsc MYQM01
G. Queue manager needs to know where the kdb file is

ALTER QMGR SSLKEYR('/var/mqm/qmgrs/MYQM01/ssl/MYQM01')  

NOTE: We omit the ‘.kbd’ when setting the path in the queue manager

Another thing we are going to do is to set FIPS to false in this example

 
ALTER QMGR SSLFIPS(NO)  

H. There is also need for a server connection channel for the client to connect to

DEFINE CHANNEL('CLIENTS') CHLTYPE(SVRCONN) TRPTYPE(TCP) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256) MCAUSER('bob') SSLCAUTH(REQUIRED) REPLACE  

A few words on SSLCIPH and SSLCAUTH. SSLCIPH is the encryption cipher to use. This cipher has to exist both on the MQ server and in the Java installation that the client runs on.
SSLCAUTH(REQUIRED) tells MQ that the client also should present a certificate when connecting, so called two-way certificate exchange.

I. When all MQ objects have been created/changed we need to refresh the SSL cache in MQ

REFRESH SECURITY TYPE(SSL)  

J. Time to test our setup with a little bit of java code
——————————————–
JAVA EXAMPLE CLIENT CODE
——————————————–

import java.io.IOException;
import java.util.Hashtable;

import com.ibm.mq.*;
import com.ibm.mq.constants.MQConstants;


public class MQClients {
    static private String CHANNEL = "CLIENTS";
    static private int    PORT = 1414;
    static private String HOST = "mymqhost.se";
    static private String QMANAGER = "MYQM01";
    static private String QUEUE = "MYQUEUE";
    static private String USER = "bob";
    static private Hashtable<String, Object> props = 
                                       new Hashtable<String, Object>();
    static MQQueueManager qMgr = null;

    static private void putMsgOnQueue(String message) {
        // Disabling IBM cipher suite mapping due to 
        // using Oracle Java and not IBM Java
        System.setProperty("com.ibm.mq.cfg.useIBMCipherMappings", "false");
        // Enabling SSL debug to view the communication
        //System.setProperty("javax.net.debug", "ssl:handshake");

        System.setProperty("javax.net.ssl.trustStore","client.jks");
        System.setProperty("javax.net.ssl.trustStorePassword","clientpass");
        System.setProperty("javax.net.ssl.keyStore","client.jks");
        System.setProperty("javax.net.ssl.keyStorePassword","clientpass");

        props.put(MQConstants.CHANNEL_PROPERTY, CHANNEL);
        props.put(MQConstants.PORT_PROPERTY, PORT);
        props.put(MQConstants.HOST_NAME_PROPERTY, HOST);
        props.put(MQConstants.USER_ID_PROPERTY, USER);
        props.put(MQConstants.PASSWORD_PROPERTY, "secret"); // Bobs OS password
        props.put(MQConstants.SSL_CIPHER_SUITE_PROPERTY, 
                                 "TLS_RSA_WITH_AES_128_CBC_SHA256");

        try {
            qMgr = new MQQueueManager(QMANAGER, props);

            // MQOO_OUTPUT = Open the queue to put messages 
            // MQOO_INPUT_AS_Q_DEF = Using queue-defined defaults
            int openOptions = MQConstants.MQOO_OUTPUT;

            // creating destination
            MQQueue queue = qMgr.accessQueue(QUEUE, openOptions);

            // specify the message options...
            MQPutMessageOptions pmo = new MQPutMessageOptions(); // Default

            // MQPMO_ASYNC_RESPONSE = MQPUT operation is completed without the 
            // application waiting for the queue manager to complete the call
            // Using this option can improve messaging performance, 
            // particularly for applications using client bindings.
            pmo.options = MQConstants.MQPMO_ASYNC_RESPONSE;

            // create message
            MQMessage mqMessage = new MQMessage();

            System.out.println("Writing message to queue: " + QUEUE);
            mqMessage.writeString(message);

            // Put message on queue
            queue.put(mqMessage, pmo);

            // Close queue
            queue.close();

            // Get status
            MQAsyncStatus asyncStatus = qMgr.getAsyncStatus();

            // Print status code (0 = successful)
            System.out.println(asyncStatus.reasonCode);

        } catch (MQException e) {
            System.out.println("The connection to MQ could not be 
                                established." + e.getMessage());

        } catch (IOException e) {
            System.out.println("Error while writing message." + 
                                e.getMessage());
        } finally {
            try {
                qMgr.disconnect();
            } catch (MQException e) {
                System.out.println("The connection could not be closed." + 
                                    e.getMessage());
            }
        }
    }

    static private void getMsgsFromQueue(){
        // Disabling IBM cipher suite mapping due to 
        // using Oracle Java and not IBM Java
        System.setProperty("com.ibm.mq.cfg.useIBMCipherMappings", "false");
        // Enabling SSL debug to view the communication
        //System.setProperty("javax.net.debug", "ssl:handshake");

        System.setProperty("javax.net.ssl.trustStore","client.jks");
        System.setProperty("javax.net.ssl.trustStorePassword","clientpass");
        System.setProperty("javax.net.ssl.keyStore","client.jks");
        System.setProperty("javax.net.ssl.keyStorePassword","clientpass");

        props.put(MQConstants.CHANNEL_PROPERTY, CHANNEL);
        props.put(MQConstants.PORT_PROPERTY, PORT);
        props.put(MQConstants.HOST_NAME_PROPERTY, HOST);
        props.put(MQConstants.USER_ID_PROPERTY, USER);
        props.put(MQConstants.PASSWORD_PROPERTY, "secret"); // Bobs OS password
        props.put(MQConstants.SSL_CIPHER_SUITE_PROPERTY, 
                                 "TLS_RSA_WITH_AES_128_CBC_SHA256");

        try {
            qMgr = new MQQueueManager(QMANAGER, props);

            // MQOO_INPUT_SHARED = Open the queue to read messages
            int openOptions = MQConstants.MQOO_INPUT_SHARED;

            // creating destination
            MQQueue queue = qMgr.accessQueue(QUEUE, openOptions);

            // specify the message options...
            MQGetMessageOptions gmo = new MQGetMessageOptions(); // Default
            gmo.options = MQConstants.MQPMO_ASYNC_RESPONSE;

            // create message
            MQMessage mqMessage = new MQMessage();

            // Get message from queue
            System.out.println("Fetching message from queue: " + QUEUE);
            queue.get(mqMessage, gmo);

            // Get a message from MQMessage
            String message = 
                 mqMessage.readStringOfByteLength(mqMessage.getMessageLength());

            // Display message
            System.out.println(message);

            // Close queue
            queue.close();

            // Get status
            MQAsyncStatus asyncStatus = qMgr.getAsyncStatus();

            // Print status code (0 = successful)
            System.out.println(asyncStatus.reasonCode);

        } catch (MQException e) {
            System.out.println("The connection to MQ could not be 
                                established." + e.getMessage());

        } catch (IOException e) {
            System.out.println("Error while fetching the message." + 
                                e.getMessage());
        } finally {
            try {
                qMgr.disconnect();
            } catch (MQException e) {
                System.out.println("The connection could not be closed." + 
                                    e.getMessage());
            }
        }
    }

    public static void main(String[] args) {
    
        putMsgOnQueue("world");
        getMsgsFromQueue();
    }
}

NOTE: The SSL_CIPHER_SUITE_PROPERTY in the client must be the same cipher that is defined on the channel SSLCIPH property.

A few troubleshooting tips

* IBM MQ and Java does not always agree on naming so the cipher you choose in MQ might have another name in Oracle/Sun/IBM Java - be sure to check the cipher name translation table on IBM site before giving up 

* The error logs for the queue manager can be found in /var/mqm/qmanagers/MYQM01/errors

* Make sure the GSKit is installed in your MQ installation. If not you are in the risk of getting strange errors like "MQRC_UNSUPPORTED_CIPHER_SUITE" even though they are correct

* To enable SSL verbose logging uncomment the line System.setProperty("javax.net.debug", "ssl:handshake") in the example code above

Tested on IBM MQ 9.0.5.0 on Red Hat 7, client using Java version 1.8.0_141 and IBM com.ibm.mq.allclients v9.0.4.0 on OSX 10.13.6