	Using the Java SecurityManager with Tomcat

Why use a SecurityManager?
--------------------------

The Java SecurityManager is what allows your browser to run an applet
in its own sandbox to prevent untrusted code from accessing files
on your 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 inadvertant mistakes.

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

<% System.exit(1); %>

Everytime 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, and 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 documenation 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
-------------------------------------------------

conf/tomcat.policy

Used to configure global Permissions for java packages installed
in classpaths searchable by the JVM and for specifying default
Permissions for classes loaded from other sources.  This is not
where Permissions are configured for web application Context's.

There should be entries with a codeBase of "file:${java.home}/lib/ext/-"
and "file:${tomcat.home}/lib/-" which grant AllPermissions.

And a default grant entry with no codeBase which has very
restrictive Permissions configured.

Edit the conf/tomcat.policy file and replace ${tomcat.home} with
the path to your Tomcat home directory.

The tomcat.policy file replaces any system java.policy file.

conf/server.xml.security

This is an example server.xml file with a SecurityManager and Permissions
configured.  You can use this as a starting point for configuring
your own Permissions.

There are two elements you can use to configure Security and Permissions
in server.xml.

<SecurityManager className="java.security.SecurityManager">
	<Permission className="java.lang.RuntimePermission" attribute="stopThread"/>
	<Permission className="java.util.PropertyPermission" attribute="java.version" value="read"/>
</SecurityManager>

If Tomcat is started with -security, the above element is used to
contain the default Permissions given to web application Context's.
The JVM java.security.SecurityManager will be used by default as
the SecurityManager unless you define an alternate SecurityManager
using the className attribute.

In addition to the Permissions you define above, the web application
will be given a FilePermission "read" access to its docBase.

To override the default Permissions given to a web application as
configured in the SecurityManager element use the Permission element
within the Context element you want to assign a different Permission
set.

<Context path="/examples" docBase="webapps/examples" debug="0" reloadable="true" >
	<Permission className="java.io.FilePermission" attribute="/usr/local/tomcat/webapps/examples/-" value="read"/>
	<Permission className="java.util.PropertyPermission" attribute="java.version" value="read" />
</Context>

You must assign Permissions you want to grant including FilePermission's
when configuring Permissions in a Context.

You might configure Permissions for a Context when you want to grant
a different Permission set from the default configured using the
SecurityManager element.

The Permission element requires that the className for the Permission
class be configured and that the attribute be configured.  The value
is optional.  These attributes and values match the arguments passed
to the constructor for each type of Permission.

The above SecurityManager and Permission configurations will be 
ignored if Tomcat is started without the "-security" option.

Starting Tomcat with a SecurityManager
--------------------------------------

Once you have configured the tomcat.policy and server.xml
files for use with a SecurityManager, Tomcat can be started
with the SecurityManager in place by using the "-security"
opton to bin/startup.bat or bin/startup.sh.

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.
