| <?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> |