Enabling CipherSpecs

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

Note: On UNIX, Linux®, and Windows, IBM® MQ provides FIPS 140-2 compliance through the IBM Crypto for C cryptographic module. The certificate for this module has been moved to the Historical status. Customers should view the IBM Crypto for C certificate and be aware of any advice provided by NIST. A replacement FIPS 140-3 module is currently in progress and its status can be viewed by searching for it in the NIST CMVP modules in process list.

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.

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.

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.

Platform support¹	CipherSpec name	Protocol used	MAC algorithm	Encryption algorithm	Encryption bits	FIPS²	Suite B
	`TLS_RSA_WITH_AES_128_CBC_SHA`	TLS 1.0	SHA-1	AES	128	Yes	No
	`TLS_RSA_WITH_AES_256_CBC_SHA` ³	TLS 1.0	SHA-1	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` ³	TLS 1.2	SHA-384	AES	256	Yes	No
	`ECDHE_ECDSA_AES_128_GCM_SHA256` ⁴	TLS 1.2	AEAD AES-128 GCM	AES	128	Yes	128 bit
	`ECDHE_ECDSA_AES_256_GCM_SHA384`³ ⁴	TLS 1.2	AEAD AES-128 GCM	AES	256	Yes	192 bit
All	`ECDHE_RSA_AES_128_CBC_SHA256`	TLS 1.2	SHA-256	AES	128	Yes	No
All	`ECDHE_RSA_AES_256_CBC_SHA384` ³	TLS 1.2	SHA-384	AES	256	Yes	No
(LTS) All (V9.0.5 and later)	`ECDHE_RSA_AES_128_GCM_SHA256` ⁴	TLS 1.2	AEAD AES-128 GCM	AES	128	Yes	No
(LTS) All (V9.0.5 and later)	`ECDHE_RSA_AES_256_GCM_SHA384` ³ ⁴	TLS 1.2	AEAD AES-128 GCM	AES	SHA384	Yes	No
⁵	`ECDHE_ECDSA_RC4_128_SHA256`	TLS 1.2	AEAD AES-128 GCM	AES	SHA256	Yes	No
	`ECDHE_ECDSA_3DES_EDE_CBC_SHA256`	TLS 1.2	AEAD AES-128 GCM	3DES	SHA256	Yes	No
	`ECDHE_ECDSA_NULL_SHA256`	TLS 1.2	AEAD AES-128 GCM	ECDSA	SHA256	Yes	No
	`ECDHE_ECDSA_AES_256_GCM_SHA384` ³ ⁴	TLS 1.2	AEAD AES-128 GCM	AES	SHA384	Yes	No
	`TLS_RSA_WITH_AES_128_CBC_SHA256`	TLS 1.2	SHA-256	AES	128	Yes	No
	`TLS_RSA_WITH_AES_256_CBC_SHA256` ³	TLS 1.2	SHA-256	AES	256	Yes	No
All (V9.0.5 and later and 9.0 LTS)	`TLS_RSA_WITH_AES_128_GCM_SHA256` ⁴	TLS 1.2	AEAD AES-128 GCM	AES	128	Yes	No
All (V9.0.5 and later and 9.0 LTS)	`TLS_RSA_WITH_AES_256_GCM_SHA384` ³ ⁴	TLS 1.2	AEAD AES-128 GCM	AES	256	Yes	No
Notes: If no specific platform is noted, the CipherSpec is available on all platforms. For a list of platforms covered by each platform icon, see Release and platform icons in the product documentation. Specifies whether the CipherSpec is FIPS-certified on a FIPS-certified platform. See Federal Information Processing Standards (FIPS) for an explanation of FIPS. 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. Following a recommendation by GSKit, 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 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. Notes: You must set this environment variable on both sides of the connection, and applies to both client to queue manager connections and queue manager to queue manager connections. This statement applies to GSKit libraries only, so affects unmanaged .NET clients as well but not Java or managed .NET clients. For more information, see AES-GCM cipher restriction. This restriction does not apply to IBM MQ for z/OS®. Important: The GCM restriction is active, regardless of the FIPS mode being used. The CipherSpecs listed as supported on IBM i, apply to Versions 7.2 and 7.3 of 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.

It is possible for you to 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.

For example, if you want to re-enable ECDHE_RSA_RC4_128_SHA256, set the following environment variable:


AMQ_SSL_WEAK_CIPHER_ENABLE=ECDHE_RSA_RC4_128_SHA256

or, alternatively change the SSL stanza in the qm.ini file, by setting:


SSL

AllowWeakCipherSpec=ECDHE_RSA_RC4_128_SHA256

Enabling deprecated CipherSpecs

In addition to issuing AMQ_SSL_WEAK_CIPHER_ENABLE, or AllowWeakCipherSpec, as described in the preceding text, you must set the environment variable AMQ_SSL_V3_ENABLE=1 or set AllowSSLV3=Y, to continue using deprecated SSLv3 CipherSpecs, as described in Deprecation: SSLv3 protocol.

For example, if you want to re-enable RC4_MD5_US, set the following environment variables:


AMQ_SSL_V3_ENABLE=1
AMQ_SSL_WEAK_CIPHER_ENABLE=RC4_MD5_US

or, alternatively, change the SSL stanza in the qm.ini file, by setting:


SSL
AllowSSLV3=Y
AllowWeakCipherSpec=RC4_MD5_US

Attention: The following information concerning TLS_V1 applies from IBM MQ 9.0.0 Fix Pack 3 or IBM MQ 9.0.5 only.

In addition to issuing AMQ_TLS_WEAK_CIPHER_ENABLE, or AllowWeakCipherSpec, you must set the environment variable AMQ_TLS_V1_ENABLE=1 or set AllowTLSV1=Y, to continue using deprecated TLSv1 CipherSpecs.

For example, if you want to re-enable TLS_RSA_WITH_AES_128_CBC_SHA, set the following environment variables:


AMQ_TLS_V1_ENABLE=1
AMQ_TLS_WEAK_CIPHER_ENABLE=TLS_RSA_WITH_AES_128_CBC_SHA

or, alternatively, change the SSL stanza in the qm.ini file, by setting:


SSL
AllowTLSV1=Y
AllowWeakCipherSpec=TLS_RSA_WITH_AES_128_CBC_SHA

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 SSLv3 protocol, you also need to define the following DD statement in the CHINIT JCL:

JCL: //CSQXSSL3 DD DUMMY

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