CipherSpec order in TLS handshake

The order of CipherSpecs is used when choosing between multiple possible CipherSpecs, for example when using one of the ANY* CipherSpecs.

During a TLS handshake, a client and server exchange the CipherSpecs and protocols that they support in order of their preference. A common CipherSpec that both sides prioritize is chosen and used for the TLS communication. When choosing a CipherSpec protocol, version is also considered, for example if a server lists TLS 1.2 CipherSpecs before TLS 1.3 CipherSpecs it will still prioritize TLS 1.3 so long as the client can support it and has a common TLS 1.3 CipherSpec that can be used.

From IBM® MQ 9.2.0, when IBM MQ is configured for TLS it sets the CipherSpecs into the order shown in the following table, from most preferred to least preferred.

Note: If a CipherSpec is not enabled through the AllowedCipherSpecs attribute, it will not be configured for use during a TLS Handshake.

In the case that the AllowedCipherSpecs attribute is not specified, a default list of enabled ciphers, indicated by the following table, is used.

Table 1. CipherSpecs order from IBM MQ 9.2.0
Platform	CipherSpec	Protocol	Hexadecimal code	Enabled by default
All	TLS_CHACHA20_POLY1305_SHA256	TLS 1.3	1303	Yes
All	TLS_AES_256_GCM_SHA384	TLS 1.3	1302	Yes
All	TLS_AES_128_GCM_SHA256	TLS 1.3	1301	Yes
	TLS_AES_128_CCM_SHA256	TLS 1.3	1304	Yes
	TLS_AES_128_CCM_8_SHA256	TLS 1.3	1305	Yes
All	TLS_RSA_WITH_AES_256_GCM_SHA384	TLS 1.2	009D	Yes
	ECDHE_ECDSA_AES_256_GCM_SHA384	TLS 1.2	C02C	Yes
All	ECDHE_RSA_AES_256_GCM_SHA384	TLS 1.2	C030	Yes
All	TLS_RSA_WITH_AES_256_CBC_SHA256	TLS 1.2	003D	Yes
All	ECDHE_ECDSA_AES_256_CBC_SHA384	TLS 1.2	C024	Yes
All	ECDHE_RSA_AES_256_CBC_SHA384	TLS 1.2	C028	Yes
All	TLS_RSA_WITH_AES_128_GCM_SHA256	TLS 1.2	009C	Yes
	ECDHE_ECDSA_AES_128_GCM_SHA256	TLS 1.2	C02B	Yes
All	ECDHE_RSA_AES_128_GCM_SHA256	TLS 1.2	C02F	Yes
All	TLS_RSA_WITH_AES_128_CBC_SHA256	TLS 1.2	003C	Yes
All	ECDHE_ECDSA_AES_128_CBC_SHA256	TLS 1.2	C023	Yes
All	ECDHE_RSA_AES_128_CBC_SHA256	TLS 1.2	C027	Yes
	ECDHE_ECDSA_3DES_EDE_CBC_SHA256	TLS 1.2	C008	No
	ECDHE_RSA_3DES_EDE_CBC_SHA256	TLS 1.2	C012	No
	TLS_RSA_WITH_RC4_128_SHA256	TLS 1.2	0005	No
	ECDHE_ECDSA_RC4_128_SHA256	TLS 1.2	C007	No
	ECDHE_RSA_RC4_128_SHA256	TLS 1.2	C011	No
All	TLS_RSA_WITH_NULL_SHA256	TLS 1.2	003B	No
	ECDHE_ECDSA_NULL_SHA256	TLS 1.2	C006	No
	ECDHE_RSA_NULL_SHA256	TLS 1.2	C010	No
	TLS_RSA_WITH_NULL_NULL	TLS 1.2	0000	No
	TLS_RSA_WITH_AES_256_CBC_SHA	TLS 1.0	0035	No
	TLS_RSA_WITH_AES_128_CBC_SHA	TLS 1.0	002F	No
	AES_SHA_US	TLS 1.0	002E	No
All	TLS_RSA_WITH_3DES_EDE_CBC_SHA	TLS 1.0	000A	No
All	TLS_RSA_WITH_RC4_128_SHA	TLS 1.0	0005	No
	TLS_RSA_WITH_RC4_128_MD5	TLS 1.0	0004	No
All	TLS_RSA_WITH_DES_CBC_SHA	TLS 1.0	0009	No
	TLS_RSA_EXPORT_WITH_RC4_40_MD5	TLS 1.0	0003	No
	TLS_RSA_EXPORT_WITH_RC2_40_MD5	TLS 1.0	0006	No
	TLS_RSA_WITH_NULL_SHA	TLS 1.0	0002	No
	TLS_RSA_WITH_NULL_MD5	TLS 1.0	0001	No
All	TRIPLE_DES_SHA_US	SSL v3	000A	No
All	RC4_SHA_US	SSL v3	0005	No
All	RC4_MD5_US	SSL v3	0004	No
All	DES_SHA_EXPORT	SSL v3	0009	No
All	RC4_MD5_EXPORT	SSL v3	0003	No
All	RC2_MD5_EXPORT	SSL v3	0006	No
All	NULL_SHA	SSL v3	0002	No
All	NULL_MD5	SSL v3	0001	No
	FIPS_WITH_3DES_EDE_CBC_SHA	SSL v3	FEFF	No
	RC4_56_SHA_EXPORT1024	SSL v3	0064	No
	DES_SHA_EXPORT1024	SSL v3	0062	No
	FIPS_WITH_DES_CBC_SHA	SSL v3	FEFE	No

This list was constructed by ordering the protocols with the default list supplied by the cryptographic library used by IBM MQ on z/OS® and is consistent across z/OS and distributed platforms.

Changing the order

If a different order is desired, then a new order of CipherSpecs can be supplied using the AllowedCipherSpecs attribute of the SSL stanza on IBM MQ for Multiplatforms [z/OS]

, or the TransportSecurity stanza on IBM MQ for z/OS, with the following rules:

Higher protocol versions are always used, regardless of their position in the list.
Any disabled CipherSpecs are re-enabled if supplied in the list.
The TLS server's list order has a higher priority than the TLS client.
When TLS 1.3 is enabled, certain CipherSpecs are not supported.

For example, on IBM MQ for Multiplatforms, if the following is configured on the queue manager:

SSL:
AllowedCipherSpecs=TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_CBC_SHA

and on IBM MQ for z/OS, if the following is configured on the queue manager:

TransportSecurity:
AllowedCipherSpecs=TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_CBC_SHA

then:

A client connecting with ANY_TLS12 will likely use the TLS 1.2 CipherSpec TLS_RSA_WITH_AES_128_GCM_SHA256.
A client connecting with ANY_TLS12_OR_HIGHER will likely use the TLS 1.3 CipherSpec TLS_AES_128_GCM_SHA256 (assuming the client supports TLS 1.3).
A client connecting with the TLS 1.0 CipherSpec TLS_RSA_WITH_AES_256_CBC_SHA will use that CipherSpec.

Previous versions of IBM MQ

Before IBM MQ 9.2.0, the following order of CipherSpecs was used:

Table 2. CipherSpecs order before IBM MQ 9.2.0
Platform	CipherSpec	Protocol	Enabled by default
	TLS_RSA_WITH_AES_128_CBC_SHA	TLS 1.0	No
	AES_SHA_US	TLS 1.0	No
	TLS_RSA_WITH_AES_256_CBC_SHA	TLS 1.0	No
All	RC4_SHA_US	SSL v3	No
All	TLS_RSA_WITH_RC4_128_SHA	TLS 1.0	No
All	RC4_MD5_US	SSL v3	No
	TLS_RSA_WITH_RC4_128_MD5	TLS 1.0	No
All	TRIPLE_DES_SHA_US	SSL v3	No
All	TLS_RSA_WITH_3DES_EDE_CBC_SHA	TLS 1.0	No
	DES_SHA_EXPORT1024	SSL v3	No
All	RC4_56_SHA_EXPORT1024	SSL v3	No
All	RC4_MD5_EXPORT	SSL v3	No
	TLS_RSA_EXPORT_WITH_RC4_40_MD5	TLS 1.0	No
All	RC2_MD5_EXPORT	SSL v3	No
	TLS_RSA_EXPORT_WITH_RC2_40_MD5	TLS 1.0	No
All	DES_SHA_EXPORT	SSL v3	No
All	TLS_RSA_WITH_DES_CBC_SHA	TLS 1.0	No
All	NULL_SHA	SSL v3	No
	TLS_RSA_WITH_NULL_SHA	TLS 1.0	No
All	NULL_MD5	SSL v3	No
	TLS_RSA_WITH_NULL_MD5	TLS 1.0	No
	FIPS_WITH_DES_CBC_SHA	SSL v3	No
	FIPS_WITH_3DES_EDE_CBC_SHA	SSL v3	No
All	TLS_RSA_WITH_AES_128_CBC_SHA256	TLS 1.2	Yes
All	TLS_RSA_WITH_AES_256_CBC_SHA256	TLS 1.2	Yes
All	TLS_RSA_WITH_NULL_SHA256	TLS 1.2	No
All	TLS_RSA_WITH_AES_128_GCM_SHA256	TLS 1.2	Yes
All	TLS_RSA_WITH_AES_256_GCM_SHA384	TLS 1.2	Yes
	ECDHE_ECDSA_RC4_128_SHA256	TLS 1.2	No
	ECDHE_ECDSA_3DES_EDE_CBC_SHA256	TLS 1.2	No
	ECDHE_RSA_RC4_128_SHA256	TLS 1.2	No
	ECDHE_RSA_3DES_EDE_CBC_SHA256	TLS 1.2	No
All	ECDHE_ECDSA_AES_128_CBC_SHA256	TLS 1.2	Yes
All	ECDHE_ECDSA_AES_256_CBC_SHA384	TLS 1.2	Yes
All	ECDHE_RSA_AES_128_CBC_SHA256	TLS 1.2	Yes
All	ECDHE_RSA_AES_256_CBC_SHA384	TLS 1.2	Yes
	ECDHE_ECDSA_AES_128_GCM_SHA256	TLS 1.2	Yes
	ECDHE_ECDSA_AES_256_GCM_SHA384	TLS 1.2	Yes
All	ECDHE_RSA_AES_128_GCM_SHA256	TLS 1.2	Yes
All	ECDHE_RSA_AES_256_GCM_SHA384	TLS 1.2	Yes
	ECDHE_RSA_NULL_SHA256	TLS 1.2	No
	ECDHE_ECDSA_NULL_SHA256	TLS 1.2	No
	TLS_RSA_WITH_NULL_NULL	TLS 1.2	No
	TLS_RSA_WITH_RC4_128_SHA256	TLS 1.2	No
	TLS_AES_128_GCM_SHA256	TLS 1.3	Yes
	TLS_AES_256_GCM_SHA384	TLS 1.3	Yes
	TLS_CHACHA20_POLY1305_SHA256	TLS 1.3	Yes
	TLS_AES_128_CCM_SHA256	TLS 1.3	Yes
	TLS_AES_128_CCM_8_SHA256	TLS 1.3	Yes

Important: As of 23rd July 2020, the following AllowedCipherSpecs attribute only enables CipherSpecs that are currently enabled by default. However, you should verify the CipherSpecs enabled by the following AllowedCipherSpecs attribute with current data, to ensure that CipherSpecs that have been deprecated since this date are not inadvertently re-enabled.

If you need to return to this order of CipherSpecs, you can do so by using the following AllowedCipherSpecs SSL/TransportSecurity stanza attribute value:

AllowedCipherSpecs=TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_GCM_SHA384,ECDHE_ECDSA_AES_128_CBC_SHA256,ECDHE_ECDSA_AES_256_CBC_SHA384,ECDHE_RSA_AES_128_CBC_SHA256,ECDHE_RSA_AES_256_CBC_SHA384,ECDHE_ECDSA_AES_128_GCM_SHA256,ECDHE_ECDSA_AES_256_GCM_SHA384,ECDHE_RSA_AES_128_GCM_SHA256,ECDHE_RSA_AES_256_GCM_SHA384

Providing a custom list of ordered and enabled CipherSpecs on IBM MQ for Multiplatforms

It is possible for you to provide an alternative set of CipherSpecs that are enabled and in your order of preference for use with IBM MQ channels, either using the [AIX, Linux, Windows]

AMQ_ALLOWED_CIPHERS environment variable or the AllowedCipherSpecs SSL stanza attribute of the .ini file. You may want to use this setting for either of the following reasons:

To restrict IBM MQ listeners from accepting incoming channel start requests, unless they use one of the named CipherSpecs.
To change the order of priority of CipherSpecs that are used in a TLS handshake.

This functionality can be used to control the CipherSpecs that are included in the ANY* CipherSpecs.

The AMQ_ALLOWED_CIPHERS environment variable or AllowedCipherSpecs SSL stanza attribute accepts:

A single CipherSpec name.
A comma separated list of CipherSpec names to re-enable.
The special value of ALL, representing all CipherSpecs.

Note: You should not enable ALL CipherSpecs, as this will enable SSL 3.0 and TLS 1.0 protocols and a large number of weak cryptographic algorithms.

If this setting is configured, it overrides the default CipherSpec list and causes IBM MQ to ignore weak cipher deprecation settings (see below):

IBM MQ listeners only accept SSL/TLS proposals that use one of the named CipherSpecs.
IBM MQ channels only allow a blank SSLCIPH value, or one of the named CipherSpecs.
runmqsc tab completion of SSLCIPH values restricts the completion values to one of the name CipherSpecs.

For example, if you only want to allow channels to be defined/altered and listeners to accept ECDHE_RSA_AES_128_GCM_SHA256 or ECDHE_ECDSA_AES_256_GCM_SHA384 you could set the following in the qm.ini file:


SSL:
AllowedCipherSpecs=ECDHE_RSA_AES_128_GCM_SHA256, ECDHE_ECDSA_AES_256_GCM_SHA384

Additionally, the CipherSpecs in this list will be used to determine the priority of the CipherSpecs used during a TLS handshake. For example, if you specify a list of TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256 it is likely that, during the handshake, the TLS_RSA_WITH_AES_128_CBC_SHA256 CipherSpec will be chosen over the TLS_RSA_WITH_AES_256_CBC_SHA256 CipherSpec if a client connects specifying both of these CipherSpecs, that is, a client connecting with ANY_TLS12.

Note that ciphers used by AMQP or MQTT channels can be restricted using java.security file settings.

Providing a custom list of ordered and enabled CipherSpecs on IBM MQ for z/OS

It is possible for you to provide an alternative set of CipherSpecs that are enabled, and in your order of preference, for use with IBM MQ channels, using the AllowedCipherSpecs TransportSecurity stanza attribute of The QMINI data set. You might want to do this for either of the following reasons:

To restrict IBM MQ listeners from accepting incoming channel start requests, unless they use one of the named CipherSpecs.
To change the order of priority of CipherSpecs that are used in a TLS handshake.

You can use this functionality to control the CipherSpecs that are included in the ANY* CipherSpecs. The AllowedCipherSpecs attribute accepts:

A single CipherSpec name.
A comma separated list of CipherSpec names to re-enable.
The special value of ALL, representing all CipherSpecs.
Note: You should not enable ALL CipherSpecs, as this will enable SSL 3.0 and TLS 1.0 protocols and a large number of weak cryptographic algorithms. If you do configure this setting, it overrides the default CipherSpec list and causes IBM MQ to ignore weak cipher deprecation settings; see Enabling deprecated CipherSpecs on z/OS.

IBM MQ listeners only accept SSL/TLS proposals that use one of the named CipherSpecs and IBM MQ channels only allow a blank SSLCIPH value, or one of the named CipherSpecs.

For example, if you only want to allow channels to be defined/altered and listeners to accept ECDHE_RSA_AES_128_GCM_SHA256 or ECDHE_RSA_AES_256_GCM_SHA384 you could set the following:


TransportSecurity:
AllowedCipherSpecs=ECDHE_RSA_AES_128_GCM_SHA256,
                   ECDHE_RSA_AES_256_GCM_SHA384

Additionally, the CipherSpecs in this list are used to determine the priority of the CipherSpecs used during a TLS handshake. For example, if you specify a list of TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256 it is likely that, during the handshake, the TLS_RSA_WITH_AES_128_CBC_SHA256 CipherSpec will be chosen over the TLS_RSA_WITH_AES_256_CBC_SHA256 CipherSpec if a client connects specifying both of these CipherSpecs, that is, a client connecting with ANY_TLS12.