TLS CipherSpecs and CipherSuites in IBM MQ classes for Java
The ability of IBM MQ classes for Java 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.
We 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.
Important: The CipherSuites listed are those supported by the IBM Java Runtime Environment (JRE) supplied with IBM MQ. The CipherSuites that are listed include those supported by the Oracle Java JRE. For more information about configuring the application to use an Oracle Java JRE, see Configure the application to use IBM Java or Oracle Java CipherSuite mappings.The table also indicates the protocol that is used for the communication, and whether or not the CipherSuite conforms to the FIPS 140-2 standard.
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.
Note: Each JRE can have multiple cryptographic security providers, each of which can contribute an implementation of the same CipherSuite. However, not all security providers are FIPS 140-2 certified. If FIPS 140-2 compliance is not enforced for an application then it is possible that an uncertified implementation of the CipherSuite might be used. Uncertified implementations might not operate in compliance with FIPS 140-2, even if the CipherSuite theoretically meets the minimum security level required by the standard. See the following notes for more information about configuring FIPS 140-2 enforcement in IBM MQ Java applications.For more information about FIPS 140-2 and Suite-B compliance for CipherSpecs and CipherSuites, see Specify CipherSpecs. We might also need to be aware of information that concerns US Federal Information Processing Standards.
To use the full set of CipherSuites and to operate with certified FIPS 140-2 and/or Suite-B compliance, a suitable JRE is required. IBM Java 7 Service Refresh 4 Fix Pack 2 or a higher level of IBM JRE provides the appropriate support for the TLS 1.2 CipherSuites listed in Table 1.To be able to use TLS v1.3 Ciphers the JRE running the application must support TLS v1.3.
Note: To use some CipherSuites, the 'unrestricted' policy files need to be configured in the JRE. For more details of how policy files are set up in an SDK or JRE, see the IBM SDK Policy files topic in the Security Reference for IBM SDK, Java Technology Edition for the version we are using.| 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 | yes |
| TLS_RSA_WITH_AES_128_CBC_SHA | SSL_RSA_WITH_AES_128_CBC_SHA | TLS_RSA_WITH_AES_128_CBC_SHA | TLS 1.0 | yes |
| TLS_RSA_WITH_AES_128_CBC_SHA256 | SSL_RSA_WITH_AES_128_CBC_SHA256 | TLS_RSA_WITH_AES_128_CBC_SHA256 | TLS 1.2 | yes |
| TLS_RSA_WITH_AES_128_GCM_SHA256 | SSL_RSA_WITH_AES_128_GCM_SHA256 | TLS_RSA_WITH_AES_128_GCM_SHA256 | TLS 1.2 | yes |
| TLS_RSA_WITH_AES_256_CBC_SHA | SSL_RSA_WITH_AES_256_CBC_SHA | TLS_RSA_WITH_AES_256_CBC_SHA | TLS 1.0 | yes |
| TLS_RSA_WITH_AES_256_CBC_SHA256 | SSL_RSA_WITH_AES_256_CBC_SHA256 | TLS_RSA_WITH_AES_256_CBC_SHA256 | TLS 1.2 | yes |
| TLS_RSA_WITH_AES_256_GCM_SHA384 | SSL_RSA_WITH_AES_256_GCM_SHA384 | TLS_RSA_WITH_AES_256_GCM_SHA384 | TLS 1.2 | yes |
| 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 |
| 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, we 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 JRE running the application must support TLS v1.3
Configure Ciphersuites and FIPS-compliance in an IBM MQ classes for Java application
- An application that uses IBM MQ classes for Java can use either
of two methods to set the CipherSuite for a connection:
- Set the sslCipherSuite field in the MQEnvironment class to the CipherSuite name.
- Set the property CMQC.SSL_CIPHER_SUITE_PROPERTY in the properties hashtable passed to the MQQueueManager constructor to the CipherSuite name.
- An application that uses IBM MQ classes for Java can use either of two methods to enforce FIPS 140-2 compliance:
- Set the sslFipsRequired field to true in the MQEnvironment class.
- Set the property CMQC.SSL_FIPS_REQUIRED_PROPERTYin the properties hash table passed to the MQQueueManager constructor to true.
Configure the application to use IBM Java or Oracle Java CipherSuite mappings
We can configure whether the application uses the default IBM Java CipherSuite to IBM MQ CipherSpec mappings, or the Oracle CipherSuite to IBM MQ CipherSpec mappings. Therefore, we can use TLS CipherSuites whether the application uses an IBM JRE or an Oracle JRE. The Java System Property 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 posts MQ Java, TLS Ciphers, Non-IBM JREs & APARs IT06775, IV66840, IT09423, IT10837, and The relationship between MQ CipherSpecs and Java Cipher Suites.
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, we need to either avoid using triple DES, or enable secret key reset when using this CipherSpec.
Parent topic: Transport Layer Security (TLS) support in IBM MQ classes for Java