Allowlisting concepts

In IBM® MQ classes for JMS, support for allowlisting of classes in the implementation of the JMS ObjectMessage interface provides a potential mitigation against some of the security risks that potentially relate to the Java object serialization and deserialization mechanism.

Allowlisting in IBM MQ classes for JMS

Note: Wherever possible, the term allowlist has replaced the term whitelist. One exception is the Java system property names mentioned in this topic.

IBM MQ classes for JMS supports allowlisting of classes in the implementation of the JMS ObjectMessage interface.

The allowlist defines which Java classes might be serialized with ObjectMessage.setObject() and deserialized with ObjectMessage.getObject().

Attempts to serialize or deserialize an instance of a class not included in the allowlist with ObjectMessage cause a javax.jms.MessageFormatException to be thrown, with a java.io.InvalidClassException as its cause.

Producing the allowlist

Important: IBM MQ classes for JMS cannot be distributed with an allowlist. The choice of classes to be transferred by using ObjectMessages is an application design choice and IBM MQ cannot preempt that.

For this reason, the allowlisting mechanism allows for two modes of operation:

DISCOVERY: In this mode, the mechanism produces a listing of fully qualified class names, reporting all classes that have been observed to be serialized or deserialized in ObjectMessages.
ENFORCEMENT: In this mode, the mechanism enforces allowlisting, rejecting attempts to serialize or deserialize classes that are not in the allowlist.

If you want to use this mechanism, you must initially run in DISCOVERY mode to gather the list of currently serialized and deserialized classes, review the list and use it as a basis for your allowlist. It might even be appropriate to use the list unchanged, but the list must be reviewed first before you decide to do this.

Controlling the allowlisting mechanism

Three system properties are available to control the allowlisting mechanism:

com.ibm.mq.jms.whitelist

This property can be specified in either of the following ways:

The path name of the file that contains the allowlist, in file URI format (that is, starting with file:). In DISCOVERY mode, this file is written to by the allowlisting mechanism. The file must not exist. If the file does exist, the mechanism throws an exception rather than overwrite it. In ENFORCEMENT mode, this file is read by the allowlisting mechanism.
A comma-separated of fully qualified class names that constitute the allowlist.

If this property is unset, the allowlist mechanism is inactive.

If you are using a Java Security Manager, you must ensure that the IBM MQ classes for JMS JAR files have read and write access to this file.

com.ibm.mq.jms.whitelist.discover

If this property is unset or set to false, the allowlist mechanism runs in ENFORCEMENT mode.
If this property is set to true and the allowlist has been specified as a file URI, the allowlist mechanism runs in DISCOVERY mode.
If this property is set to true and the allowlist has been specified as a list of class names, the allowlist mechanism throws a suitable exception.
If this property is set to true and the allowlist has not been specified by using the com.ibm.mq.jms.whitelist property, the allowlist mechanism is inactive.
If this property is set to true and the allowlist file already exists, the allowlist mechanism throws a java.io.InvalidClassException and entries are not added to the file.

com.ibm.mq.jms.whitelist.mode

This string property can be specified in any of three ways:

If this property is set to SERIALIZE, then ENFORCEMENT mode performs allowlist validation only on the ObjectMessage.setObject() method.
If this property is set to DESERIALIZE, then ENFORCEMENT mode performs allowlist validation only on the ObjectMessage.getObject() method.
If this property is unset, or set to any other value, then ENFORCEMENT mode performs allowlist validation on both the ObjectMessage.getObject() and the ObjectMessage.setObject() methods.

Format of the allowlist file

These are the main features of the format of the allowlist file:

The allowlist file is in default platform file encoding with platform-appropriate line-endings.
Note: If an allowlist file is being used, then that file is always written and read using the default file encoding for the JVM.
This is fine if the allowlist file is generated in any of the following ways:
- Generated by a stand-alone application running on z/OS® and used by other stand-alone applications that are also running on z/OS.
- Generated by an application running inside of WebSphere® Application Server on any platform, and used by another instance of WebSphere Application Server.
- Generated by a stand-alone application running on IBM MQ for Multiplatforms, and used by other stand-alone applications running on IBM MQ for Multiplatforms, or by applications running inside of WebSphere Application Server on any platform.
However, as WebSphere Application Server uses ASCII, and a standalone JVM uses EBCDIC, there will be file encoding issues if the allowlist file is generated in either of the following ways:
- Generated on z/OS, then used by standalone applications running on a platform other than z/OS or by WebSphere Application Server.
- Generated by either WebSphere Application Server or a standalone application running on a platform other than z/OS, then used by a stand-alone application on z/OS.
Each non-empty line contains a fully qualified class name. Empty lines are ignored.
Comments can be included - anything following a '#' character, to the end of the line, is ignored.
There is a very basic wildcarding mechanism:
- '*' can be the last element of a class name.
- '*' matches a single element of a class name, that is, the class, but no part of the package.
So com.ibm.mq.* would match com.ibm.mq.MQMessage but not com.ibm.mq.jmqi.remote.api.RemoteFAP.

Wildcarding does not work for classes in the default package that is for classes without an explicit package name, so a class name of "*" is rejected.
Badly formatted allowlist files, for example, files that contain an entry such as com.ibm.mq.*.Message, where the wildcard is not the last element, result in a java.lang.IllegalArgumentException being thrown.
An empty allowlist file has the effect of totally disabling the use of ObjectMessage.

Format of the allowlist as a comma-separated list

The same wildcarding mechanism is available for an allowlist as a comma-separated list.

The '*' can be expanded by the operating system if specified on a command line or in a shell script or batch file, so it might need special handling.
The '#' comment character is only applicable when a file is specified. If the allowlist is specified as a comma-separated list of class names, then assuming that the operating system or shell doesn't process it, as it is the default comment character in many UNIX or Linux® shells, it is treated as a normal character.

When does allowlisting happen?

Allowlisting is initiated when the application first runs an ObjectMessage setMessage() or getMessage() method.

The system properties are evaluated, the allowlist file is opened and in ENFORCEMENT mode, the list of allowlisted classes are loaded when the mechanism is initialized. At this point, an entry is written in to the IBM MQ JMS log file for the application.

When the mechanism is initialized, its parameters might not be changed. As the time of initialization is not easily predicted as it depends on application behavior. The system property settings and the allowlist file contents should therefore be regarded as fixed from the time that the application is started. Do not change the properties or the contents of the allowlist file while the application is running, as the results are not guaranteed.

Points to consider

The best approach to mitigating the risks intrinsic to the Java serialization mechanism would be to explore alternative approaches to data transfer such as using JSON instead of ObjectMessage. Using Advanced Message Security (AMS) mechanisms can add further security by ensuring that messages come from trusted sources.

If you use the Java Security Manager mechanism with your application, you must grant the following permissions:

FilePermission on any allowlist file that you use, with read permission for ENFORCEMENT mode, write permission for DISCOVER mode.
PropertyPermission (read) on the com.ibm.mq.jms.whitelist, com.ibm.mq.jms.whitelist.discover, and com.ibm.mq.jms.whitelist.mode properties.

More information

See Setting up and using a JMS allowlist and Allowlisting in WebSphere Application Server for more information on allowlists.