Running IBM MQ classes for JMS applications under the Java security manager

IBM® MQ classes for JMS can run with the Java security manager enabled. To run applications successfully with the security manager enabled, you must configure your Java virtual machine (JVM) with a suitable policy configuration file.

The simplest way to do this is to change the policy configuration file supplied with your Java Runtime Environment (JRE). On most systems, this file is in the directory lib/security/java.policy relative to your JRE directory. You can edit the policy configuration file using your preferred editor or the policytool program supplied with your JRE.

Important: Wherever possible, the term allowlist has replaced the term whitelist. One exception is the following Java system property names.

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.

ClassName allowlisting is supported from IBM MQ 8.0.0, Fix Pack 6. For more information, see Allowlisting concepts.

Here is an example of a policy configuration file that allows IBM MQ classes for JMS to run successfully under the default security manager. This file will need to be customized, to specify the locations of certain files and directories: MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed, MQ_DATA_DIRECTORY represents the location of the MQ data directory, and QM_NAME is the name of the Queue Manager for which access is being configured.


grant codeBase "file:MQ_INSTALLATION_PATH/java/lib/*" {
  //We need access to these properties, mainly for tracing
  permission java.util.PropertyPermission "user.name","read";
  permission java.util.PropertyPermission "os.name","read";
  permission java.util.PropertyPermission "user.dir","read";
  permission java.util.PropertyPermission "line.separator","read";
  permission java.util.PropertyPermission "path.separator","read";
  permission java.util.PropertyPermission "file.separator","read";
  permission java.util.PropertyPermission "com.ibm.msg.client.commonservices.log.*","read";
  permission java.util.PropertyPermission "com.ibm.msg.client.commonservices.trace.*","read";
  permission java.util.PropertyPermission "Diagnostics.Java.Errors.Destination.Filename","read";
  permission java.util.PropertyPermission "com.ibm.mq.commonservices","read";
  permission java.util.PropertyPermission "com.ibm.mq.cfg.*","read";

  //Tracing - we need the ability to control java.util.logging
  permission java.util.logging.LoggingPermission "control";
  // And access to create the trace file and read the log file - assumed to be in the current directory
  permission java.io.FilePermission "*","read,write";

  // We'd like to set up an mBean to control trace
  permission javax.management.MBeanServerPermission "createMBeanServer";
  permission javax.management.MBeanPermission "*","*";

  // We need to be able to read manifests etc from the jar files in the installation directory
  permission java.io.FilePermission "MQ_INSTALLATION_PATH/java/lib/-","read";

  //Required if mqclient.ini/mqs.ini configuration files are used
  permission java.io.FilePermission "MQ_DATA_DIRECTORY/mqclient.ini","read";
  permission java.io.FilePermission "MQ_DATA_DIRECTORY/mqs.ini","read";

  //For the client transport type.
  permission java.net.SocketPermission "*","connect,resolve";

  //For the bindings transport type.
  permission java.lang.RuntimePermission "loadLibrary.*";

  //For applications that use CCDT tables (access to the CCDT AMQCLCHL.TAB)
  permission java.io.FilePermission "MQ_DATA_DIRECTORY/qmgrs/QM_NAME/@ipcc/AMQCLCHL.TAB","read";

  //For applications that use User Exits
  permission java.io.FilePermission "MQ_DATA_DIRECTORY/exits/*","read";
  permission java.io.FilePermission "MQ_DATA_DIRECTORY/exits64/*","read";
  permission java.lang.RuntimePermission "createClassLoader";

  //Required for the z/OS platform
  permission java.util.PropertyPermission "com.ibm.vm.bitmode","read";

  // Used by the internal ConnectionFactory implementation
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";

  // Used for controlled class loading
  permission java.lang.RuntimePermission "setContextClassLoader";

  // Used to default the Application name in Client mode connections
  permission java.util.PropertyPermission "sun.java.command","read";

  // Used by the IBM JSSE classes
  permission java.util.PropertyPermission "com.ibm.crypto.provider.AESNITrace","read";

  //Required to determine if an IBM Java Runtime is running in FIPS mode,
  //and to modify the property values status as required.
  permission java.util.PropertyPermission "com.ibm.jsse2.usefipsprovider","read,write";
  permission java.util.PropertyPermission "com.ibm.jsse2.JSSEFIPS","read,write";
  //Required if an IBM FIPS provider is to be used for SSL communication.
  permission java.security.SecurityPermission "insertProvider.IBMJCEFIPS"; 

  // Required for non-IBM Java Runtimes that establish secure client 
  // transport mode connections using mutual TLS authentication
  permission java.util.PropertyPermission "javax.net.ssl.keyStore","read";
  permission java.util.PropertyPermission "javax.net.ssl.keyStorePassword","read";  
};

In the example, the grant statement contains the permissions required by IBM MQ classes for JMS. To use these grant statements in your policy configuration file, you might need to modify the path names depending on where you have installed IBM MQ classes for JMS and where you store your applications.

The sample applications supplied with IBM MQ classes for JMS, and scripts to run them, do not enable the security manager.