Java Security Manager

The Java Security Manager can be used with any MQIPT feature to provide a further level of security.

MQIPT uses the default Java Security Manager as defined in the java.lang.SecurityManager class. The Java Security Manager feature in MQIPT can be enabled or disabled using the global property SecurityManager. See Global properties for more information.

The Java Security Manager uses two default policy files:

• A global system policy file named $MQIPT_PATH/java/jre/lib/security/java.policy (where $MQIPT_PATH is the directory where MQIPT is installed) is used by all instances of a virtual machine on a host.
• A user-specific policy file called .java.policy, which can exist in the user's home directory.

An additional MQIPT policy file can also be used. You should use the MQIPT policy file instead of the default policy files described earlier. See SecurityManagerPolicy in Global properties for more information.

The syntax of the policy file is quite complex and although it can be changed using a text editor, it is usually easier to use the Policy Tool utility provided with Java for making any changes. The Policy Tool utility can be found in the $MQIPT_PATH/java/jre/bin directory and is fully documented within the Java documentation.

A sample policy file (mqiptSample.policy) has been provided with MQIPT to show you what permissions must be set for running MQIPT.

You must edit the sample policy file to match your configuration. In particular, note that the MQIPT home directory (the location of mqipt.conf) might not be the same as the MQIPT installation directory, so take care to specify the correct directories when configuring FilePermission entries in the security policy.

You must change the following entries:

• The java.io.FilePermission entry which grants read and write access to the errors directory. The file path in this entry must refer to the MQIPT home directory, because this is where the errors directory is located. MQIPT creates FFST Failure Data Capture files (AMQ*.FDC) and trace files (AMQ*.TRC*) in the errors directory. You must ensure that MQIPT has permission to create trace and FFST files in the errors directory, so that troubleshooting is possible.
• The java.io.FilePermission entry which grants read and write access to the logs directory. The file path in this entry must refer to the MQIPT home directory, because this is where the logs directory is located. MQIPT creates connection log files (mqipt*.log) in the logs directory if the ConnectionLog global property is enabled.
• The java.io.FilePermission entries which grant read and execute access to any directories in the MQIPT installation directory, such as the bin, exits, lib, and ssl directories. The file paths in these entries must be changed to refer to the MQIPT installation directory. Some of these entries may be omitted if they are not required.
• The java.net.SocketPermission entries must be modified to control connections into each listening MQIPT route. The listen and accept permissions are required for the listener port and listener address for each MQIPT route.
• The java.net.SocketPermission entries must be modified to control connections out of each MQIPT route. The connect permission is required for any route destinations, proxy servers or LDAP servers that the MQIPT route connects to. The resolve permission is required when specifying addresses using a host name.

Depending on your configuration, you might also need to add the following entries:

• A java.io.FilePermission entry to grant read access to mqipt.conf, or the MQIPT home directory containing mqipt.conf. If you need to configure MQIPT remotely using the Administration Client then MQIPT will also need write access to mqipt.conf so that it can save configuration changes.
• A java.io.FilePermission entry to grant read access to the security policy file itself. This is useful if an MQIPT refresh causes the security policy file to be re-read.
• Some java.io.FilePermission entries to grant read access to any SSL/TLS keyring files and password stash files. This is only required when using a route which has the SSLClient or SSLServer properties enabled.
• Some java.io.FilePermission entries to grant read or execute access to any MQIPT exit classes. This is only required when an MQIPT exit is enabled. You might need to grant additional permissions if required by the exit.

Note: Windows java.io.FilePermission entries must use two backslash characters (\\) for every backslash in the path. This is because a single backslash is used as an escape character.

The sample file assumes that MQIPT has been installed on a Windows system in C:\Program Files\IBM\MQ Internet Pass-Thru. It also assumes that the MQIPT home directory (the location of the mqipt.conf file) is the same as the MQIPT installation directory.

If we have installed MQIPT in another location, you must change the directory in the codeBase definition to refer to your MQIPT installation directory. Take care to include the correct prefix (file:/) and the correct file suffix (/lib/com.ibm.mq.ipt.jar). On UNIX and Linux systems, a typical codeBase URL might be file:/opt/mqipt/lib/com.ibm.mq.ipt.jar, assuming that MQIPT is installed in /opt/mqipt.

Permissions are usually defined with three attributes. To control socket connections, their values are:

class permission

java.net.SocketPermission

name to control

This is made up with the format hostname:port, where each component of the name can be specified by a wildcard. The hostname can be a domain name or an IP address. The leftmost position of the host name can be specified by an asterisk (*). For example, harry.company1.com would be matched by each of these strings:

• harry
• harry.company1.com
• *.company1.com
• *
• 198.51.100.123 (assuming this is the IP address of harry.company1.com)

The port component of the name can be specified as a single port address or a range of port addresses, for example:

1414

only port 1414

1414-

all port addresses greater than or equal to 1414

-1414

all port addresses less than or equal to 1414

1-1414

all port addresses between 1 and 1414, inclusive

allowed action

The actions used by java.net.SocketPermission are:

• accept, this allows permission to accept connections from the specified target
• connect, this allows permission to connect to the specified target
• listen, this allows permission to listen on the specified port or ports for connection requests
• resolve, this allows permission to use the DNS name service to resolve domain names into IP addresses

Control of the Java Security Manager can also be made through the java.security.manager and java.security.policy Java system properties, but it is recommended we use the SecurityManager and SecurityManagerPolicy properties for controlling MQIPT. To include diagnostic information in trace and FFST records, MQIPT must access certain MQIPT system properties and environment variables. You must always include the following properties in the Java security policy:

permission java.util.PropertyPermission "java.home", "read";
permission java.util.PropertyPermission "java.version", "read";
permission java.util.PropertyPermission "java.runtime.version", "read";
permission java.util.PropertyPermission "java.vm.info", "read";
permission java.util.PropertyPermission "java.vm.vendor", "read";
permission java.util.PropertyPermission "os.arch", "read";
permission java.util.PropertyPermission "os.name", "read";
permission java.util.PropertyPermission "os.version", "read";
permission java.lang.RuntimePermission "getenv.MQIPT_PATH";

If we do not include all of these properties, MQIPT will not operate correctly, and problem diagnosis will be impaired.