Security Manager How-To

&project; Glenn Nielsen Jean-Francois Arcand Security Manager How-To

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 file system, connecting to a host other than the one the applet was loaded from, and so on. 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, JSPs, JSP beans, and tag libraries. Or even inadvertent mistakes.

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

]]>

Every time this 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.

WARNING - A security audit have been conducted using the Tomcat codebase. Most of the critical package have been protected and a new security package protection mechanism has been implemented. Still, make sure that you are satisfied with your SecurityManager configuration before allowing untrusted users to publish web applications, JSPs, servlets, beans, or tag libraries. However, running with a SecurityManager is definitely better than running without one.

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

This is just a short summary of the standard system SecurityManager Permission classes applicable to Tomcat. See http://docs.oracle.com/javase/7/docs/technotes/guides/security/ for more information.

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(). Also control the package access/definition.
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.

Policy File Format

The security policies implemented by the Java SecurityManager are configured in the $CATALINA_BASE/conf/catalina.policy file. This file completely replaces the java.policy file present in your JDK system directories. The catalina.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 catalina.policy file use the standard java.policy file format, as follows:

,] [codeBase

] {
  permission    [ [, ]];
};]]>

  The signedBy and codeBase entries are
  optional when granting permissions.  Comment lines begin with "//" and
  end at the end of the current line.  The codeBase is in the
  form of a URL, and for a file URL can use the ${java.home}
  and ${catalina.home} properties (which are expanded out to
  the directory paths defined for them by the JAVA_HOME,
  CATALINA_HOME and CATALINA_BASE environment
  variables).

  The Default Policy File

  The default $CATALINA_BASE/conf/catalina.policy file
  looks like this:


&defaultpolicy;

  Starting Tomcat With A SecurityManager

  Once you have configured the catalina.policy file for use
  with a SecurityManager, Tomcat can be started with a SecurityManager in
  place by using the "-security" option:
$CATALINA_HOME/bin/catalina.sh start -security    (Unix)
%CATALINA_HOME%\bin\catalina start -security      (Windows)

  

    When using packed WAR files, it is necessary to use Tomcat's custom war
    URL protocol to assign permissions to web application code.

    To assign permissions to the entire web application the entry in the
    policy file would look like this:



    To assign permissions to a single JAR within the web application the
    entry in the policy file would look like this:




  Starting with Tomcat 5, it is now possible to configure which Tomcat
  internal package are protected against package definition and access. See
  
    http://www.oracle.com/technetwork/java/seccodeguide-139067.html
    for more information.


  WARNING: Be aware that removing the default package protection
  could possibly open a security hole

  The Default Properties File

  The default $CATALINA_BASE/conf/catalina.properties file
  looks like this:

  Once you have configured the catalina.properties file for use
  with a SecurityManager, remember to re-start Tomcat.




  If your web application attempts to execute an operation that is
  prohibited by lack of a required Permission, it will throw an
  AccessControLException or a SecurityException
  when the SecurityManager detects the violation.  Debugging the permission
  that is missing can be challenging, and one option is to turn on debug
  output of all security decisions that are made during execution.  This
  is done by setting a system property before starting Tomcat.  The easiest
  way to do this is via the CATALINA_OPTS environment variable.
  Execute this command:
export CATALINA_OPTS=-Djava.security.debug=all    (Unix)
set CATALINA_OPTS=-Djava.security.debug=all       (Windows)

  before starting Tomcat.

  WARNING - This will generate many megabytes
  of output!  However, it can help you track down problems by searching
  for the word "FAILED" and determining which permission was being checked
  for.  See the Java security documentation for more options that you can
  specify here as well.