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 Java Security Manager enabled, we must configure your Java virtual machine (JVM) with a suitable policy configuration file.

The simplest way to create a suitable policy definition file 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. We can edit the policy configuration file either by using your preferred editor or by using the policy tool program supplied with your JRE.

• FilePermission on any allowlist file that we 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.

For more information, see Allowlisting concepts.

Example policy configuration file

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 the applications.

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

The IBM MQ classes for JMS trace facility requires further permissions as it performs additional querying of system properties, and also further file system operations.

A suitable template security policy file for running under a security manager with tracing enabled is provided in the samples/wmqjava directory of the IBM MQ installation as example.security.policy.