TLS CipherSpecs and CipherSuites in IBM MQ classes for JMS
The ability of IBM® MQ classes for JMS applications to establish connections to a queue manager, depends on the CipherSpec specified at the server end of the MQI channel and the CipherSuite specified at the client end.
The following table lists the CipherSpecs supported by IBM MQ and their equivalent CipherSuites.
You should review the topic Deprecated CipherSpecs to see if any of the CipherSpecs, listed in the following table, have been deprecated by IBM MQ and, if so, at which update the CipherSpec was deprecated.
Ciphersuites denoted as FIPS 140-2 compliant can be used if the application has not been configured to enforce FIPS 140-2 compliance, but if FIPS 140-2 compliance has been configured for the application (see the following notes on configuration) only those CipherSuites which are marked as FIPS 140-2 compatible can be configured; attempting to use other CipherSuites results in an error.
For more information about FIPS 140-2 and Suite-B compliance for CipherSpecs and CipherSuites, see Specifying CipherSpecs. You might also need to be aware of information that concerns US Federal Information Processing Standards.
To be able to use TLS v1.3 Ciphers the JRE running your application must support TLS v1.3.
CipherSpec | Equivalent CipherSuite (IBM JRE) | Equivalent CipherSuite (Oracle JRE) | Protocol | FIPS 140-2 compatible |
---|---|---|---|---|
ECDHE_ECDSA_3DES_EDE_CBC_SHA256 | SSL_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA | TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA | TLS 1.2 | yes |
ECDHE_ECDSA_AES_128_CBC_SHA256 | SSL_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | TLS 1.2 | yes |
ECDHE_ECDSA_AES_128_GCM_SHA256 | SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | TLS 1.2 | yes |
ECDHE_ECDSA_AES_256_CBC_SHA384 | SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | TLS 1.2 | yes |
ECDHE_ECDSA_AES_256_GCM_SHA384 | SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | TLS 1.2 | yes |
ECDHE_ECDSA_NULL_SHA256 | SSL_ECDHE_ECDSA_WITH_NULL_SHA | TLS_ECDHE_ECDSA_WITH_NULL_SHA | TLS 1.2 | no |
ECDHE_ECDSA_RC4_128_SHA256 | SSL_ECDHE_ECDSA_WITH_RC4_128_SHA | TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | TLS 1.2 | no |
ECDHE_RSA_3DES_EDE_CBC_SHA256 | SSL_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | TLS 1.2 | yes |
ECDHE_RSA_AES_128_CBC_SHA256 | SSL_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | TLS 1.2 | yes |
ECDHE_RSA_AES_128_GCM_SHA256 | SSL_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | TLS 1.2 | yes |
ECDHE_RSA_AES_256_CBC_SHA384 | SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | TLS 1.2 | yes |
ECDHE_RSA_AES_256_GCM_SHA384 | SSL_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | TLS 1.2 | yes |
ECDHE_RSA_NULL_SHA256 | SSL_ECDHE_RSA_WITH_NULL_SHA | TLS_ECDHE_RSA_WITH_NULL_SHA | TLS 1.2 | no |
ECDHE_RSA_RC4_128_SHA256 | SSL_ECDHE_RSA_WITH_RC4_128_SHA | TLS_ECDHE_RSA_WITH_RC4_128_SHA | TLS 1.2 | no |
TLS_RSA_WITH_3DES_EDE_CBC_SHA 1 | SSL_RSA_WITH_3DES_EDE_CBC_SHA | TLS_RSA_WITH_3DES_EDE_CBC_SHA | TLS 1.0 | no 3 |
TLS_RSA_WITH_AES_128_CBC_SHA | SSL_RSA_WITH_AES_128_CBC_SHA | TLS_RSA_WITH_AES_128_CBC_SHA | TLS 1.0 | no 3 |
TLS_RSA_WITH_AES_128_CBC_SHA256 | SSL_RSA_WITH_AES_128_CBC_SHA256 | TLS_RSA_WITH_AES_128_CBC_SHA256 | TLS 1.2 | no 3 |
TLS_RSA_WITH_AES_128_GCM_SHA256 | SSL_RSA_WITH_AES_128_GCM_SHA256 | TLS_RSA_WITH_AES_128_GCM_SHA256 | TLS 1.2 | no 3 |
TLS_RSA_WITH_AES_256_CBC_SHA | SSL_RSA_WITH_AES_256_CBC_SHA | TLS_RSA_WITH_AES_256_CBC_SHA | TLS 1.0 | no 3 |
TLS_RSA_WITH_AES_256_CBC_SHA256 | SSL_RSA_WITH_AES_256_CBC_SHA256 | TLS_RSA_WITH_AES_256_CBC_SHA256 | TLS 1.2 | no 3 |
TLS_RSA_WITH_AES_256_GCM_SHA384 | SSL_RSA_WITH_AES_256_GCM_SHA384 | TLS_RSA_WITH_AES_256_GCM_SHA384 | TLS 1.2 | no 3 |
TLS_RSA_WITH_DES_CBC_SHA | SSL_RSA_WITH_DES_CBC_SHA | SSL_RSA_WITH_DES_CBC_SHA | TLS 1.0 | no |
TLS_RSA_WITH_NULL_SHA256 | SSL_RSA_WITH_NULL_SHA256 | TLS_RSA_WITH_NULL_SHA256 | TLS 1.2 | no |
TLS_RSA_WITH_RC4_128_SHA256 | SSL_RSA_WITH_RC4_128_SHA | SSL_RSA_WITH_RC4_128_SHA | TLS 1.2 | no |
ANY_TLS12 | *TLS12 | *TLS12 | TLS 1.2 | yes |
TLS_AES_128_GCM_SHA256 2 | TLS_AES_128_GCM_SHA256 | TLS_AES_128_GCM_SHA256 | TLS V1.3 | no |
TLS_AES_256_GCM_SHA384 2 | TLS_AES_256_GCM_SHA384 | TLS_AES_256_GCM_SHA384 | TLS V1.3 | no |
TLS_CHACHA20_POLY1305_SHA256 2 | TLS_CHACHA20_POLY1305_SHA256 | TLS_CHACHA20_POLY1305_SHA256 | TLS V1.3 | no |
TLS_AES_128_CCM_SHA256 2 | TLS_AES_128_CCM_SHA256 | TLS_AES_128_CCM_SHA256 | TLS V1.3 | no |
TLS_AES_128_CCM_8_SHA256 2 | TLS_AES_128_CCM_8_SHA256 | TLS_AES_128_CCM_8_SHA256 | TLS V1.3 | no |
ANY 2 | *ANY | *ANY | Multiple | no |
ANY_TLS13 2 | *TLS13 | *TLS13 | TLS V13 | no |
ANY_TLS12_OR_HIGHER 2 | *TLS12ORHIGHER | *TLS12ORHIGHER | TLS V1.2 and above | no |
ANY_TLS13_OR_HIGHER 2 | *TLS13ORHIGHER | *TLS13ORHIGHER | TLS V1.3 and above | no |
- CipherSpec TLS_RSA_WITH_3DES_EDE_CBC_SHA is deprecated. However, it can still be used to transfer up to 32 GB of data before the connection is terminated with error AMQ9288. To avoid this error, you need to either avoid using triple DES, or enable secret key reset when using this CipherSpec.
- To be able to use TLS v1.3 Ciphers, the Java runtime environment (JRE) running your application must support TLS v1.3.
- From IBM MQ 9.2.0 Fix Pack 25, the IBM Java 8 JRE removes support for RSA key exchange when operating in FIPS mode.
Configuring Ciphersuites and FIPS-compliance in an IBM MQ classes for JMS application
- An application that uses IBM MQ classes for JMS can use either
of two methods to set the CipherSuite for a connection:
- Call the setSSLCipherSuite method of a ConnectionFactory object.
- Use the IBM MQ JMS administration tool to set the SSLCIPHERSUITE property of a ConnectionFactory object.
- An application that uses IBM MQ classes for JMS can use either of two methods to enforce FIPS 140-2 compliance:
- Call the setSSLFipsRequired method of a ConnectionFactory object.
- Use the IBM MQ JMS administration tool to set the SSLFIPSREQUIRED property of a ConnectionFactory object.
Configuring your application to use IBM Java or Oracle Java CipherSuite mappings
com.ibm.mq.cfg.useIBMCipherMappings
controls which mappings are used. The property
can be one of the following values: - true
- Use the IBM Java CipherSuite to IBM MQ CipherSpec mappings.
- false
- Use the Oracle CipherSuite to IBM MQ CipherSpec mappings.
For more information about using IBM MQ Java and TLS Ciphers, see the MQdev blog post MQ Java, TLS Ciphers, Non-IBM JREs & APARs IT06775, IV66840, IT09423, IT10837.
Interoperability limitations
Certain CipherSuites might be compatible with more than one IBM MQ CipherSpec, depending on the protocol in use. However, only the CipherSuite/CipherSpec combination that uses the TLS version specified in Table 1 is supported. Attempting to use the unsupported combinations of CipherSuites and CipherSpecs will fail with an appropriate exception. Installations using any of these CipherSuite/CipherSpec combinations should move to a supported combination.
The following table shows the CipherSuites to which this limitation applies.
CipherSuite | Supported TLS CipherSpec | Unsupported SSL CipherSpec |
---|---|---|
SSL_RSA_WITH_3DES_EDE_CBC_SHA | TLS_RSA_WITH_3DES_EDE_CBC_SHA 1 | TRIPLE_DES_SHA_US |
SSL_RSA_WITH_DES_CBC_SHA | TLS_RSA_WITH_DES_CBC_SHA | DES_SHA_EXPORT |
SSL_RSA_WITH_RC4_128_SHA | TLS_RSA_WITH_RC4_128_SHA256 | RC4_SHA_US |
- This CipherSpec TLS_RSA_WITH_3DES_EDE_CBC_SHA is deprecated. However, it can still be used to transfer up to 32 GB of data before the connection is terminated with error AMQ9288. To avoid this error, you need to either avoid using triple DES, or enable secret key reset when using this CipherSpec.