MQCSP password protection

Authentication credentials that are specified in the MQCSP structure can be either protected by using the IBM® MQ MQCSP password protection feature, or encrypted by using TLS encryption.

IBM MQ client applications can supply a user ID and password when they connect to a queue manager. [MQ 9.4.0 Jun 2024] From IBM MQ 9.4.0, applications can also supply an authentication token as an alternative method of authentication. These credentials are sent to the queue manager in an MQCSP structure.

If the channel is using TLS encryption, credentials in the MQCSP are encrypted according to the TLS cipher specification. If the channel is not using TLS encryption, IBM MQ can protect these credentials before they are sent over the network, to avoid sending credentials over a network in plain text. The IBM MQ feature that protects these credentials is called MQCSP password protection.

If MQCSP password protection is used, the following data in the MQCSP structure is protected:

The password, if the MQCSP.AuthenticationType field is set to MQCSP_AUTH_USER_ID_AND_PW.
The authentication token, if the MQCSP.AuthenticationType field is set to MQCSP_AUTH_ID_TOKEN.

Important: MQCSP password protection is useful for test and development purposes as using MQCSP password protection is simpler than setting up TLS encryption, but not as secure. For production purposes, use TLS encryption in preference to IBM MQ password protection, especially when the network between the client and queue manager is untrusted, as TLS encryption is more secure.

If you are concerned about what encryption is being used, and how much protection it offers, you need to use full TLS encryption. With TLS, the algorithms are publicly known, and you can select the appropriate one for your enterprise by using the SSLCIPH channel attribute.

For more information about the MQCSP structure, see MQCSP structure.

Credentials in the MQCSP structure are protected by using IBM MQ password protection if all the following conditions are met:

Both ends of the connection are using IBM MQ 8.0, or later.
The channel is not using TLS encryption. A channel is not using TLS encryption if the channel has a blank SSLCIPH attribute, or the SSLCIPH attribute is set to a cipher specification that does not provide encryption. Null ciphers, for example, NULL_SHA, do not provide encryption.
The MQCSP.AuthenticationType field is set to MQCSP_AUTH_USER_ID_AND_PWD or MQCSP_AUTH_ID_TOKEN. For more information about the MQCSP.AuthenticationType field, see AuthenticationType.
If the client is IBM MQ Explorer and user identification compatibility mode is not enabled. This mode is not the default mode that is used by IBM MQ Explorer to send a user ID and password. This condition is applicable only to IBM MQ Explorer.

If any of these conditions are not met, the credentials are not protected with MQCSP password protection. If the value of the PasswordProtection attribute prohibits credentials from being sent in plain text, and the channel is not using TLS encryption, the connection fails and an MQRC_PASSWORD_PROTECTION_ERROR (2594) reason code is returned.

The PasswordProtection configuration setting

The PasswordProtection attribute in the Channels stanza of the client and queue manager configuration files can prevent credentials from being sent in plain text.

Note: This attribute is only relevant for connections that do not use TLS encryption. Credentials are encrypted by using TLS instead of being protected with MQCSP password protection if the connection uses TLS encryption.

The attribute can be set to one of the following values. The default value is compatible.

compatible

Credentials are sent in plain text if either the queue manager or client is running a version of IBM MQ earlier than IBM MQ 8.0. That is, credentials can be sent over a network in plain text for compatibility with versions of IBM MQ that do not support MQCSP password protection.

Credentials are protected by MQCSP password protection if both the queue manager and the client are running a version of IBM MQ at IBM MQ 8.0 or later.

The connection fails before the credentials are sent if both the queue manager and the client are running a version of IBM MQ at IBM MQ 8.0 or later, and the MQCSP.AuthenticationType field is not set to MQCSP_AUTH_USER_ID_AND_PW or MQCSP_AUTH_ID_TOKEN.

always

Credentials must not be sent over a network unprotected.

Credentials are protected by MQCSP password protection if both the queue manager and the client are running a version of IBM MQ at IBM MQ 8.0 or later.

The connection fails before the credentials are sent in the following cases:

The MQCSP.AuthenticationType field is not set to MQCSP_AUTH_USER_ID_AND_PW or MQCSP_AUTH_ID_TOKEN.
Either the queue manager or the client is running a version of IBM MQ earlier than IBM MQ 8.0.

optional

Credentials are protected by MQCSP password protection if both the queue manager and the client are running a version of IBM MQ at IBM MQ 8.0 or later, and the MQCSP.AuthenticationType field is set to MQCSP_AUTH_USER_ID_AND_PW or MQCSP_AUTH_ID_TOKEN. Otherwise, credentials are sent in plain text.

warn

Any client is allowed to send plain text credentials. If plain text credentials are received, warning message AMQ9297W is written to the queue manager error logs.

This option can be specified only in the queue manager configuration file.

For Java and JMS clients, the behavior of the PasswordProtection attribute changes depending on whether the client uses compatibility mode or MQCSP mode:

If Java and JMS clients are operating in compatibility mode, an MQCSP structure is not used to send the user ID and password when the client connects. Therefore, the behavior of the PasswordProtection attribute is the same as the behavior described for clients that are running a version of IBM MQ earlier than IBM MQ 8.0.
If Java and JMS clients are operating in MQCSP mode, the behavior of the PasswordProtection attribute is the behavior as described.

For more information about connection authentication with Java and JMS clients, see Connection authentication with the Java client.

MQCSP password protection and MQIPT

If a client connects to a queue manager through IBM MQ Internet Pass-Thru (MQIPT), the MQIPT route might be configured to add or remove TLS encryption. That is, the MQIPT route might be configured with SSLServer=true and SSLClient=false, or SSLServer=true and SSLClient=false. In this situation, the client and the queue manager might fail to agree a password protection algorithm as one end of the channel is using TLS encryption, and the other is not. This causes the connection to fail with reason code MQRC_PASSWORD_PROTECTION_ERROR (2594).

From IBM MQ 9.4.0, MQIPT can add or remove protection for credentials in MQCSP structures, in order to maintain compatibility between the client and queue manager for MQIPT routes that add or remove TLS encryption. MQCSP password protection in MQIPT is configured by using the PasswordProtection route property.

The default value of the PasswordProtection property is required. This value means that MQIPT is able to add, but not remove, MQCSP password protection. Connections to a MQIPT route that adds TLS encryption might fail with reason code MQRC_PASSWORD_PROTECTION_ERROR (2594) with this value of PasswordProtection. To resolve this issue, set the value of the PasswordProtection property to compatible in the MQIPT route configuration.

For more information about the PasswordProtection property in MQIPT, see PasswordProtection.