Setting up and using a JMS or Jakarta Messaging allowlist

This information tells you how an allowlist works, and how you set one up using the functionality contained in the IBM® MQ classes for JMS or IBM MQ classes for Jakarta Messaging to generate an allowlist file, containing a list of the types of ObjectMessages that an application can process.

Before you begin

Important:

Wherever possible, the term allowlist has replaced the term whitelist. For IBM MQ 9.0 and later releases, this includes some Java system property names mentioned in this topic. You do not have to change any existing configuration. The previous system property names also continue to work.

Before starting this task, make sure that you have read and understood Allowlisting concepts

About this task

Because JMS and Jakarta Messaging share much in common, further references to JMS in this topic can be taken as referring to both. Any differences are highlighted as necessary.

When you have enabled the allowlisting functionality, the IBM MQ classes for JMS use that functionality in the following ways:

When an application wants to send an ObjectMessage, it can create it in one of two ways, by calling the:
- Session.createObjectMessage(Serializable) method, passing in the object that is to be contained within the message.
- Session.createObjectMessage() method, to create an empty ObjectMessage, and then calling ObjectMessage.setObject(Serializable) to store the object to be sent inside the ObjectMessage.
When either the Session.createObjectMessage(Serializable) or the ObjectMessage.setObject(Serializable) methods are called, the classes for JMS check whether the object passed in is of a type that is mentioned in the allowlist.
If it is of a type mentioned, the object is serialized and stored within the ObjectMessage. However, if the object is of a type that is not in the allowlist, the IBM MQ classes for JMS throw a JMSException containing the message:
```
JMSCC0052: An exception occurred while serializing the object:
'java.io.InvalidClassException: <object class>; The class may not be serialized 
or deserialized as it has not been included in the allowlist '<allowlist>'.
```
back to the application.
Important: If the exception is thrown from the Session.createObjectMessage(Serializable) method, the ObjectMessage will not be created. Similarly, if the JMSException is thrown from the ObjectMessage.setObject(Serializable) method, the object will not be added to the ObjectMessage.
If an application receives an ObjectMessage, it calls the method ObjectMessage.getObject() to get the object contained within it. When this method is called, the IBM MQ classes for JMS check the type of object contained within the ObjectMessage, to see if that object is of a type specified in the allowlist.
If it is, the object is deserialized and returned to the application. However, if the object is of a type that is not in the allowlist, the IBM MQ classes for JMS throw a JMSException containing the message:
```
JMSCC0053: An exception occurred while deserializing a message: 
'java.io.InvalidClassException: <object class>; The class may not be 
serialized or deserialized as it has not been included in the 
allowlist '<allowlist>'.'.
```
back to the application.

For example, suppose your application contains the following code to send an ObjectMessage containing an object of type java.net.URI:

java.net.URL testURL = new java.net.URL("https://www.ibm.com/");
ObjectMessage msg = session.createObjectMessage(testURL);
sender.send(msg);

As allowlisting is not enabled, the application is able to successfully put the message to the required destination.

If you create a file called C:\allowlist.txt containing a single entry, java.net.URL, and you start the application again with the Java system property set:

-Dcom.ibm.mq.jms.allowlist=file:/C:/allowlist.txt

the allowlist functionality is enabled. The application is still able to create and send the ObjectMessage containing an object of type java.net.URI , as that type is specified in the allowlist.

However, if you change the allowlist.txt file so that the file contains the single entry java.util.Calendar, as the allowlist functionality is still enabled, when the application calls:

ObjectMessage msg = session.createObjectMessage(testURL);

the IBM MQ classes for JMS check the allowlist and find that it does not contain an entry for java.net.URI.

As a result, a JMSException containing the JMSCC0052 message is thrown.

Similarly, suppose you have another application that receives ObjectMessages using this code:

ObjectMessage message = (ObjectMessage)receiver.receive(30000);
if (message != null) {
    Object messageBody = objectMessage.getObject();
    if (messageBody instanceof java.net.URI) {
      :    :    :    :    :    :    :

If allowlisting is not enabled, the application is able to receive ObjectMessages that contain an object of any type. The application then checks if the object is of type java.net.URL before performing the appropriate processing.

If you now start the application with the Java system property:

-Dcom.ibm.mq.jms.allowlist=java.net.URL

set, the allowlisting functionality is turned on. When the application calls:

Object messageBody = objectMessage.getObject();

the ObjectMessage.getObject() method only returns objects of type java.net.URL.

If the object contained within the ObjectMessage is not of this type, the ObjectMessage.getObject() method throws a JMSException containing the JMSCC0053 message. The application then needs to decide what do to with the message; for example, the message could be moved to the dead-letter queue for that queue manager.

The application only returns normally if the object inside the ObjectMessage is of the type java.net.URL.

Procedure

Run the application which processes ObjectMessages, with the following Java system properties specified:
```
-Dcom.ibm.mq.jms.allowlist.discover=true
-Dcom.ibm.mq.jms.allowlist=file:/<path to your allowlist file>    
```
When the application runs, the IBM MQ classes for JMS create a file which contained the types of objects that the application processed.
After the application has processed a representative sample of ObjectMessages over a period of time, stop it.
The allowlist file now contains a list of all of the types of objects contained within the ObjectMessages that the application processed while it was running.
If you have run the application for a sufficient time, this list includes all the possible types of objects contained within ObjectMessages that the application is likely to handle.
Restart the application with the following system property set:
```
-Dcom.ibm.mq.jms.allowlist=file:/<path to your allowlist file>  
```
This enables allowlisting, and if the IBM MQ classes for JMS detect an ObjectMessage of a type which is not in the allowlist, a JMSException containing either the JMSCC0052 or JMSCC0053 message is thrown.