Using the Java SecurityManager with Tomcat

Why use a SecurityManager?

The Java SecurityManager is what allows a web browser to run an applet in its own sandbox to prevent untrusted code from accessing files on the local system, connecting to a host other than the one the applet was loaded from, etc.

In the same way the SecurityManager protects you from an untrusted applet running in your browser, use of a SecurityManager while running Tomcat can protect your server from trojan servlets, JSP's, JSP beans, and tag libraries.  Or even inadvertent mistakes.

Imagine if someone who is authorized to publish JSP's on your site inadvertently included the following in their JSP:

<% System.exit(1); %>

Every time that JSP was executed by Tomcat, Tomcat would exit.

Using the Java SecurityManager is just one more line of defense a system administrator can use to keep the server secure and reliable.

System Requirements

Use of the SecurityManager requires a JVM that supports JDK 1.2.

Precautions

Implementation of a SecurityManager in Tomcat has not been fully tested to ensure the security of Tomcat.  No special Permissions have been created to prevent access to internal Tomcat classes by JSP's, web applications, servlets, beans, or tag libraries. Make sure that you are satisfied with your SecurityManager configuration before allowing untrusted users to publish web applications, JSP's, servlets, beans, or tag libraries.

Still, running with a SecurityManager is definitely better than running without one.

Types of Permissions

Permission classes are used to define what Permissions a class loaded by Tomcat will have.  There are a number of Permission classes as part of the JDK and you can even create your own Permission class for use in your own web applications.

This is just a short summary of the System SecurityManager Permission classes applicable to Tomcat.  Please refer to the JDK documentation for more information on using the below Permissions.

java.util.PropertyPermission
Controls read/write access to JVM properties such as java.home.

java.lang.RuntimePermission
Controls use of some System/Runtime functions like exit() and exec().

java.io.FilePermission
Controls read/write/execute access to files and directories.

java.net.SocketPermission
Controls use of network sockets.

java.net.NetPermission
Controls use of multicast network connections.

java.lang.reflect.ReflectPermission
Controls use of reflection to do class introspection.

java.security.SecurityPermission
Controls access to Security methods.

java.security.AllPermission
Allows access to all permissions, just as if you were running Tomcat without a SecurityManager.

Configuring Tomcat for use with a SecurityManager

tomcat.policy

The security policies implemented by the Java SecurityManager are configured in the tomcat.policy file located in the tomcat conf directory.  The tomcat.policy file replaces any system java.policy file.  The tomcat.policy file can be edited by hand or you can use the policytool application that comes with Java 1.2, or later.

Entries in the tomcat.policy file use the standard java.policy file format as follows:

// Example policy file entry

grant [signedBy <signer> [,codeBase <code source>] {
    permission <class> [<name> [, <action list>]];
};

The signedBy and codeBase entries are optional when granting permissions. Comment lines begin with // and end at a new line.

The codeBase is in the form of a URL and for a file URL can use the ${java.home} and ${tomcat.home} properties which are expanded out to the directory paths defined for them.

Default tomcat.policy file

// Permissions for tomcat.
 
// javac needs this
grant codeBase "file:${java.home}/lib/-" {
  permission java.security.AllPermission;
};
 
// Tomcat gets all permissions
grant codeBase "file:${tomcat.home}/lib/-" {
  permission java.security.AllPermission;
};
 
grant codeBase "file:${tomcat.home}/classes/-" {
  permission java.security.AllPermission;
};
 
// Example webapp policy
// By default we grant read access on webapp dir
// and read of the line.separator PropertyPermission
grant codeBase "file:${tomcat.home}/webapps/examples" {
  permission java.net.SocketPermission "localhost:1024-","listen";
  permission java.util.PropertyPermission "*","read";
};

Here is an example where in addition to the above, we want to grant the examples web application the ability to connect to the localhost smtp port so that it can send mail.

grant codeBase "file:${tomcat.home}/webapps/examples" {
  permission java.net.SocketPermission "localhost:25","connect";
  permission java.net.SocketPermission "localhost:1024","listen";
  permission java.util.PropertyPermission "*","read";
};

Now what if we wanted to give all contexts not configured by their own grant entry some default permissions in addition to what Tomcat assigns by default.

grant {
  permission java.net.SocketPermission "localhost:1024","listen";
  permission java.util.PropertyPermission "*","read";
};

Finally, a more complex tomcat.policy file.  In this case we are using Tomcat as an app server for a number of remote web servers.  We want to limit what remote web servers can connect to Tomcat by using the Java SecurityManager.

// Permissions for tomcat.
// javac needs this
grant codeBase "file:${java.home}/lib/-" {
  permission java.security.AllPermission;
};
 
// Tomcat with IP filtering
grant codeBase "file:${tomcat.home}/lib/-" {
  // Tomcat should be able to read/write all properties
  permission java.util.PropertyPermission "*","read,write";
  // Tomcat needs to be able to read files in its own directory
  permission java.io.FilePermission "${tomcat.home}/-","read";
  // Tomcat has to be able to write its logs
  permission java.io.FilePermission "${tomcat.home}/logs/-","read,write";
  // Tomcat has to be able to write to the conf directory
  permission java.io.FilePermission "${tomcat.home}/conf/-","read,write";
  // Tomcat has to be able to compile JSP's
  permission java.io.FilePermission "${tomcat.home}/work/-","read,write,delete";
  // Tomcat needs all the RuntimePermission's
  permission java.lang.RuntimePermission "*";
  // Needed so Tomcat can set security policy for a Context
  permission java.security.SecurityPermission "*";
  // Needed so that Tomcat will accept connections from a remote web server
  // Replace XXX.XXX.XXX.XXX with the IP address of the remote web server
  permission java.net.SocketPermission "XXX.XXX.XXX.XXX:1024-","accept,listen,resolve";
  // Tomcat has to be able to use its port on the localhost
  permission java.net.SocketPermission "localhost:1024-","connect,accept,listen,resolve";
};
 
// Example webapp policy
// By default we grant read access on webapp dir
// and read of the line.separator PropertyPermission
grant codeBase "file:${tomcat.home}/webapps/examples" {
  permission java.net.SocketPermission "localhost:1024-","listen";
  permission java.util.PropertyPermission "*","read";
};

Starting Tomcat with a SecurityManager

Once you have configured the tomcat.policy for use with a SecurityManager, Tomcat can be started with the SecurityManager in place by adding the "-security" option to bin/startup.bat or bin/startup.

What happens when the SecurityManager detects a Security violation?

The JVM will throw an AccessControlException or a SecurityException when the SecurityManager detects a security policy violation.

Trouble shooting tomcat.policy configuration and Security Violations

You can turn on Java SecurityManager debug logging by setting the environmental variable:

TOMCAT_OPTS=-Djava.security.debug=all

The debug output will be written to Tomcat's log file, or the console if no log file is defined.

Note: This gives the most complete debugging information, but generates many MB's of output, for less verbose security debug output, use:

TOMCAT_OPTS=-Djava.security.debug=access,failure

Use the following shell command to determine all the security debug options available: java -Djava.security.debug=help

JSP Compile using JVM internal javac fails with AccessControlException for RuntimePermission accessClassInPackage sun.tools.javac.

Check your JAVA_HOME/jre/lib/security/java.security file configuration.  Comment out the line "package.access=sun.".