Here is a minimalist cookbook for getting SSL working with XMS .NET client when communicating with WebSphere MQ*. Comments and suggestions are very welcome!

* Understanding of basic JMS and XMS concepts is assumed in this cookbook. For further information about JMS, see ‘Using Java’ book and for further information about XMS see ‘Message Service Clients for C/C++ and .NET’ book shipped with XMS.

Meta Notes

  • Currently, MQ SSL only applies to the unmanaged client*. This functionality is not available for the fully managed client (which is the default). This functionality is not applicable for the bindings mode, as there is no network communication in bindings.
  • The following only applies to MQ v6, as v5.3 has a different SSL story, at-least for Windows, I think.

So, in source code we must do the following:

myConnectionFactory.SetIntProperty(XMSC.WMQ_CONNECTION_MODE, XMSC.WMQ_CM_CLIENT_UNMANAGED);

* XMS .NET for WebSphere MQ delegates the security to lower layer of ‘MQ classes for .NET’. ‘MQ classes for .NET’ supports three connection modes – unmanaged client, fully managed client and bindings. XMS .NET transparently allows a selection between these three connection modes thru the XMSC.WMQ_CONNECTION_MODE property on a ConnectionFactory. For further information about these modes, see ‘Using .NET’ book. However, in a nutshell: unmanaged client is .NET wrapper with underlying C library, fully managed client is 100% pure .NET and bindings is (by definition) unmanaged, since it does IPC with the queue manager processes. (client modes communicate over network, bindings mode does IPC).

MQ configuration

a) Create new channel

Create a new channel, for example, named ‘SECURE.SVRCONN’ with SSL settings set to some CipherSpec, for example ‘RC4_MD5_US’.

Advanced option (do it later, if needed) – No need to restrict to matching on distinguished name.

Leave ‘Authentication…’ to be ‘Required’ – means two way authentication.

(‘Optional’ means one way authentication (client needs to know about qmgr’s certificate)).

No other non-default options needed on the channel.

b) Create two keystores – one for the queue manager and one for the client.

Use ‘IBM Key Management’ tool from WebSphere MQ folder in start menu (Java GUI – iKeyman in GSKit, wrapped by MQ tool strmqikm.exe).

Create new ‘Key Database File’, type ‘CMS’.

For queue manager keystore, this should be <WMQ-install-dir>\Qmgrs\<QMGR> \ssl\, for example C:\wmq6\Qmgrs\QM_thinkpad\ssl\

For client side keystore, this could be any folder on the disk, for example ‘D:\vs-workspace\ssl’

Password for keystore should be some non-null value. I set it to be ‘cms’ and this works. Any other value should also work.

Expiration is optional.

You must select to stash the password.

If you see the ‘Signer Certificates’ view with couple of known and trusted certificates, then you have successfully created a keystore.

c) Create a self-signed certificate in qmgr’s keystore, ‘Extract’ it to disk, ‘Add’ it in client’s keystore

Open qmgr’s keystore

Create -> New self-signed certificate

Key label must be ‘ibmwebspheremq<qmgr>’ – all in lower case, no spaces, (without quotes) for example, ‘ibmwebspheremqqm_thinkpad’.

Enter values for three non-optional fields – Common Name (For example – Saket), Organization (For example – IBM), Country (For example – GB).

The new certificate is added and classed as ‘Personal Certificate’.

‘Extract’ it to disk, using either format, anywhere on disk.

Open client’s keystore

In the ‘Signer Certificates’ view, ‘Add’ a certificate. Select the recently created certificate on disk. Use the same label as used before, i.e., ‘ibmwebspheremqqm_thinkpad’.

Done

d) Create a self-signed certificate in client’s keystore, ‘Extract’ it to disk, ‘Add’ it in qmgr’s keystore

Do as before – create a new self-signed certificate in client’s keystore, extract it to disk, and ‘Add’ it to qmgr’s keystore.

Use key label to be ‘ibmwebspheremq<logged-on-userid>’ – all in lower case, no spaces, (without quotes), for example, ‘ibmwebspheremqadministrator’.

Client configuration

We need two/three additional properties on the connection factory on top of the usual ones.

Set channel to be the new channel

Following two SSL props are mandatory:

Set string property XMSC_WMQ_SSL_CIPHER_SPEC to be “RC4_MD5_US”, for example
Set string property XMSC_WMQ_SSL_KEY_REPOSITORY to be @”D:\vs-workspace\ssl\key”, for example

This assumes a physical file “D:\vs-workspace\ssl\key.kdb” exists (with extension). The property is set without the extension.

(@ denotes no escape char interpolation in C# and saves escaping \)

Other XMSC_WMQ_SSL_* properties can be used for advanced functionality.

In source code:

myConnectionFactory.SetStringProperty(XMSC.WMQ_SSL_CIPHER_SPEC, “RC4_MD5_US”);
myConnectionFactory.SetStringProperty(XMSC.WMQ_SSL_KEY_REPOSITORY, @”D:\vs-workspace\ssl\key”);

Further notes

JMS

If using JMS clients, additional configuration is needed; for further information checkout the dW article by Alex Fehners.

Refresh security

If we change any SSL settings on the queue manager, channel, key stores (QM-side or client-side), then we should issue refresh security command using runmqsc or restart the QM or reboot the machine.

Command:

refresh security type(ssl)

or
More generally,

refresh security

For example:

D:vs-workspace>runmqsc
5724-H72 (C) Copyright IBM Corp. 1994, 2004.  ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM_thinkpad.

refresh security type(ssl)
     1 : refresh security type(ssl)
AMQ8560: WebSphere MQ security cache refreshed.
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed.

Finally

Note: XMS .NET for WebSphere MQ delegates the security to lower layer of ‘MQ classes for .NET’, so reading the ‘Using .NET’ book and ‘WebSphere MQ Security’ book is highly recommended for finer details.

Caution: Given that you’re interested in security, you should study the finer details about it and not rely on this minimalist cookbook to provide you with a thorough solution. This should hopefully get you started in the right direction.

Advertisements