tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs security-manager-howto.xml index.xml project.xml
Date Sun, 09 Sep 2001 22:43:48 GMT
craigmcc    01/09/09 15:43:48

  Modified:    webapps/tomcat-docs index.xml project.xml
  Added:       webapps/tomcat-docs security-manager-howto.xml
  Log:
  Convert Glenn's "Using A Security Manager With Tomcat" to the new format.
  
  Revision  Changes    Path
  1.13      +4 -0      jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- index.xml	2001/09/09 00:48:11	1.12
  +++ index.xml	2001/09/09 22:43:48	1.13
  @@ -79,6 +79,10 @@
       passwords, and their associated roles) for use in web applications that
       utilize <em>Container Managed Security</em> (FIXME - hyperlink to
       background info on this).</li>
  +<li><a href="security-manager-howto.html"><strong>Security Manager
  +    HOW-TO</strong></a> - Configuring and using a Java Security Manager to
  +    support fine-grained control over the behavior of your web applications.
  +    </li>
   <li><a href="ssl-howto.html"><strong>SSL Configuration HOW-TO</strong></a>
-
       Installing and
       configuring SSL support so that your Tomcat will serve requests using
  
  
  
  1.13      +1 -0      jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- project.xml	2001/09/09 00:48:11	1.12
  +++ project.xml	2001/09/09 22:43:48	1.13
  @@ -29,6 +29,7 @@
           <item name="Manager App HOW-TO"    href="manager-howto.html"/>
           <item name="Proxy Support HOW-TO"  href="proxy-howto.html"/>
           <item name="Realm HOW-TO"          href="realm-howto.html"/>
  +        <item name="Security Mgr. HOW-TO"  href="security-manager-howto.html"/>
           <item name="SSL Config HOW-TO"     href="ssl-howto.html"/>
       </menu>
   
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/security-manager-howto.xml
  
  Index: security-manager-howto.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
      &project;
  
      <properties>
          <author email="glenn@voyager.apg.more.net">Glenn Nielsen</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>
  &lt;% System.exit(1); %&gt;
  </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> - Implementation of a SecurityManager in
    Tomcat has not been fully tested or had a security audit.  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.</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 4.</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>.</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>
  
    </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 &lt;signer&gt;,] [codeBase &lt;code source&gt;] {
    permission  &lt;class&gt;  [&lt;name&gt; [, &lt;action list&gt;]];
  };
  </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 4.0
  //
  // 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: security-manager-howto.xml,v 1.1 2001/09/09 22:43:48 craigmcc Exp $
  // ============================================================================
  
  
  // ========== 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 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;
  };
  
  // These permissions apply to the jasper page compiler
  // located in the "jasper" directory.
  grant codeBase "file:${catalina.home}/jasper/-" {
          permission java.security.AllPermission;
  };
  
  // These permissions apply to shared web application libraries
  // including the Jasper runtime library installed in the "lib" directory
  grant codeBase "file:${catalina.home}/lib/-" {
          permission java.security.AllPermission;
  };
  
  // These permissions apply to shared web application classes
  // located in the "classes" directory
  grant codeBase "file:${catalina.home}/classes/-" {
          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.*";
  
  	// 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 "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 "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="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>
  
  
  

Mime
View raw message