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 we 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.
Set 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 Cipher Suite list is configured via the Windows group policy management console, the SVRCONN channel definition must specify a matching CipherSpec. A matching CipherSpec could either be a generic value such as "ANY_TLS12_OR_HIGHER", or a specific value that maps to the highest Cipher Suite that would be negotiated from the ordered list. The use of generic CipherSpec values is recommended for use with .NET clients as it avoids needing to change the SVRCONN CipherSpec configuration if the order of the client list changes.
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.
Parent topic: TLS support for the managed .NET client
Related concepts
Related information