Enabling TLS in IBM MQ classes for Java

To enable TLS, you specify a CipherSuite. There are two ways of specifying a CipherSuite.

TLS is supported only for client connections. To enable TLS, you must specify the CipherSuite to use when communicating with the queue manager, and this CipherSuite must match the CipherSpec set on the target channel. Additionally, the named CipherSuite must be supported by your JSSE provider. However, CipherSuites are distinct from CipherSpecs and so have different names. TLS CipherSpecs and CipherSuites in IBM MQ classes for Java contains a table mapping the CipherSpecs supported by IBM MQ to their equivalent CipherSuites as known to JSSE.

To enable TLS, specify the CipherSuite using the sslCipherSuite static member variable of MQEnvironment. The following example attaches to an SVRCONN channel named SECURE.SVRCONN.CHANNEL, which has been set up to require TLS with a CipherSpec of TLS_RSA_WITH_AES_128_CBC_SHA256:


MQEnvironment.hostname       = "your_hostname";
MQEnvironment.channel        = "SECURE.SVRCONN.CHANNEL";
MQEnvironment.sslCipherSuite = "SSL_RSA_WITH_AES_128_CBC_SHA256";
MQQueueManager qmgr = new MQQueueManager("your_Q_manager");

Although the channel has a CipherSpec of TLS_RSA_WITH_AES_128_CBC_SHA256, the Java application must specify a CipherSuite of SSL_RSA_WITH_AES_128_CBC_SHA256. See TLS CipherSpecs and CipherSuites in IBM MQ classes for Java for a list of mappings between CipherSpecs and CipherSuites.

An application can also specify a CipherSuite by setting the environment property CMQC.SSL_CIPHER_SUITE_PROPERTY.

Alternatively, use the Client Channel Definition Table (CCDT). For more information, see Using a client channel definition table with IBM MQ classes for Java

If you require a client connection to use a CipherSuite that is supported by the IBM Java JSSE FIPS provider (IBMJSSEFIPS), an application can set the sslFipsRequired field in the MQEnvironment class to true. Alternatively, the application can set the environment property CMQC.SSL_FIPS_REQUIRED_PROPERTY. The default value is false, which means that a client connection can use any CipherSuite that is supported by IBM MQ.

If an application uses more than one client connection, the value of the sslFipsRequired field that is used when the application creates the first client connection determines the value that is used when the application creates any subsequent client connection. Therefore when the application creates a subsequent client connection, the value of the sslFipsRequired field is ignored. You must restart the application if you want to use a different value for the sslFipsRequired field.

To connect successfully using TLS, the JSSE truststore must be set up with certificate authority root certificates from which the certificate presented by the queue manager can be authenticated. Similarly, if SSLClientAuth on the SVRCONN channel has been set to MQSSL_CLIENT_AUTH_REQUIRED, the JSSE keystore must contain an identifying certificate that is trusted by the queue manager.