z/TPF security manager for Java

By default, IBM® Semeru Runtime Certified Edition for z/TPF is configured with a customized version of the Java security manager enabled. The z/TPF security manager enforces the class loading restriction, which is set up to prevent unauthorized Java classes from creating a Java™ class loader.

Introduction to the class loading restriction

Java class and archive files (.class and .jar files) are composed of Java bytecode instructions that define Java classes. These classes are loaded to the Java virtual machine (JVM) by using a class loader. In general, the z/TPF loader is used to load Java class and archive files to the z/TPF file system and the class loaders read the class and archive files from the file system. By using the z/TPF loader, you can enforce audit procedures, such as controlling what files are loaded to your z/TPF system and requiring the approval of a system operator.

Java applications can create their own class loaders. The applications can use the class loaders to dynamically load classes from any location including network connections. The class loading restriction of the z/TPF security manager is used to prevent an application from creating new class loaders and dynamically loading Java classes to a running Java application. By restricting the capability to dynamically load Java classes to a JVM, the z/TPF system is less exposed to vulnerabilities that might be introduced by this functionality.

Bypass the restriction

Some applications might create class loaders as part of their normal function. For example, some Java packages, such as the Spring Framework and WebSphere® Liberty create class loaders to dynamically load and manage classes as part of their frameworks. In addition, you might need to build your own class loaders to manage loading components.

In these cases, you can use the z/TPF security manager configuration file to bypass the restriction and allow specific classes to create class loaders. The z/TPF security manager contains some predefined classes that can create a class loader. These classes are used by the z/TPF application manager for Java (JAM) and can be used in applications.

Create a configuration file

You can create a configuration file for the z/TPF security manager. For IBM Semeru Runtime Certified Edition for z/TPF 11 and later, you must name the file tpf.clpolicy and load it to the /sys/tpf_pbfiles/opt/ibm/ibm-semeru-certified-11-jdk/lib/security directory. The tpf.clpolicy file consists of a sequence of class names that can create class loaders. The class names are in UTF-8 encoding and are separated by line breaks. The following example shows the format of the file that is represented by a set of allowed classes for a JAM.
# 2/14/2017 java install - authorized class loaders for JAMs
java.util.ResourceBundle$RBClassLoader$1
sun.reflect.ClassDefiner$1
java.lang.Thread
Note: Lines that begin with a number sign (#) or an exclamation point (!) are treated as comments.

Customize the configuration file

You can customize the tpf.clpolicy file to enable specific classes to create class loaders. If you try to run a package on your z/TPF system and encounter a security exception, you can add the class name to the tpf.clpolicy file. The following example shows a security exception when you use the java.lang.Thread class to create a class loader but the class name is not included in the tpf.clpolicy file. 
Exception in thread "main" java/lang/SecurityException:
Unauthorized class loader creation from java.lang.Thread
at com/ibm/tpf/TPFSecurityManager.checkCreateClassLoader (TPFSecurityManager.java:79)
at java/lang/ClassLoader.<init> (ClassLoader.java:216)
at java/lang/ClassLoader.<init> (ClassLoader.java:197)
at java/lang/ClassLoader.initializeClassLoaders (ClassLoader.java:176)
at java/lang/Thread.initialize (Thread.java:370)
at java/lang/Thread.<init>(Thread.java:133)
Note: The java.lang.Thread class has global permission to create classes in the z/TPF security manager, so you might not encounter the same security exception as the example shows.

Customize the Java security manager settings

By default, IBM Semeru Runtime Certified Edition for z/TPF uses the z/TPF security manager. The z/TPF security manager is implemented by the com.ibm.tpf.TPFSecurityManager class and is used as the Java security manager. You can customize which class is used as the Java security manager by taking one of the following actions:
  • Specify the -Djava.security.manager=usersecurityclass option in the options.default configuration file, where usersecurityclass is the class name that you want to use as the Java security manager.
  • Enter the ZFILE java command with the -Djava.security.manager=usersecurityclass option specified when you start the JVM.

To globally disable the z/TPF security manager, you must remove the -Djava.security.manager=com.ibm.tpf.TPFSecurityManager option from the options.default configuration file, which is in the /sys/tpf_pbfiles/opt/ibm/ibm-semeru-certified-11-jdk/lib directory.

If you globally disable the z/TPF security manager, you can enable the z/TPF security manager for specific JVMs or JAMs by taking one of the following actions:
  • Enter the ZFILE java command with the -Djava.security.manager=com.ibm.tpf.TPFSecurityManager option specified for your JVMs.
  • Add the -Djava.security.manager=com.ibm.tpf.TPFSecurityManager option to the <JVMCommandLineOption> element for your JAM descriptors.