CipherSpec support for the managed .NET client

The CipherSpec settings for an application are used during the handshake with the server.

IBM® MQ clients allow you to set a CipherSpec value that is used during the handshake with the queue manager. IBM MQ clients should set a valid CipherSpec for secured connection to establish, preferably the CipherSpec specified in the Windows group policy. Leaving this field blank indicates a plain-text channel without any security on the sockets.

For the IBM MQ.NET managed client, the TLS settings are for the Microsoft.NET SSLStream class. For SSLStream, a CipherSpec, or a preference list of CipherSpecs, can be set only in the Windows group policy, which is a computer-wide setting. SSLStream then uses the specified CipherSpec or preference list during the handshake with the server. In case of other IBM MQ clients, the CipherSpec property can be set in the application on the IBM MQ channel definition and the same setting is used for TLS negotiation. As a result of this restriction, the TLS handshake might negotiate any supported CipherSpec regardless of what is specified in the IBM MQ channel configuration. Therefore, it is likely that this will result in error AMQ9631 on the queue manager. To avoid this error, set the same CipherSpec as the one that you have set in the application as the TLS configuration in the Windows group policy.

The new IBM MQ.NET TLS client code checks only that the correct protocol version was negotiated. The TLS protocol version is derived from the CipherSpec that the application sets and is used for the TLS handshake with the server (queue manager). Hence it is required by design to set the CipherSpec in the IBM MQ.NET managed client application. If the CipherSpec set by the IBM MQ client is anything other than the one from the SSL 3.0, TLS 1.0 and TLS 1.2 protocols, the IBM MQ managed .NET client would negotiate by default with any of the ciphers from SSL 3.0 or TLS 1.0 protocols and it would not report an error.

Note: If the CipherSpec value supplied by the application is not a CipherSpec known to IBM MQ, then the IBM MQ managed .NET client disregards it and negotiates the connection based on the Windows system's group policy.

Setting a CipherSpec

There are three ways of setting a CipherSpec:

MQEnvironment .NET class

The following example shows how to set a CipherSpec with the MQEnvironment class.


MQEnvironment.SSLKeyRepository = "*USER";
MQEnvironment.ConnectionName = connectionName;
MQEnvironment.Channel = channelName;
MQEnvironment.properties.Add(MQC.TRANSPORT_PROPERTY, MQC.TRANSPORT_MQSERIES_MANAGED);
MQEnvironment.SSLCipherSpec = "TLS_RSA_WITH_AES_128_CBC_SHA";

TLS CipherSpec property

The following example shows how to set a CipherSpec by adding a hashtable parameter into the MQQueueManager constructor.


properties = new Hashtable();
properties.Add(MQC.TRANSPORT_PROPERTY, MQC.TRANSPORT_MQSERIES_MANAGED);
properties.Add(MQC.HOST_NAME_PROPERTY, hostName);
properties.Add(MQC.PORT_PROPERTY, port);
properties.Add(MQC.CHANNEL_PROPERTY, channelName);
properties.Add(MQC.SSL_CERT_STORE_PROPERTY, sslKeyRepository);
properties.Add(MQC.SSL_CIPHER_SPEC_PROPERTY, cipherSpec);
properties.Add(MQC.SSL_PEER_NAME_PROPERTY, sslPeerName);
properties.Add(MQC.SSL_RESET_COUNT_PROPERTY, keyResetCount);
queueManager = new MQQueueManager(queueManagerName, properties);

Windows group policy

When a CipherSpec is set on the Windows group policy, the same CipherSpec must be set for the SSLCipherSpec property value on the SVRCONN channel and in the application. If the Windows group policy is set to the default, that is the group policy is not enabled/edited for CipherSpec setting, applications must set the same default value of the CipherSpec from the Windows group policy TLS configuration in the MQEnvironment class or in the MQQueueManager constructor hashtable properties.

CCDT usage

IBM MQ.NET only supports Client Channel Definition Tables (.TAB files) that are on a local computer. Existing CCDT files that have a CipherSpec value set can be used for IBM MQ.NET connections. However, the CipherSpec value set on the client connection channel determines the TLS protocol version and also must match the CipherSpec set in the Windows group policy.