IBM® MQ for HPE NonStop 'How to' Series Part 1 - Sharing a TLS Certificate Key Repository with Multiple Queue Managers

While MQ on Windows and Linux use a CMS keystore file usually called key.kdb, as their TLS key repository, MQ on HPE NonStop uses a different method; the TLS key repository for MQ on HPE NonStop is an OSS directory that contains TLS certificates and other TLS-related files. For HPE NonStop, each MQ queue manager normally has its own TLS directory into which these files are placed.

However, there are often advantages to placing the collection of TLS certificates needed by all queue managers in a single shared OSS directory, rather than a separate directory for each queue manager. When many queue managers are using TLS channels, using one directory for these important files can make management of TLS certificates easier, and it may reduce the risk of mistakes that can lead to channel connection problems.

In this post, we show how to setup a single shared directory for TLS certificates. We do this by taking advantage of two MQSC attributes called SSLKEYR and CERTLABL on the QMGR object, and also the CERTLABL attribute on each channel definition. Before getting into the details, let’s review what CERTLABL and SSLKEYR really mean.

Channel CERTLABL

The CERTLABL attribute of a channel specifies the label of the TLS certificate and stash file to be used by the channel. So, a channel with a CERTLABL(‘MYLABEL’) configured, will use the following certificate and stash files when making TLS connections:

   MYLABEL.pem
   MYLABEL.sth

A channel’s CERTLABL attribute is initially blank, which means that the channel will use the queue manager’s CERTLABL value.

QMGR CERTLABL

The QMGR object also carries a CERTLABL attribute. The queue manager’s CERTLABL attribute specifies the default label to be used by channels that do not have their own CERTLABL configured.

When a queue manager is created, its QMGR CERTLABL attribute is set to a blank value, which means that the queue manager will use the default certificate. Note that the default certificate is always contained in a file called cert.pem along with its corresponding Stash.sth stash file.

QMGR SSLKEYR

On the QMGR object, SSLKEYR defines the OSS location of the queue manager’s TLS key repository. For MQ on HPE NonStop this is a directory containing certificates and other TLS-related files needed by the queue manager. Its default value is the queue manager’s “ssl” directory, like so:

   $MQINST/var/mqm/qmgrs/QMGR/ssl

The queue manager’s channels will search this directory to find their certificates and private keys, its trusted CA certificates and their necessary stash files.

Setting up a shared TLS key repository

Now that we understand the meaning of the SSLKEYR and CERTLABL attributes, it is not difficult to establish a single directory where certificates for all queue managers can be located and used.

Here’s an example of doing this for the two sample MQ queue managers called ALICE and BOB, but the method is easily extended to include more queue managers.

The recipe described here uses the MQ ssl sample environment. This sample script (called setup.sh in the samp/ssl directory) will create the queue managers, channels and certificates needed to establish a working TLS channel pair.

Create the sample MQ TLS queue managers and their certificates

1. cd $MQINST/opt/mqm/samp/ssl
2. ./setup.sh

The setup.sh script will create 2 new queue managers called ALICE and BOB and will also create certificates and channels for them.

Caution: setup.sh will delete and recreate existing queue managers called ALICE and BOB.

Confirm that the ALICE.TO.BOB and the BOB.TO.ALICE channels will connect and start.

Create a shared TLS key repository directory

Create this directory somewhere convenient that is not inside any MQ installation. Since this directory will contain private keys and stash files, make sure to put strong controls on who can access it.

1. Login to OSS as the MQ installation owner MQM.
2. Create a shared key repository directory and ensure that its permissions are carefully set.
      mkdir /home/mqm/mqkdb
      chmod 700 /home/mqm/mqkdb
3. Copy all sample TLS material in ALICE’s ssl directory and BOB’s ssl directory into your new shared TLS directory:
      cp $MQINST/var/mqm/qmgrs/ALICE/ssl/* /home/mqm/mqkdb/
      cp $MQINST/var/mqm/qmgrs/BOB/ssl/* /home/mqm/mqkdb/
4. Ensure that all files in the new TLS directory have strong access controls.
      chmod 600 /home/mqm/mqkdb/*

Configure both queue managers to use the new shared TLS key repository

The final step is to tell the ALICE and BOB queue managers to use the new shared TLS directory containing your certificates.

1. runmqsc ALICE
      alter qmgr sslkeyr(‘/home/mqm/mqkdb’)
2. runmqsc BOB
      alter qmgr sslkeyr(‘/home/mqm/mqkdb’)

Confirm that the sample TLS channels will connect and start

Start the ALICE.TO.BOB and BOB.TO.ALICE channels and confirm they are running.

1. runmqsc ALICE
      start chl(ALICE.TO.BOB)
      dis chs(*)
2. runmqsc BOB
      start chl(BOB.TO.ALICE)
      dis chs(*)

Thoughts

Some things to consider before you attempt to do this with your own queue managers:

• The trust.pem file contains the CA certificates needed by the queue manager. When using a shared, common, TLS directory the trust.pem file must contain all of the CA certificates for all of the queue managers that are sharing that TLS directory.
• Be careful: When both ends of the channel (i.e. both the sender and its receiver) are using the same shared TLS directory, it is easy to inadvertently arrange both ends of the channel to use the same certificate. Depending on how your certificates are generated, the channel may start anyway. Nevertheless, using the same certificate for the client and server role of a TLS connection is not good practice and it should be avoided.
• With this in mind, it is usually better for all queue managers that are sharing a TLS directory, to have a specific unique CERTLABL configured for them. The example above is intended to be minimal and simple and it does not follow this advice. The ALICE.TO.BOB channel is using the same default certificate for both its sender and receiver. It is easy to not notice this because the channel does start. A good exercise for the reader is to revise the example above, so that it assigns a unique CERTLABL to each queue manager to avoid the same-certificate problem.
• While centrally locating your certificates and keys in a shared TLS repository can offer easier certificate management it is also true that a mistake might affect channels in more than one queue manager. This should be given careful thought before using this method in production MQ deployments.

Contact:

For more information on IBM MQ for HPE NonStop, please contact:

Gerhard Lehnhoff
Director Business Unit IBM at comforte 
g.lehnhoff@comforte.com