Enabling CipherSpecs

Enable a CipherSpec by using the SSLCIPH parameter in either the DEFINE CHANNEL MQSC command or the ALTER CHANNEL MQSC command.

Some of the CipherSpecs that you can use with IBM® MQ are FIPS compliant. Some of the FIPS compliant CipherSpecs are also Suite B compliant although others, such as TLS_RSA_WITH_AES_256_CBC_SHA, are not.

All Suite B compliant CipherSpecs are also FIPS compliant. All Suite B compliant CipherSpecs fall into two groups: 128 bit (for example, ECDHE_ECDSA_AES_128_GCM_SHA256) and 192 bit (for example, ECDHE_ECDSA_AES_256_GCM_SHA384),

The following diagram illustrates the relationship between these subsets:

Diagram representing the relationship between FIPS compliant CipherSpecs and Suite B compliant CipherSpecs.

From IBM MQ 8.0.0 Fix Pack 3 the number of supported CipherSpecs has been reduced.

[V9.1.1 Nov 2018]For information about configuring the default CipherSpecs, see Default CipherSpec values enabled in IBM MQ. You can also provide an alternative set of CipherSpecs that are enabled for use with MQ channels. See Providing a custom list of enabled CipherSpecs on Multiplatforms.

For information about enabling the deprecated CipherSpecs, see Enabling deprecated CipherSpecs on Multiplatforms or Enabling deprecated CipherSpecs on z/OS. For a list of CipherSpecs that you can re-enable to use with IBM MQ, see Deprecated CipherSpecs.

[UNIX, Linux, Windows][V9.1.4 Dec 2019]From IBM MQ 9.1.4, IBM MQ supports the TLS 1.3 security protocol on UNIX, Linux®, and Windows. For information about using these CipherSpecs, see Using TLS 1.3 in IBM MQ and IBM MQ MQI client and TLS 1.3.

CipherSpecs that you can use with IBM MQ TLS support

Cipher specifications that you can use with the IBM MQ queue manager automatically are listed in the following table. When you request a personal certificate, you specify a key size for the public and private key pair. The key size that is used during the TLS handshake is the size stored in the certificate unless it is determined by the CipherSpec, as noted in the table.

Table 1. CipherSpecs you can use with IBM MQ TLS support
Platform support 1 CipherSpec name Protocol used Data integrity Encryption algorithm Encryption bits FIPS 2 Suite B
Alias CipherSpecs

[V9.1.1 Nov 2018]

All

ANY_TLS12 3 TLS 1.2 Negotiated Negotiated Negotiated Negotiated Negotiated

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

ANY_TLS13 4 TLS 1.3 Negotiated Negotiated Negotiated Negotiated Negotiated

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

ANY_TLS12_OR_HIGHER 5 Negotiated Negotiated Negotiated Negotiated Negotiated Negotiated

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

ANY_TLS13_OR_HIGHER 6 Negotiated Negotiated Negotiated Negotiated Negotiated Negotiated

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

ANY 7 Negotiated Negotiated Negotiated Negotiated Negotiated Negotiated
CipherSpecs for TLS 1.3

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

TLS_AES_128_GCM_SHA256 TLS 1.3 GCM AES-128 with GCM 128 No No

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

TLS_AES_256_GCM_SHA384 TLS 1.3 GCM AES-256 with GCM 256 No No

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

TLS_CHACHA20_POLY1305_SHA256 TLS 1.3 POLY1305 CHACHA20 256 No No

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

TLS_AES_128_CCM_SHA256 TLS 1.3 CBC-MAC AES-128 with CTR 128 No No

[V9.1.4 Dec 2019]

[UNIX, Linux, Windows]

TLS_AES_128_CCM_8_SHA256 8 TLS 1.3 CBC-MAC AES-128 with CTR 128 No No
CipherSpecs for TLS 1.2
All TLS_RSA_WITH_AES_128_CBC_SHA256 TLS 1.2 SHA-256 AES 128 Yes No
All TLS_RSA_WITH_AES_256_CBC_SHA256 9 TLS 1.2 SHA-256 AES 256 Yes No
All TLS_RSA_WITH_AES_128_GCM_SHA256 10 TLS 1.2 SHA-256 and AEAD GCM AES 128 Yes No
All TLS_RSA_WITH_AES_256_GCM_SHA384 9 10 TLS 1.2 SHA-384 and AEAD GCM AES 256 Yes No
All ECDHE_ECDSA_AES_128_CBC_SHA256 TLS 1.2 SHA-256 AES 128 Yes No
All ECDHE_ECDSA_AES_256_CBC_SHA384 9 TLS 1.2 SHA-384 AES 256 Yes No
All ECDHE_RSA_AES_128_CBC_SHA256 TLS 1.2 SHA-256 AES 128 Yes No
All ECDHE_RSA_AES_256_CBC_SHA384 9 TLS 1.2 SHA-384 AES 256 Yes No

[UNIX, Linux, Windows, IBM i]

ECDHE_ECDSA_AES_128_GCM_SHA256 9 10 TLS 1.2 SHA-256 and AEAD GCM AES SHA384 Yes 128 bit

[UNIX, Linux, Windows, IBM i]

ECDHE_ECDSA_AES_256_GCM_SHA384 9 10 TLS 1.2 SHA-384 and AEAD GCM AES SHA384 Yes 192 bit
All ECDHE_RSA_AES_128_GCM_SHA256 10 TLS 1.2 SHA-256 and AEAD GCM AES 128 Yes No
All ECDHE_RSA_AES_256_GCM_SHA384 9 10 TLS 1.2 AEAD AES-128 GCM AES SHA384 Yes No
Notes:
  1. For a list of platforms covered by each platform icon, see Release and platform icons in the product documentation.
  2. Specifies whether the CipherSpec is FIPS-certified on a FIPS-certified platform. See Federal Information Processing Standards (FIPS) for an explanation of FIPS.
  3. [V9.1.1 Nov 2018] The ANY_TLS12 CipherSpec represents a subset of acceptable CipherSpecs that use the TLS 1.2 protocol, as listed in this table for each platform.
  4. [UNIX, Linux, Windows][V9.1.4 Dec 2019]The ANY_TLS13 alias CipherSpec represents a subset of acceptable CipherSpecs that use the TLS 1.3 protocol, as listed in this table for each platform.
  5. [UNIX, Linux, Windows][V9.1.4 Dec 2019]The ANY_TLS12_OR_HIGHER alias CipherSpec negotiates the highest level of security that the remote end will allow but will only connect using a TLS 1.2 or higher protocol.
  6. [UNIX, Linux, Windows][V9.1.4 Dec 2019]The ANY_TLS13_OR_HIGHER alias CipherSpec negotiates the highest level of security that the remote end will allow but will only connect using a TLS 1.3 or higher protocol.
  7. [UNIX, Linux, Windows][V9.1.4 Dec 2019]The ANY alias CipherSpec negotiates the highest level of security that the remote end will allow.
  8. [UNIX, Linux, Windows][V9.1.4 Dec 2019]These CipherSpecs use an 8-octet Integrity Check Value (ICV) instead of a 16-octet ICV.
  9. This CipherSpec cannot be used to secure a connection from the IBM MQ Explorer to a queue manager unless the appropriate unrestricted policy files are applied to the JRE used by the Explorer.
  10. [Linux][Windows] Following a recommendation by GSKit, TLS 1.2 GCM CipherSpecs have a restriction which means that after 2ˆ24.5 TLS records are sent, using the same session key, the connection is terminated with message AMQ9288.

    To prevent this error from happening: avoid using TLS 1.2 GCM Ciphers, enable secret key reset, or start your IBM MQ queue manager or client with the environment variable GSK_ENFORCE_GCM_RESTRICTION=GSK_FALSE set.

    This restriction does not apply to IBM MQ for z/OS®.
    Important: The GCM restriction is active, regardless of the FIPS mode being used.
[UNIX, Linux, Windows][V9.1.4 Dec 2019]

Using TLS 1.3 in IBM MQ

From IBM MQ 9.1.4, IBM MQ supports TLS 1.3 on UNIX, Linux, and Windows. On any supported installation, new queue managers are created with an entry in the SSL stanza of the qm.ini file that reads:
SSL:   
  AllowTLSV13=TRUE 
Note: The file qm.ini can be found in the directory <data directory>/qmgrs/<qmgr name>.

If the queue manager was created using a version of IBM MQ prior to IBM MQ 9.1.4, but is later started using IBM MQ 9.1.4 or higher, it will not have the AllowTLSV13 property set. If you wish to enable TLS 1.3, you must edit the qm.ini file and add in the property as shown in the example (including the “SSL:” stanza if it does not yet exist).

This .ini file property enables TLS 1.3, which allows the use of TLS 1.3 CipherSpecs. In accordance with the TLS 1.3 specification, any attempts to communicate with a weak CipherSpec, regardless of whether they are enabled in IBM MQ or not, will be rejected. The CipherSpecs that TLS 1.3 considers weak are CipherSpecs that meet one or more of the following criteria:
  • Uses the SSL 3.0 protocol.
  • Uses RC4 or RC2 as the Encryption algorithm.
  • Has a encryption key size (bit) equal to or less than 112.
These restrictions are flagged with Note [10] in Table 1 of Deprecated CipherSpecs.
If you need to continue using such CipherSpecs, then you must disable TLS 1.3 mode. You do this by editing the queue manager's qm.ini file and changing the setting of the AllowTLSV13 property to:
SSL:   
  AllowTLSV13=FALSE
Note: With this setting in place you cannot use TLS 1.3 CipherSpecs.
[UNIX, Linux, Windows][V9.1.4 Dec 2019]

IBM MQ MQI client and TLS 1.3

When using the IBM MQ MQI client client, the value of AllowTLSV13 is inferred unless it is explicitly specified in the SSL stanza of the mqclient.ini file that is being used by the application.
  • If any weak CipherSpecs are enabled, AllowTLSV13 is set to FALSE and no TLS 1.3 CipherSpecs can be used.
  • Otherwise, AllowTLSV13 is set to TRUE and the new TLS 1.3 CipherSpecs and alias CipherSpecs may be used.
[UNIX, Linux, Windows, IBM i][V9.1.1 Nov 2018]

Default CipherSpec values enabled in IBM MQ

In default configuration, IBM MQ provides support for the TLS 1.2 protocol and various cryptographic algorithms using CipherSpecs. For compatibility purposes, IBM MQ can also be configured to use SSL 3.0 and TLS 1.0 protocols and a number of cryptographic algorithms that are known to be weak or susceptible to security vulnerabilities. The list of CipherSpecs that are enabled in default configuration may change by applying maintenance.

It is possible to configure IBM MQ to restrict or permit the use of CipherSpecs using the following controls:
  • Only permit FIPS 140-2 compliant CipherSpecs using SSLFIPS.
  • [UNIX, Linux, Windows]Only permit NSA Suite B compliant CipherSpecs using SUITEB.
  • [UNIX, Linux, Windows]Permit a custom list of CipherSpecs using AllowedCipherSpecs or the AMQ_ALLOWED_CIPHERS environment variable.
  • [UNIX, Linux, Windows]Permit the use of deprecated CipherSpecs using AllowWeakCipher or the AMQ_SSL_WEAK_CIPHER_ENABLE environment variable.
  • [z/OS]Permit the use of deprecated CipherSpecs using DD statements in the CHINIT JCL.
Note: If you specify a custom list of CipherSpecs using AllowedCipherSpecs or AMQ_ALLOWED_CIPHERS this overrides enablement of any deprecated CipherSpecs. Note that when using either NSA Suite B or FIPS 140-2 restrictions in combination with a custom CipherSpec list, you must ensure the custom list only contains CipherSpecs permitted by the Suite B or FIPS 140-2 settings.
[UNIX, Linux, Windows, IBM i][V9.1.1 Nov 2018]

Providing a custom list of enabled CipherSpecs on Multiplatforms

It is possible for you to provide an alternative set of CipherSpecs that are enabled 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 wish to use this setting to restrict IBM MQ listeners from accepting incoming channel start requests, unless they use one of the named CipherSpecs. 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, or
  • A comma separated list of IBM MQ CipherSpec names to re-enable, or
  • The special value of ALL, representing all CipherSpecs (not recommended).
Note: Enabling ALL CipherSpecs is not recommended 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 will only accept SSL/TLS proposals that use one of the named CipherSpecs.
  • IBM MQ channels will 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

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

[UNIX, Linux, Windows, IBM i]

Enabling deprecated CipherSpecs on Multiplatforms

By default, you are not allowed to specify a deprecated CipherSpec on a channel definition. If you attempt to specify a deprecated CipherSpec on Multiplatforms, you receive message AMQ8242: SSLCIPH definition wrong, and PCF returns MQRCCF_SSL_CIPHER_SPEC_ERROR.

You cannot start a channel with a deprecated CipherSpec. If you attempt to do so with a deprecated CipherSpec, the system returns MQCC_FAILED (2), together with a Reason of MQRC_SSL_INITIALIZATION_ERROR (2393) to the client.

You can re-enable one or more of the deprecated CipherSpecs for defining channels, at runtime on the server, by setting the environment variable AMQ_SSL_WEAK_CIPHER_ENABLE.

The AMQ_SSL_WEAK_CIPHER_ENABLE environment variable accepts:
  • A single CipherSpec name, or
  • A comma separated list of IBM MQ CipherSpec names to re-enable, or
  • The special value of ALL, representing all CipherSpecs (not recommended).
Note: Re-enabling ALL CipherSpecs is not recommended, as this will enable SSL 3.0 and TLS 1.0 protocols and a large number of weak cryptographic algorithms.
For example, if you want to re-enable ECDHE_RSA_RC4_128_SHA256, set the following environment variable:

  export AMQ_SSL_WEAK_CIPHER_ENABLE=ECDHE_RSA_RC4_128_SHA256
or, alternatively change the SSL stanza in the qm.ini file, by setting:

SSL:
  AllowTLSV1=Y
  AllowWeakCipherSpec=ECDHE_RSA_RC4_128_SHA256
[z/OS]

Enabling deprecated CipherSpecs on z/OS

By default, you are not allowed to specify a deprecated CipherSpec on a channel definition. If you attempt to specify a deprecated CipherSpec on z/OS, you receive message CSQM102E or message CSQX674E.

To enable weak (deprecated) cipherspecs, you need to define the following DD statement in the CHINIT JCL:
JCL: //CSQXWEAK DD DUMMY 
To enable the deprecated SSL 3.0 protocol, you also need to define the following DD statement in the CHINIT JCL:
JCL: //CSQXSSL3 DD DUMMY 
[V9.1.0 Jul 2018]To enable the deprecated TLS 1.0 protocol, you also need to define the following DD statement in the CHINIT JCL:
JCL: //TLS10ON DD DUMMY 
Note that the name of the DD card is TLS10ON, to signify that TLS 1.0 is turned ON, and not TLS100N.
To turn TLS 1.0 OFF, use the following statement:
JCL: //TLS10OFF DD DUMMY
If you do not want to negotiate with the listener using weak or broken cipher specifications, you need to define the following DD statement in the CHINIT JCL:
JCL: //WCIPSOFF DD DUMMY 
If you want to only negotiate with the listener using the cipher specifications listed on the System SSL default cipher specification list, you need to define the following DD statement in the CHINIT JCL:
JCL: //GSKDCIPS DD DUMMY 
[UNIX, Linux, Windows][V9.1.4 Dec 2019]

Minimum level versus fixed level CipherSpecs

IBM MQ supports two different types of CipherSpecs:
  • Minimum level CipherSpecs are those that do not set an upper bound, for example ANY, ANY_TLS12_OR_HIGHER or ANY_TLS13_OR_HIGHER.
  • Fixed level CipherSpecs are those that identify a specific protocol, for example ANY_TLS12 and ANY_TLS13, or a specific algorithm such as ECDHE_ECDSA_3DES_EDE_CBC_SHA256

To maximise simplicity of configuration whilst maintaining security, the use of minimum level CipherSpecs is recommended on both sides of the channel. This allows your communications to automatically support and use a higher TLS protocol version when both sides support a new version without the need for changing either side's configuration.

Using a minimum level CipherSpec on the initiating side, but a fixed level CipherSpec on the receiving side could result in the connection being rejected and messages AMQ9631 and AMQ9641 being issued.

See Relationship between Alias CipherSpec settings for tables containing different outcomes for Alias CipherSpec settings.