TLS CipherSpecs and CipherSuites in IBM MQ classes for JMS

FIPS compliance

Note: On AIX®, Linux®, and Windows, IBM MQ provides FIPS 140-2 compliance through the IBM Crypto for C (ICC) cryptographic module. The certificate for this module has been moved to the Historical status. Customers should view the IBM Crypto for C (ICC) certificate and be aware of any advice provided by NIST. The FIPS 140-3 cryptographic module within the IBM Semeru SDK was approved by NIST in August 2024. IBM MQ 9.4.2 adds support for the handling of IBM MQ classes for JMS and IBM MQ classes for Java client connections using TLS for FIPS 140-3 in Java 8 and Semeru 11+. The NIST certification associated with the FIPS 140-3 module can be viewed at https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4755. The FIPS 140-2 provider is still the default profile. IBM MQ 9.4.2 does not change the default behavior but does allow you to configure connections with FIPS 140-3.

The IBM MQ Operator 3.2.0 and queue manager container image 9.4.0.0 onwards are based on UBI 9. FIPS 140-3 compliance is currently pending.

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 "Configuring Ciphersuites and FIPS-compliance" section of this topic) only those CipherSuites that 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 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 CipherSuites listed in CipherSpecs supported by IBM MQ and their equivalent CipherSuites.

From IBM MQ 9.4.2, the handling of IBM MQ classes for JMS and IBM MQ classes for Java client connections using TLS for IBM Semeru runtime versions 8.0.8.30, 11.0.24, 17.0.12, and Java 21.0.4 or higher supports the FIPS 140-3 implementation on the following platforms:

• AIX
• Linux for x86-64
• Linux on Power® Systems - Little Endian
• Windows

CipherSpecs supported by IBM MQ and their equivalent CipherSuites

The following table lists the CipherSpecs that IBM MQ supports and their equivalent CipherSuites. The table also indicates the protocol that is used for the communication, and whether or not the CipherSuite conforms to the FIPS 140-2 and FIPS 140-3 standards.

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.

To be able to use TLS 1.3 Ciphers, the JRE running your application must support TLS 1.3.

From Java 11, cipher prefixes are not interchangeable, so the correct SSL_ or TLS_ are required on both the channel and client definition.

Table 1. CipherSpecs supported by IBM MQ and their equivalent CipherSuites

CipherSpec 1	Equivalent CipherSuite (IBM JRE)	Equivalent CipherSuite (Oracle JRE)	Protocol	FIPS 140-2 compatible	FIPS 140-3 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	No
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	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	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	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	Yes
ECDHE_ECDSA_NULL_SHA256	SSL_ECDHE_ECDSA_WITH_NULL_SHA	TLS_ECDHE_ECDSA_WITH_NULL_SHA	TLS 1.2	No	No
ECDHE_ECDSA_RC4_128_SHA256	SSL_ECDHE_ECDSA_WITH_RC4_128_SHA	TLS_ECDHE_ECDSA_WITH_RC4_128_SHA	TLS 1.2	No	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	No
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	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	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	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	Yes
ECDHE_RSA_NULL_SHA256	SSL_ECDHE_RSA_WITH_NULL_SHA	TLS_ECDHE_RSA_WITH_NULL_SHA	TLS 1.2	No	No
ECDHE_RSA_RC4_128_SHA256	SSL_ECDHE_RSA_WITH_RC4_128_SHA	TLS_ECDHE_RSA_WITH_RC4_128_SHA	TLS 1.2	No	No
TLS_RSA_WITH_3DES_EDE_CBC_SHA 2	SSL_RSA_WITH_3DES_EDE_CBC_SHA	TLS_RSA_WITH_3DES_EDE_CBC_SHA	TLS 1.0	No 4	No
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 4	No
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 4	No
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 4	No
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 4	No
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 4	No
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 4	No
TLS_RSA_WITH_DES_CBC_SHA	SSL_RSA_WITH_DES_CBC_SHA	SSL_RSA_WITH_DES_CBC_SHA	TLS 1.0	No	No
TLS_RSA_WITH_NULL_SHA256	SSL_RSA_WITH_NULL_SHA256	TLS_RSA_WITH_NULL_SHA256	TLS 1.2	No	No
TLS_RSA_WITH_RC4_128_SHA256	SSL_RSA_WITH_RC4_128_SHA	SSL_RSA_WITH_RC4_128_SHA	TLS 1.2	No	No
ANY_TLS12	*TLS12	*TLS12	TLS 1.2	Yes	No
TLS_AES_128_GCM_SHA256 3	TLS_AES_128_GCM_SHA256	TLS_AES_128_GCM_SHA256	TLS V1.3	No	Yes
TLS_AES_256_GCM_SHA384 3	TLS_AES_256_GCM_SHA384	TLS_AES_256_GCM_SHA384	TLS V1.3	No	Yes
TLS_CHACHA20_POLY1305_SHA256 3	TLS_CHACHA20_POLY1305_SHA256	TLS_CHACHA20_POLY1305_SHA256	TLS V1.3	No	No
TLS_AES_128_CCM_SHA256 3	TLS_AES_128_CCM_SHA256	TLS_AES_128_CCM_SHA256	TLS V1.3	No	No
TLS_AES_128_CCM_8_SHA256 3	TLS_AES_128_CCM_8_SHA256	TLS_AES_128_CCM_8_SHA256	TLS V1.3	No	No
ANY 3	*ANY	*ANY	Multiple	No	No
ANY_TLS13 3	*TLS13	*TLS13	TLS V13	No	No
ANY_TLS12_OR_HIGHER 3	*TLS12ORHIGHER	*TLS12ORHIGHER	TLS 1.2 and above	No	No
ANY_TLS13_OR_HIGHER 3	*TLS13ORHIGHER	*TLS13ORHIGHER	TLS 1.3 and above	No	No

Configuring Ciphersuites and FIPS compliance in an IBM MQ classes for JMS application

The security provider for FIPS 140-3 is OpenJCEPlusFIPS. You enable the FIPS 140-3 implementation by providing the following Java properties:

-Dsemeru.fips=true -Dsemeru.customprofile=OpenJCEPlusFIPS

This sets the default security provider to be OpenJCEPlusFIPS. Connections need to use a CipherSuite that is supported for the FIPS 140-3 implementation (see CipherSpecs supported by IBM MQ and their equivalent CipherSuites).

Notes:

• You can confirm the version of FIPS that a client connection is using by querying the Java system property com.ibm.fips.mode. This returns either 140-2 or 140-3.
• When migrating to IBM MQ 9.4.2, you will not see any change in behavior of your existing IBM MQ classes for JMS and IBM MQ classes for Java clients. However, if you are migrating FIPS clients from Java 8 to IBM Semeru Java, you will need to make changes to the clients to account for the new Java properties that you must specify to enable the FIPS 140-3 security provider.
• The SSLFIPSREQUIRED property is not supported by IBM Semeru Java and is no longer necessary to create a FIPS certified connection. If a client connects with SSLFIPSREQUIRED set on the connection factory using a Semeru 11+ runtime but the IBM Semeru Java properties are not specified, a JMS SSL configuration exception is thrown. This exception specifies that a FIPS certified connection has been requested with an appropriate security provider available. For more information, see MQJMS Exception Messages.
• From Java 11, support for being able to use the SSL_ and TLS_ prefixes interchangeably in CipherSuites has been removed so the cipher definition must be correctly defined.
• IBM Semeru FIPS 140-3 does not support 32 bit clients. If your 32 bit client cannot be updated, it is possible to override hardcoded connection factory properties by providing an override file.

Configuring your application to use IBM Java or Oracle Java CipherSuite mappings

From IBM MQ 9.4.0, a Cipher can be defined as either the CipherSpec or CipherSuite name and is handled correctly by IBM MQ.

Note: The Java System Property com.ibm.mq.cfg.useIBMCipherMappings, which controlled which mappings were used in earlier versions of IBM MQ, is no longer needed and is removed from the product at IBM MQ 9.4.0.

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.