| <?xml version="1.0"?> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <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="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> |
| <% 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 5 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 5.</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://java.sun.com/security/">http://java.sun.com/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> |
| |
| |
| <subsection name="Tomcat Custom Permissions"> |
| |
| <p>Tomcat utilizes a custom permission class called |
| <strong>org.apache.naming.JndiPermission</strong>. 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:</p> |
| <source> |
| permission org.apache.naming.JndiPermission "jndi://localhost/examples/*"; |
| </source> |
| |
| <p>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).</p> |
| |
| <p>Also, Tomcat always dynamically creates the following file permission:</p> |
| <source> |
| permission java.io.FilePermission "** your application context**", "read"; |
| </source> |
| <p>Where **your application context** equals the folder(or WAR file) under which |
| your application has been deployed. </p> |
| |
| </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_HOME/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://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/policytool.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> |
| // 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> and |
| <code>CATALINA_HOME</code> environment variables).</p> |
| |
| <h3>The Default Policy File</h3> |
| |
| <p>The default <code>$CATALINA_HOME/conf/catalina.policy</code> file |
| looks like this:</p> |
| <source> |
| // ============================================================================ |
| // catalina.corepolicy - Security Policy Permissions for Tomcat 5 |
| // |
| // This file contains a default set of security policies to be enforced (by the |
| // JVM) when Catalina is executed with the "-security" option. In addition |
| // to the permissions granted here, the following additional permissions are |
| // granted to the codebase specific to each web application: |
| // |
| // * Read access to the document root directory |
| // |
| // $Id$ |
| // ============================================================================ |
| |
| |
| // ========== SYSTEM CODE PERMISSIONS ========================================= |
| |
| |
| // These permissions apply to javac |
| grant codeBase "file:${java.home}/lib/-" { |
| permission java.security.AllPermission; |
| }; |
| |
| // These permissions apply to all shared system extensions |
| grant codeBase "file:${java.home}/jre/lib/ext/-" { |
| permission java.security.AllPermission; |
| }; |
| |
| // These permissions apply to javac when ${java.home] points at $JAVA_HOME/jre |
| grant codeBase "file:${java.home}/../lib/-" { |
| permission java.security.AllPermission; |
| }; |
| |
| // These permissions apply to all shared system extensions when |
| // ${java.home} points at $JAVA_HOME/jre |
| grant codeBase "file:${java.home}/lib/ext/-" { |
| permission java.security.AllPermission; |
| }; |
| |
| |
| // ========== CATALINA CODE PERMISSIONS ======================================= |
| |
| |
| // These permissions apply to the launcher code |
| grant codeBase "file:${catalina.home}/bin/commons-launcher.jar" { |
| permission java.security.AllPermission; |
| }; |
| |
| // These permissions apply to the server startup code |
| grant codeBase "file:${catalina.home}/bin/bootstrap.jar" { |
| permission java.security.AllPermission; |
| }; |
| |
| // These permissions apply to the servlet API classes |
| // and those that are shared across all class loaders |
| // located in the "common" directory |
| grant codeBase "file:${catalina.home}/common/-" { |
| permission java.security.AllPermission; |
| }; |
| |
| // These permissions apply to the container's core code, plus any additional |
| // libraries installed in the "server" directory |
| grant codeBase "file:${catalina.home}/server/-" { |
| permission java.security.AllPermission; |
| }; |
| |
| // ========== WEB APPLICATION PERMISSIONS ===================================== |
| |
| |
| // These permissions are granted by default to all web applications |
| // In addition, a web application will be given a read FilePermission |
| // and JndiPermission for all files and directories in its document root. |
| grant { |
| // Required for JNDI lookup of named JDBC DataSource's and |
| // javamail named MimePart DataSource used to send mail |
| permission java.util.PropertyPermission "java.home", "read"; |
| permission java.util.PropertyPermission "java.naming.*", "read"; |
| permission java.util.PropertyPermission "javax.sql.*", "read"; |
| |
| // OS Specific properties to allow read access |
| permission java.util.PropertyPermission "os.name", "read"; |
| permission java.util.PropertyPermission "os.version", "read"; |
| permission java.util.PropertyPermission "os.arch", "read"; |
| permission java.util.PropertyPermission "file.separator", "read"; |
| permission java.util.PropertyPermission "path.separator", "read"; |
| permission java.util.PropertyPermission "line.separator", "read"; |
| |
| // JVM properties to allow read access |
| permission java.util.PropertyPermission "java.version", "read"; |
| permission java.util.PropertyPermission "java.vendor", "read"; |
| permission java.util.PropertyPermission "java.vendor.url", "read"; |
| permission java.util.PropertyPermission "java.class.version", "read"; |
| permission java.util.PropertyPermission "java.specification.version", "read"; |
| permission java.util.PropertyPermission "java.specification.vendor", "read"; |
| permission java.util.PropertyPermission "java.specification.name", "read"; |
| |
| permission java.util.PropertyPermission "java.vm.specification.version", "read"; |
| permission java.util.PropertyPermission "java.vm.specification.vendor", "read"; |
| permission java.util.PropertyPermission "java.vm.specification.name", "read"; |
| permission java.util.PropertyPermission "java.vm.version", "read"; |
| permission java.util.PropertyPermission "java.vm.vendor", "read"; |
| permission java.util.PropertyPermission "java.vm.name", "read"; |
| |
| // Required for getting BeanInfo |
| permission java.lang.RuntimePermission "accessClassInPackage.sun.beans.*"; |
| |
| // Required for OpenJMX |
| permission java.lang.RuntimePermission "getAttribute"; |
| |
| // Allow read of JAXP compliant XML parser debug |
| permission java.util.PropertyPermission "jaxp.debug", "read"; |
| }; |
| |
| |
| // You can assign additional permissions to particular web applications by |
| // adding additional "grant" entries here, based on the code base for that |
| // application, /WEB-INF/classes/, or /WEB-INF/lib/ jar files. |
| // |
| // Different permissions can be granted to JSP pages, classes loaded from |
| // the /WEB-INF/classes/ directory, all jar files in the /WEB-INF/lib/ |
| // directory, or even to individual jar files in the /WEB-INF/lib/ directory. |
| // |
| // For instance, assume that the standard "examples" application |
| // included a JDBC driver that needed to establish a network connection to the |
| // corresponding database and used the scrape taglib to get the weather from |
| // the NOAA web server. You might create a "grant" entries like this: |
| // |
| // The permissions granted to the context root directory apply to JSP pages. |
| // grant codeBase "file:${catalina.home}/webapps/examples/-" { |
| // permission java.net.SocketPermission "dbhost.mycompany.com:5432", "connect"; |
| // permission java.net.SocketPermission "*.noaa.gov:80", "connect"; |
| // }; |
| // |
| // The permissions granted to the context WEB-INF/classes directory |
| // grant codeBase "file:${catalina.home}/webapps/examples/WEB-INF/classes/-" { |
| // }; |
| // |
| // The permission granted to your JDBC driver |
| // grant codeBase "jar:file:${catalina.home}/webapps/examples/WEB-INF/lib/driver.jar!/-" { |
| // permission java.net.SocketPermission "dbhost.mycompany.com:5432", "connect"; |
| // }; |
| // The permission granted to the scrape taglib |
| // grant codeBase "jar:file:${catalina.home}/webapps/examples/WEB-INF/lib/scrape.jar!/-" { |
| // permission java.net.SocketPermission "*.noaa.gov:80", "connect"; |
| // }; |
| </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> |
| |
| </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 againts package definition and access. See |
| <a href="http://java.sun.com/security/seccodeguide.html"> |
| http://java.sun.com/security/seccodeguide.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_HOME/conf/catalina.properties</code> file |
| looks like this:</p> |
| <source> |
| # |
| # 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> |