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 we 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:

From IBM MQ Version 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 we can re-enable to use with IBM MQ, see Deprecated CipherSpecs.

Cipher specifications that we 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 1 CipherSpec name Protocol used Data integrity Encryption algorithm Encryption bits FIPS 2 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 3 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 3 TLS 1.2 SHA-384 AES 256 Yes No

ECDHE_ECDSA_AES_128_GCM_SHA256 4 TLS 1.2 AEAD AES-128 GCM AES 128 Yes 128 bit

ECDHE_ECDSA_AES_256_GCM_SHA3843 4 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 3 TLS 1.2 SHA-384 AES 256 Yes No

(LTS)

All (V9.0.5 and later)

 ECDHE_RSA_AES_128_GCM_SHA256 4 TLS 1.2 AEAD AES-128 GCM AES 128 Yes No

(LTS)

All (V9.0.5 and later)

 ECDHE_RSA_AES_256_GCM_SHA384 3 4 TLS 1.2 AEAD AES-128 GCM AES SHA384 Yes No

5		 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 3 4 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 3 TLS 1.2 SHA-256 AES 256 Yes No
All (V9.0.5 and later and V9.0 LTS) TLS_RSA_WITH_AES_128_GCM_SHA256 4 TLS 1.2 AEAD AES-128 GCM AES 128 Yes No
All (V9.0.5 and later and V9.0 LTS) TLS_RSA_WITH_AES_256_GCM_SHA384 3 4 TLS 1.2 AEAD AES-128 GCM AES 256 Yes No
Notes:
  1. 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.
  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. 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.
  4. 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.

    This restriction does not apply to IBM MQ for z/OS®.Important: The GCM restriction is active, regardless of the FIPS mode being used.
  5. 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.

We 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 Version 9.0.0, Fix Pack 3 or IBM MQ Version 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 we 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