251 lines
10 KiB
XML
251 lines
10 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
<!DOCTYPE document [
|
|
<!ENTITY project SYSTEM "project.xml">
|
|
<!ENTITY defaultpolicy SYSTEM "../../conf/catalina.policy">
|
|
]>
|
|
<document url="security-manager-howto.html">
|
|
|
|
&project;
|
|
|
|
<properties>
|
|
<author email="glenn@voyager.apg.more.net">Glenn Nielsen</author>
|
|
<author email="jeanfrancois.arcand@sun.com">Jean-Francois Arcand</author>
|
|
<title>Security Manager How-To</title>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<section name="Table of Contents">
|
|
<toc/>
|
|
</section>
|
|
|
|
<section name="Background">
|
|
|
|
<p>The Java <strong>SecurityManager</strong> 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.</p>
|
|
|
|
<p>Imagine if someone who is authorized to publish JSPs on your site
|
|
inadvertently included the following in their JSP:</p>
|
|
<source><![CDATA[<% System.exit(1); %>]]></source>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><strong>WARNING</strong> - 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. <strong>However, running with a
|
|
SecurityManager is definitely better than running without one.</strong></p>
|
|
|
|
</section>
|
|
|
|
|
|
<section name="Permissions">
|
|
|
|
<p>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.</p>
|
|
|
|
|
|
<subsection name="Standard Permissions">
|
|
|
|
<p>This is just a short summary of the standard system SecurityManager
|
|
Permission classes applicable to Tomcat. See
|
|
<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/">
|
|
http://docs.oracle.com/javase/7/docs/technotes/guides/security/</a>
|
|
for more information.</p>
|
|
|
|
<ul>
|
|
<li><strong>java.util.PropertyPermission</strong> - Controls read/write
|
|
access to JVM properties such as <code>java.home</code>.</li>
|
|
<li><strong>java.lang.RuntimePermission</strong> - Controls use of
|
|
some System/Runtime functions like <code>exit()</code> and
|
|
<code>exec()</code>. Also control the package access/definition.</li>
|
|
<li><strong>java.io.FilePermission</strong> - Controls read/write/execute
|
|
access to files and directories.</li>
|
|
<li><strong>java.net.SocketPermission</strong> - Controls use of
|
|
network sockets.</li>
|
|
<li><strong>java.net.NetPermission</strong> - Controls use of
|
|
multicast network connections.</li>
|
|
<li><strong>java.lang.reflect.ReflectPermission</strong> - Controls
|
|
use of reflection to do class introspection.</li>
|
|
<li><strong>java.security.SecurityPermission</strong> - Controls access
|
|
to Security methods.</li>
|
|
<li><strong>java.security.AllPermission</strong> - Allows access to all
|
|
permissions, just as if you were running Tomcat without a
|
|
SecurityManager.</li>
|
|
</ul>
|
|
|
|
</subsection>
|
|
|
|
</section>
|
|
|
|
|
|
<section name="Configuring Tomcat With A SecurityManager">
|
|
|
|
<h3>Policy File Format</h3>
|
|
|
|
<p>The security policies implemented by the Java SecurityManager are
|
|
configured in the <code>$CATALINA_BASE/conf/catalina.policy</code> file.
|
|
This file completely replaces the <code>java.policy</code> file present
|
|
in your JDK system directories. The <code>catalina.policy</code> file
|
|
can be edited by hand, or you can use the
|
|
<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/PolicyGuide.html">policytool</a>
|
|
application that comes with Java 1.2 or later.</p>
|
|
|
|
<p>Entries in the <code>catalina.policy</code> file use the standard
|
|
<code>java.policy</code> file format, as follows:</p>
|
|
<source><![CDATA[// Example policy file entry
|
|
|
|
grant [signedBy <signer>,] [codeBase <code source>] {
|
|
permission <class> [<name> [, <action list>]];
|
|
};]]></source>
|
|
|
|
<p>The <strong>signedBy</strong> and <strong>codeBase</strong> entries are
|
|
optional when granting permissions. Comment lines begin with "//" and
|
|
end at the end of the current line. The <code>codeBase</code> is in the
|
|
form of a URL, and for a file URL can use the <code>${java.home}</code>
|
|
and <code>${catalina.home}</code> properties (which are expanded out to
|
|
the directory paths defined for them by the <code>JAVA_HOME</code>,
|
|
<code>CATALINA_HOME</code> and <code>CATALINA_BASE</code> environment
|
|
variables).</p>
|
|
|
|
<h3>The Default Policy File</h3>
|
|
|
|
<p>The default <code>$CATALINA_BASE/conf/catalina.policy</code> file
|
|
looks like this:</p>
|
|
|
|
<!-- The following pulls in the conf/catalina.policy file when the
|
|
documentation is built -->
|
|
<source>&defaultpolicy;</source>
|
|
|
|
<h3>Starting Tomcat With A SecurityManager</h3>
|
|
|
|
<p>Once you have configured the <code>catalina.policy</code> file for use
|
|
with a SecurityManager, Tomcat can be started with a SecurityManager in
|
|
place by using the "-security" option:</p>
|
|
<source>$CATALINA_HOME/bin/catalina.sh start -security (Unix)
|
|
%CATALINA_HOME%\bin\catalina start -security (Windows)</source>
|
|
|
|
<subsection name="Permissions for packed WAR files">
|
|
|
|
<p>When using packed WAR files, it is necessary to use Tomcat's custom war
|
|
URL protocol to assign permissions to web application code.</p>
|
|
|
|
<p>To assign permissions to the entire web application the entry in the
|
|
policy file would look like this:</p>
|
|
|
|
<source><![CDATA[// Example policy file entry
|
|
grant codeBase "war:file:${catalina.base}/webapps/examples.war*/-" {
|
|
...
|
|
};
|
|
]]></source>
|
|
|
|
<p>To assign permissions to a single JAR within the web application the
|
|
entry in the policy file would look like this:</p>
|
|
|
|
<source><![CDATA[// Example policy file entry
|
|
grant codeBase "war:file:${catalina.base}/webapps/examples.war*/WEB-INF/lib/foo.jar" {
|
|
...
|
|
};
|
|
]]></source>
|
|
|
|
</subsection>
|
|
|
|
</section>
|
|
|
|
<section name="Configuring Package Protection in Tomcat">
|
|
<p>Starting with Tomcat 5, it is now possible to configure which Tomcat
|
|
internal package are protected against package definition and access. See
|
|
<a href="http://www.oracle.com/technetwork/java/seccodeguide-139067.html">
|
|
http://www.oracle.com/technetwork/java/seccodeguide-139067.html</a>
|
|
for more information.</p>
|
|
|
|
|
|
<p><strong>WARNING</strong>: Be aware that removing the default package protection
|
|
could possibly open a security hole</p>
|
|
|
|
<h3>The Default Properties File</h3>
|
|
|
|
<p>The default <code>$CATALINA_BASE/conf/catalina.properties</code> file
|
|
looks like this:</p>
|
|
<source><![CDATA[#
|
|
# 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.]]></source>
|
|
<p>Once you have configured the <code>catalina.properties</code> file for use
|
|
with a SecurityManager, remember to re-start Tomcat.</p>
|
|
</section>
|
|
|
|
<section name="Troubleshooting">
|
|
|
|
<p>If your web application attempts to execute an operation that is
|
|
prohibited by lack of a required Permission, it will throw an
|
|
<code>AccessControLException</code> or a <code>SecurityException</code>
|
|
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 <code>CATALINA_OPTS</code> environment variable.
|
|
Execute this command:</p>
|
|
<source>export CATALINA_OPTS=-Djava.security.debug=all (Unix)
|
|
set CATALINA_OPTS=-Djava.security.debug=all (Windows)</source>
|
|
|
|
<p>before starting Tomcat.</p>
|
|
|
|
<p><strong>WARNING</strong> - This will generate <em>many megabytes</em>
|
|
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.</p>
|
|
|
|
</section>
|
|
|
|
|
|
</body>
|
|
|
|
</document>
|