MQ

This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

Digital Certificates have labels, sometimes called friendly names, used to refer to them rather than using the X.509 Distinguished Name which is a bit more of a mouthful.

When IBM MQ first made use of digital certificates with its support for the SSL protocol on channels in V5.3, the certificates had to use a specific label, one of:

• ibmwebspheremqqmgr-name or qsg-name
• ibmwebspheremqlogged-on-userid

depending on whether the channel in question was at the queue manager end of things or the client end of things.

Things remained the same until IBM MQ V8 when the Certificate Label attribute was introduced. It allowed you to give your certificate any label you desired, perhaps to follow your own business security policies, and then to tell MQ the label it should look for. The defaults, if you did not change anything remained as they were before.

While it was obvious and easy to use for referencing the Certificate to be used by the queue manager:

ALTER QMGR CERTLABL('MQG1QMgrCertificate')

I have learned, from discussions with MQ users, that it is not so obvious that you can also use them on the client side of things. So that is the subject of today's post.

In my opinion, avoiding the mandated MQ labels is much more useful on the client side of things where the certificate you might want to refer to, could have been issued to you, the person, for use in a multitude of different environments, not just for MQ purposes, and having to use a label specific to MQ might be awkward.

Also you might have situations where one certificate store might have to contain several certificates that you might use to connect to different queue managers, or with different applications, and being able to keep them all together but with different labels makes life much easier.

Let's look at how you can tell the MQ client exactly which certificate you want to use.

As with a number of MQ Client configuration items there are several possible ways to configure it (programmatically through MQCONNX, using an environment variable, or through the mqclient.ini file). As you may know from reading previous blog posts I have written, I favour the mqclient.ini file approach as it keeps everything together. Read my earlier blog post for why I consider the use of the mqclient.ini file as best practice.

So imagine you have an MQ application that you wish to use with a TLS connection, but it does not provide anywhere in the application to configure everything that you need. Perhaps it was originally written prior to IBM MQ V8, and has not been updated to know about certificate labels. How could you take that application and have it connect using TLS and a certificate label? Let's use the ubiquitous amqsputc sample as our example. It does not take any TLS parameters, so everything must be set up outside the application.

Let's assume that we have already set up our certificate with a label MQAdminProd in a KDB file MQGemClient.kdb.

We also need a CCDT file with our channel definition so that we can, at the very least, provide an SSLCIPH value.

With these things available, which are amply described elsewhere in tutorials (for example here) so I won't repeat, we are ready to create an mqclient.ini file to pulls everything together.

What I like to do is to create a working directory for my application and put all the relevant things in there. Then whenever I run the application, I first ensure that I am in this directory and the MQ Client will preferentially look there first for an mqclient.ini file.

mkdir TLS_amqsputc

cd TLS_amqsputc

Now create a file called mqclient.ini with contents like the following, change the locations of things to refer to your named files as appropriate.

#***********************************************************************#
#* Simple mqclient.ini file to define what is needed for a TLS         *#
#* connection to my queue manager.                                     *#
#***********************************************************************#
CHANNELS:
  ChannelDefinitionDirectory=.
  ChannelDefinitionFile=MQGEM.TAB

SSL:
  SSLKeyRepository=C:\MQGem\MQGemClient.kdb
  CertificateLabel=MQAdminProd

A few interesting things to note.

• I have set the ChannelDefinitionDirectory to a single dot, which refers to the same place as the location of the mqclient.ini file. This is helpful if you ever need to move/change the directory, then you haven't hard coded the directory name in the contents of the file. Of course, if it is not in the same directory as your mqclient.ini file, you will need to be specific about its location (as I have done with my KDB file).
• In older versions of IBM MQ, you did not supply the file extension of the SSLKeyRepository. in modern versions, you can supply the extension if you want, as I have done above. If you omit it, it is assumed to be a .kdb file. However, these days it might instead be a .p12 file.

Having put this in place, and making sure I am in the same directory as the mqclient.ini file, I can run my application program, e.g.

amqsputc Q1 MQG1

and while it sits and waits for me to enter some message data, a quick view of my channel status proves it is running over TLS:-

DISPLAY CHSTATUS(*) SSLPEER RAPPLTAG RPRODUCT SECPROT

AMQ8417I: Display Channel Status details.
   CHANNEL(MQGEM.SVRCONN.TLS)              CHLTYPE(SVRCONN)
   CONNAME(127.0.0.1)                      CURRENT
   RAPPLTAG(:\mqm9340\bin64\amqsputc.exe)
   SECPROT(TLSV12)
   SSLPEER(SERIALNUMBER=47:3D:F7:E1:85:2C:BF:99,CN=Morag Hughson,OU=Prod,O=MQGem Software)
   STATUS(RUNNING)                         SUBSTATE(RECEIVE)
   RPRODUCT(MQCC)

Changing into the appropriate directory is handy if you are testing various different environments, and need an easy way to switch things around. This is likely why I prefer this mode. It is certainly useful when setting things up too. However, once you get things working, you may prefer to have a shortcut set up that always just works. This could be achieved by using the MQCLNTCF environment variable which can be set to point to the location of the mqclient.ini file. This is detailed in IBM Docs here.

I hope that makes it clear how easy it is to use a Certificate Label for the client side of things too, but please do ask questions in the comments if you need any more details.

#Little-Gem
#IBMMQ
#IBMChampion