Channel authentication records

To exercise more precise control over the access granted to connecting systems at a channel level, you can use channel authentication records.

You might find that clients attempt to connect to your queue manager using a blank user ID or a high-level user ID that would allow the client to perform undesirable actions. You can block access to these clients using channel authentication records. Alternatively, a client might assert a user ID that is valid on the client platform but is unknown or of an invalid format on the server platform. You can use a channel authentication record to map the asserted user ID to a valid user ID.

You might find a client application that connects to your queue manager and behaves badly in some way. To protect the server from the issues this application is causing, it needs to be temporarily blocked using the IP address the client application is on until such time as the firewall rules are updated or the client application is corrected. You can use a channel authentication record to block the IP address from which the client application connects.

If you have set up an administration tool such as the MQ Explorer, and a channel for that specific use, you might want to ensure that only specific client computers can use it. You can use a channel authentication record to allow the channel to be used only from certain IP addresses.

If you are just getting started with some sample applications running as clients, see Preparing and running the sample programs for an example of setting up the queue manager securely using channel authentication records.

To get channel authentication records to control inbound channels, use the MQSC command ALTER QMGR CHLAUTH(ENABLED).

CHLAUTH rules are applied for a channel MCA that is created in response to a new inbound connection. For a channel MCA created in response to the channel being started locally, no CHLAUTH rules are applied.

Table 1. Where CHLAUTH rules are applied for different channel pairs
Channel type	MCA where CHLAUTH rules are applied
SDR-RCVR	RCVR
RQSTR-SVR (Started at SVR)	RQSTR
RQSTR-SVR (Started at RQSTR)	SVR
RQSTR-SDR (Started at SDR)	RQSTR
RQSTR-SDR (Started at RQSTR)	SDR for initial connection. RQSTR for callback connection.

Channel authentication records can be created to perform the following functions:

To block connections from specific IP addresses.
To block connections from specific user IDs.
To set an MCAUSER value to be used for any channel connecting from a specific IP address.
To set an MCAUSER value to be used for any channel asserting a specific user ID.
To set an MCAUSER value to be used for any channel having a specific SSL or TLS Distinguished Name (DN).
To set an MCAUSER value to be used for any channel connecting from a specific queue manager.
To block connections claiming to be from a certain queue manager unless the connection is from a specific IP address.
To block connections presenting a certain SSL or TLS certificate unless the connection is from a specific IP address.

These uses are explained further in the following sections.

You create, modify, or remove channel authentication records using the MQSC command SET CHLAUTH or the PCF command Set Channel Authentication Record.

Note: Large numbers of channel authentication records can have a negative impact on a queue manager's performance.

Blocking IP addresses

It is normally the role of a firewall to prevent access from certain IP addresses. However, there might be occasions where you experience connection attempts from an IP address that should not have access to your IBM® MQ system and must temporarily block the address before the firewall can be updated. These connection attempts might not be coming from IBM MQ channels; these connection attempts might be coming from other socket applications that are misconfigured to target your IBM MQ listener. Block IP addresses by setting a channel authentication record of type BLOCKADDR. You can specify one or more single addresses, ranges of addresses, or patterns including wildcards.

Whenever an inbound connection is refused because the IP address is blocked in this manner, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_ADDRESS is issued, provided that channel events are enabled and the queue manager is running. Additionally, the connection is held open for 30 seconds prior to returning the error to ensure the listener is not flooded with repeated attempts to connect that are blocked.

To block IP addresses only on specific channels, or to avoid the delay before the error is reported, set a channel authentication record of type ADDRESSMAP with the USERSRC(NOACCESS) parameter.

Whenever an inbound connection is refused for this reason, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_NOACCESS is issued, provided that channel events are enabled and the queue manager is running.

See Blocking specific IP addresses for an example.

Blocking user IDs

To prevent certain user IDs from connecting over a client channel, set a channel authentication record of type BLOCKUSER. This type of channel authentication record applies only to client channels, not to message channels. You can specify one or more individual user IDs to be blocked, but you cannot use wildcards.

Whenever an inbound connection is refused for this reason, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_USERID is issued, provided that channel events are enabled.

See Blocking specific user IDs for an example.

You can also block any access for specified user IDs on certain channels by setting a channel authentication record of type USERMAP with the USERSRC(NOACCESS) parameter.

See Blocking access for a client asserted user ID for an example.

Blocking queue manager names

To specify that any channel connecting from a specified queue manager is to have no access, set a channel authentication record of type QMGRMAP with the USERSRC(NOACCESS) parameter. You can specify a single queue manager name or a pattern including wildcards. There is no equivalent of the BLOCKUSER function to block access from queue managers.

See Blocking access from a remote queue manager for an example.

Blocking SSL or TLS DNs

To specify that any user presenting an SSL or TLS personal certificate containing a specified DN is to have no access, set a channel authentication record of type SSLPEERMAP with the USERSRC(NOACCESS) parameter. You can specify a single distinguished name or a pattern including wildcards. There is no equivalent of the BLOCKUSER function to block access for DNs.

See Blocking access for an SSL Distinguished Name for an example.

Mapping IP addresses to user IDs to be used

To specify that any channel connecting from a specified IP address is to use a specific MCAUSER, set a channel authentication record of type ADDRESSMAP. You can specify a single address, a range of addresses, or a pattern including wildcards.

If you use a port forwarder, DMZ session break, or any other setup which changes the IP address presented to the queue manager, then mapping IP addresses is not necessarily suitable for your use.

See Mapping an IP address to an MCAUSER user ID for an example.

Mapping queue manager names to user IDs to be used

To specify that any channel connecting from a specified queue manager is to use a specific MCAUSER, set a channel authentication record of type QMGRMAP. You can specify a single queue manager name or a pattern including wildcards.

See Mapping a remote queue manager to an MCAUSER user ID for an example.

Mapping user IDs asserted by a client to user IDs to be used

To specify that if a certain user ID is used by a connection from an IBM MQ MQI client, a different, specified MCAUSER is to be used, set a channel authentication record of type USERMAP. User ID mapping does not use wildcards.

See Mapping a client asserted user ID to an MCAUSER user ID for an example.

Mapping SSL or TLS DNs to user IDs to be used

To specify that any user presenting an SSL/TLS personal certificate containing a specified DN is to use a specific MCAUSER, set a channel authentication record of type SSLPEERMAP. You can specify a single distinguished name or a pattern including wildcards.

See Mapping an SSL or TLS Distinguished Name to an MCAUSER user ID for an example.

Mapping queue managers, clients, or SSL or TLS DNs according to IP address

In some circumstances it might be possible for a third party to spoof a queue manager name. An SSL or TLS certificate or key database file might also be stolen and reused. To protect against these threats, you can specify that a connection from a certain queue manager or client, or using a certain DN must be connecting from a specified IP address. Set a channel authentication record of type USERMAP, QMGRMAP or SSLPEERMAP and specify the permitted IP address, or pattern of IP addresses, using the ADDRESS parameter.

See Mapping a remote queue manager to an MCAUSER user ID for an example.

Interaction between channel authentication records

It is possible that a channel attempting to make a connection matches more than one channel authentication record, and that these have contradictory effects. For example, a channel might assert a user ID which is blocked by a BLOCKUSER channel authentication record, but with an SSL or TLS certificate that matches an SSLPEERMAP record that sets a different user ID. In addition, if channel authentication records use wildcards, a single IP address, queue manager name, or SSL or TLS DN might match several patterns. For example, the IP address 192.0.2.6 matches the patterns 192.0.2.0-24, 192.0.2.*, and 192.0.*.6. The action taken is determined as follows.

The channel authentication record used is selected as follows:
- A channel authentication record explicitly matching the channel name takes priority over a channel authentication record matching the channel name by using a wildcard.
- A channel authentication record using an SSL or TLS DN takes priority over a record using a user ID, queue manager name, or IP address.
- A channel authentication record using a user ID or queue manager name takes priority over a record using an IP address.
If a matching channel authentication record is found and it specifies an MCAUSER, this MCAUSER is assigned to the channel.
If a matching channel authentication record is found and it specifies that the channel has no access, an MCAUSER value of *NOACCESS is assigned to the channel. This value can later be changed by a security exit program.
If no matching channel authentication record is found, or a matching channel authentication record is found and it specifies that the user ID of the channel is to be used, the MCAUSER field is inspected.
- If the MCAUSER field is blank, the client user ID is assigned to the channel.
- If the MCAUSER field is not blank, it is assigned to the channel.
Any security exit program is run. This exit program might set the channel user ID or determine that access is to be blocked.
If the connection is blocked or the MCAUSER is set to *NOACCESS, the channel ends.
If the connection is not blocked, for any channel except a client channel, the channel user ID determined in the previous steps is checked against the list of blocked users.
- If the user ID is in the list of blocked users, the channel ends.
- If the user ID is not in the list of blocked users, the channel runs.

Where a number of channel authentication records match a channel name, IP address, hostname, queue manager name, or SSL or TLS DN, the most specific match is used. The match considered to be:

The most specific is a name without wildcard characters, for example:
- A channel name of A.B.C
- An IP address of 192.0.2.6
- A hostname of hursley.ibm.com
- A queue manager name of 192.0.2.6
The most generic is a single asterisk (*) that matches, for example:
- All channel names
- All IP addresses
- All hostnames
- All queue manager names
A pattern with an asterisk at the start of a string is more generic than a defined value at the start of a string:
- For channels, *.B.C is more generic than A.*
- For IP addresses, *.0.2.6 is more generic than 192.*
- For hostnames, *.ibm.com is more generic than hursley.*
- For queue manager names, *QUEUEMANAGER is more generic than QUEUEMANAGER*
A pattern with an asterisk at a specific place in a string is more generic than a defined value at the same place in a string, and similarly for each subsequent place in a string:
- For channels, A.*.C is more generic than A.B.*
- For IP addresses, 192.*.2.6 is more generic than 192.0.*.
- For hostnames, hursley.*.com is more generic than hursley.ibm.*
- For queue manager names, Q*MANAGER is more generic than QUEUE*
Where two or more patterns have an asterisk at a specific place in a string, the one with fewer nodes following the asterisk is more generic:
- For channels, A.* is more generic than A.*.C
- For IP addresses, 192.* is more generic than 192.*.2.*.
- For hostnames, hurlsey.* is more generic than hursley.*.com
- For queue manager names, Q* is more generic than Q*MGR
Additionally, for an IP address:
- A range indicated with a hyphen (-), is more specific than an asterisk. Thus 192.0.2.0-24 is more specific than 192.0.2.*.
- A range that is a subset of another is more specific than the larger range. Thus 192.0.2.5-15 is more specific than 192.0.2.0-24.
- Overlapping ranges are not permitted. For example, you cannot have channel authentication records for both 192.0.2.0-15 and 192.0.2.10-20.
- A pattern cannot have fewer than the required number of parts, unless the pattern ends with a single trailing asterisk. For example 192.0.2 is invalid, but 192.0.2.* is valid.
- A trailing asterisk must be separated from the rest of the address by the appropriate part separator (a dot (.) for IPv4, a colon (:) for IPv6). For example, 192.0* is not valid because the asterisk is not in a part of its own.
- A pattern can contain additional asterisks, provided that no asterisk is adjacent to the trailing asterisk. For example, 192.*.2.* is valid, but 192.0.*.* is not valid.
- An IPv6 address pattern cannot contain a double colon and a trailing asterisk, because the resulting address would be ambiguous. For example, 2001::* could expand to 2001:0000:*, 2001:0000:0000:* and so on

For an SSL or TLS Distinguished Name (DN), the precedence order of substrings is as follows:

Table 2. Precedence order of substrings
Order	DN substring	Name
1	SERIALNUMBER=	Certificate serial number
2	MAIL=	Email address
3	E=	Email address (Deprecated in preference to MAIL)
4	UID=, USERID=	User identifier
5	CN=	Common name
6	T=	Title
7	OU=	Organizational unit
8	DC=	Domain component
9	O=	Organization
10	STREET=	Street / First line of address
11	L=	Locality
12	ST=, SP=, S=	State or province name
13	PC=	Postal code / zip code
14	C=	Country
15	UNSTRUCTUREDNAME=	Host name
16	UNSTRUCTUREDADDRESS=	IP address
17	DNQ=	Distinguished name qualifier

Thus, if an SSL or TLS certificate is presented with a DN containing the substrings O=IBM and C=UK, IBM MQ uses a channel authentication record for O=IBM in preference to one for C=UK, if both are present.

A DN can contain multiple OUs, which must be specified in hierarchical order with the large organizational units specified first. If two DNs are equal in all respects except for their OU values, the more specific DN is determined as follows:

If they have different numbers of OU attributes then the DN with the most OU values is more specific. This is because the DN with more Organizational Units fully qualifies the DN in more detail and provides more matching criteria. Even if its top-level OU is a wildcard (OU=*), the DN with more OUs is still regarded as more specific overall.
If they have the same number of OU attributes then the corresponding pairs of OU values are compared in sequence left-to-right, where the left-most OU is the highest-level (least specific), according to the following rules.
1. An OU with no wildcard values is the most specific because it can only match exactly one string.
2. An OU with a single wildcard at either the beginning or end (for example, OU=ABC* or OU=*ABC) is next most specific.
3. An OU with two wildcards for example, OU=*ABC*) is next most specific.
4. An OU consisting only of an asterisk (OU=*) is the least specific.
If the string comparison is tied between two attribute values of the same specificity then whichever attribute string is longer is more specific.
If the string comparison is tied between two attribute values of the same specificity and length then the result is determined by a case-insensitive string comparison of the portion of the DN excluding any wildcards.

If two DNs are equal in all respects except for their DC values, the same matching rules apply as for OUs except that in DC values the left-most DC is the lowest-level (most specific) and the comparison ordering differs accordingly.

Displaying channel authentication records

To display channel authentication records, use the MQSC command DISPLAY CHLAUTH or the PCF command Inquire Channel Authentication Records. You can choose to return all records that match the supplied channel name, or you can choose an explicit match. The explicit match tells you which channel authentication record would be used if a channel attempted to make a connection from a specific IP address, from a specific queue manager or using a specific user ID, and, optionally, presenting an SSL/TLS personal certificate containing a specified DN.