[V7.5.0.8 Jun 2017]

ClassName allowlisting in JMS ObjectMessage

[V7.5.0.8 Jun 2017]In WebSphere® 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.

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

The Java object serialization and deserialization mechanism has been identified as a potential security risk because deserialization instantiates arbitrary Java objects, where there is the potential for maliciously sent data to cause various problems. One notable application of serialization is in Java Message Service (JMS) ObjectMessages that use serialization to encapsulate and transfer arbitrary objects.

Serialization allowlisting is a potential mitigation against some of the risks that serialization poses. By explicitly specifying which classes can be encapsulated in, and extracted from, ObjectMessages, allowlisting provides some protection against some serialization risks.

Allowlisting in WebSphere MQ classes for JMS

With APAR IT14385 and IBM® WebSphere MQ Version 7.5.0, Fix Pack 8, WebSphere 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: WebSphere 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 WebSphere MQ cannot pre-empt 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 WebSphere 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: The file might need conversion if you move it between heterogeneous systems.
  • 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 WebSphere 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 IBM WebSphere MQ 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.