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 Version 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.

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 N
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.


Change 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 , 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 Version 9.2.0, the following order of CipherSpecs was used:

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, we 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. For to return to this order of CipherSpecs, we 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 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: We 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 we 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. We 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.

We 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: We 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 Enable 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 we 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.

Parent topic: Enable CipherSpecs