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:

<% System.exit(1); %>

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.

Tomcat utilizes a custom permission class called
org.apache.naming.JndiPermission. This permission
controls read access to JNDI named file based resources. The permission
name is the JNDI name and there are no actions. A trailing "*" can be
used to do wild card matching for a JNDI named file resource when
granting permission. For example, you might include the following
in your policy file:

A Permission entry like this is generated dynamically for each web
application that is deployed, to allow it to read its own static resources
but disallow it from using file access to read any other files (unless
permissions for those files are explicitly granted).

Where **your application context** equals the folder (or WAR file) under which
your application has been deployed and **application working directory** is the
temporary directory provided to your application as required by the
Servlet Specification.

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:

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 Properties File

#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageAccess unless the
# corresponding RuntimePermission ("accessClassInPackage."+package) has
# been granted.
package.access=sun.,org.apache.catalina.,org.apache.coyote.,org.apache.tomcat.,
org.apache.jasper.
#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageDefinition unless the
# corresponding RuntimePermission ("defineClassInPackage."+package) has
# been granted.
#
# by default, no packages are restricted for definition, and none of
# the class loaders supplied with the JDK call checkPackageDefinition.
#
package.definition=sun.,java.,org.apache.catalina.,org.apache.coyote.,
org.apache.tomcat.,org.apache.jasper.

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:

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.