Securing AMQP clients

You use a range of security mechanisms to secure connections from AMQP clients and help ensure data is suitably protected on the network. You can build security into your MQ Light applications. You can also use existing security features of IBM® MQ with AMQP clients, in the same way that the features are used for other applications.

Channel authentication rules (CHLAUTH)

You can use channel authentication rules to restrict the TCP connections to a queue manager. AMQP channels support the use of channel authentication rules that you configure for your queue manager. If channel authentication rules are defined with a profile that matches any AMQP channels on your queue manager, these rules are applied to those channels. By default, channel authentication is enabled on new IBM MQ queue managers so you must complete at least some configuration before you can use an AMQP channel.

For more information about how to configure channel authentication rules to allow AMQP connections to your queue manager, see Creating and using AMQP channels.

Connection authentication (CONNAUTH)

You can use connection authentication to authenticate connections to a queue manager. AMQP channels support the use of connection authentication to control access to the queue manager from AMQP applications.

The AMQP protocol uses the SASL (Simple Authentication and Security Layer) framework to specify how a connection is authenticated. There are various SASL mechanisms and IBM MQ supports two SASL mechanisms: ANONYMOUS and PLAIN.

In the case of ANONYMOUS, no credentials are passed from the client to the queue manager for authentication. If the IBM MQ AUTHINFO object that is specified in the queue manager CONNAUTH attribute has a CHCKCLNT value of REQUIRED or REQDADM (if connecting as an administrative user), the connection is refused. If the value of CHCKCLNT is NONE or OPTIONAL, the connection is accepted.

In the case of PLAIN, a user name and password are passed from the client to the queue manager for authentication. If the IBM MQ AUTHINFO object that is specified in the queue manager CONNAUTH attribute has a CHCKCLNT value of NONE, the connection is refused. If the value of CHCKCLNT is OPTIONAL, REQUIRED, or REQDADM (if connecting as an administrative user), the user name and password is checked by the queue manager. The queue manager checks the operating system (if the AUTHINFO object is of type IDPWOS) or an LDAP repository (if the AUTHINFO object is of type IDPWLDAP).

The following table summarizes this authentication behavior:

Table 1. Summary of SASL mechanisms and connection authentication
SASL mechanism	Credentials passed from client to queue manager?	CHCKCLNT value
ANONYMOUS	No	REQUIRED or REQDADM - connection refused NONE or OPTIONAL - connection accepted
PLAIN	Yes, user name and password	REQUIRED, REQDADM, or OPTIONAL - user name and password checked by the queue manager NONE - connection refused

If you are using an MQ Light client, you can specify credentials by including them in the AMQP address you connect to, for example:

amqp://mwhitehead:mYp4ssw0rd@localhost:5672/sports/football

MCAUSER setting on a channel

AMQP channels have an MCAUSER attribute, which you can use to set the IBM MQ user ID that all connections to that channel are authorized under. All connections from AMQP clients to that channel adopt the MCAUSER ID you have configured. That user ID is used for authorization of messaging on different topics.

You are recommended to use channel authentication (CHLAUTH) to secure connections to queue managers. If you are using channel authentication, you are recommended to configure the value of MCAUSER to a non-privileged user. This ensures that if a connection to a channel is not matched by a CHLAUTH rule, the connection is not authorized to perform any messaging on the queue manager.

SSL/TLS support

AMQP channels support SSL/TLS encryption using keys from the key repository configured for your queue manager. AMQP channel configuration options for SSL/TLS encryption support the same options as other types of MQ channel; you can specify a cipher specification and whether the queue manager requires certificates from AMQP client connections.

By using the FIPS attributes of the queue manager you can control the SSL/TLS cipher suites, which you can use to secure connections from AMQP clients.

For information about how to set up a key repository for the queue manager see Working with SSL/TLS on AIX, Linux, and Windows.

For information about how to configure SSL/TLS support for an AMQP client connection, see Creating and using AMQP channels.

From IBM MQ 9.4.0, the AMQP channel no longer supports CMS key repositories on the queue manager. You can use the runmqakm command to convert a CMS key repository to the PKCS #12 format, which is supported. For example, you can use the following command to convert a key repository named sslTest.kdb from CMS format to PKCS #12 format. The new key repository is named sslTest.p12, and protected with the password passw0rd.

runmqakm -keydb -convert -type cms -db sslTest.kdb -stashed -new_format pkcs12 -target sslTest.p12 -new_pw passw0rd

Important: You set the password in the queue manager's KEYRPWD attribute. For more information, see Supplying the key repository password for a queue manager on AIX, Linux, and Windows and Encrypting key repository passwords on AIX, Linux, and Windows.

From IBM MQ 9.4.4, with the JRE upgrade to IBM Semeru Runtime 21, only FIPS 140-3 is supported for FIPS configuration. For the AMQP protocol, FIPS 140-3 is supported only on the following platforms:

AIX
Windows systems
Linux on Power® Systems
Linux for x86-64

To enable FIPS 140-3 cryptography for the AMQP channels, the following updates are required:

Set the SSLFIPS attribute to YES in the queue manager.

Update the amqp_java.properties file with the following:

-Dsemeru.fips=true 
-Dsemeru.customprofile=OpenJCEPlusFIPS

You can also use the setamqp property to update the amqp_java.properties by using the following command:

setamqp properties -m -k -Dsemeru.fips -v true -k -Dsemeru.customprofile -v OpenJCEPlusFIPS.

If SSLFIPS is enabled in the queue manager without setting both the Dsemeru Java properties, the AMQP service does not start and the following error message is logged:

AMQXR2125E: SSLFIPS property is set to YES in the Queue Manager configuration but the FIPS 140-3 JVM system properties -Dsemeru.fips=true and -Dsemeru.customprofile=OpenJCEPlusFIPS are not set in the amqp_java.properties file.

If the Java properties are set but SSLFIPS is not enabled, the AMQP service does not start and the following error message is logged:

AMQXR2126E: The FIPS 140-3 JVM system properties -Dsemeru.fips=true and -Dsemeru.customprofile=OpenJCEPlusFIPS are set in the amqp_java.properties file but the SSLFIPS property is not set in the Queue Manager configuration.

For more information, see setamqp (set AMQP server properties).

FIPS 140-3 support not available on Linux s390x

The AMQP service is available on the Linux s390x architecture but this system does not support FIPS 140-3. On this platform, the AMQP channel can still use FIPS-compliant ciphers without enabling FIPS configuration. If FIPS is enabled, the AMQP service will not start and a general security exception is logged in the AMQP error log. The exception includes an error message.

AMQXR2127E: FIPS 140-3 support is not available on this operating system.

Allowing the AMQP service to start without FIPS support

To allow the AMQP service to start when FIPS is enabled but not supported on the platform, you can use the com.ibm.mq.MQXR.AllowStartupWithoutFIPS property. You configure this property in the amqp_java.properties file. The service starts, but an error message is logged indicating that FIPS is not supported. This feature is important for events where the queue manager sets SSLFIPS to YES as other channels require FIPS to be enabled. Disabling SSLFIPS in such cases can negatively impact those channels. By using this property, AMQP services can continue to run without compromising the broader FIPS configuration.

Java Authentication and Authorization Service (JAAS)

You can optionally configure AMQP channels with a JAAS login module, which can check the user name and password provided by an AMQP client. See Configuring JAAS for AMQP channels.