JBoss, a division of Red HatJBoss.org - Community driven.
User Guide
Docs Home
Introduction
Setup
System Properties
First webapp
Deployer
Manager
Realms and AAA
Security Manager
JNDI Resources
JDBC DataSources
Classloading
JSPs
SSL
PHP
SSI
CGI
URL Rewriting
Proxy Support
MBean Descriptor
Default Servlet
Connectors
Monitoring and Management
Logging
APR
Virtual Hosting
Advanced IO
JBoss Web Development
Building
Changelog
Architecture
Functional Specs.
Legal
Reference
Release Notes
Configuration
Javadocs
JK 1.2 Documentation
Tomcat FAQ
Printer Friendly Version

Security Manager HOW-TO

Background

The Java SecurityManager 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 JBoss Web can protect your server from trojan servlets, JSPs, JSP beans, and tag libraries. Or even inadvertent mistakes.

Imagine if someone who is authorized to publish JSPs on your site inadvertently included the following in their JSP:

<% System.exit(1); %>

Every time this JSP was executed by JBoss Web, JBoss Web 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.

WARNING - 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. However, running with a SecurityManager is definitely better than running without one.

Permissions

Permission classes are used to define what Permissions a class loaded by JBoss Web 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 JBoss Web.

Standard Permissions

This is just a short summary of the standard system SecurityManager Permission classes applicable to JBoss Web. See http://java.sun.com/security/ for more information.

  • 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(). Also control the package access/definition.
  • 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 JBoss Web without a SecurityManager.

JBoss Web Custom Permissions

JBoss Web utilizes a custom permission class called org.apache.naming.JndiPermission. 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:

permission  org.apache.naming.JndiPermission  "jndi://localhost/examples/*";

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).

Also, JBoss Web always dynamically creates the following file permission:

  
permission java.io.FilePermission "** your application context**", "read";

Where **your application context** equals the folder(or WAR file) under which your application has been deployed.

Configuring JBoss Web With A SecurityManager

Policy File Format

The security policies implemented by the Java SecurityManager are configured in the $CATALINA_HOME/conf/catalina.policy file. This file completely replaces the java.policy file present in your JDK system directories. The catalina.policy file can be edited by hand, or you can use the policytool application that comes with Java 1.2 or later.

Entries in the catalina.policy file use the standard java.policy file format, as follows:

// Example policy file entry

grant [signedBy <signer>,] [codeBase <code source>] {
  permission  <class>  [<name> [, <action list>]];
};

The signedBy and codeBase entries are optional when granting permissions. Comment lines begin with "//" and end at the end of the current line. The codeBase is in the form of a URL, and for a file URL can use the ${java.home} and ${catalina.home} properties (which are expanded out to the directory paths defined for them by the JAVA_HOME and CATALINA_HOME environment variables).

The Default Policy File

The default $CATALINA_HOME/conf/catalina.policy file looks like this:

// ============================================================================
// catalina.corepolicy - Security Policy Permissions for JBoss Web
//
// 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 512 2008-03-17 16:52:59Z jfrederic.clere@jboss.com $
// ============================================================================


// ========== 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 daemon code
grant codeBase "file:${catalina.home}/bin/commons-daemon.jar" {
        permission java.security.AllPermission;
};

// These permissions apply to the logging API
grant codeBase "file:${catalina.home}/bin/tomcat-juli.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 "lib" directory
grant codeBase "file:${catalina.home}/lib/-" {
        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 OpenJMX
    permission java.lang.RuntimePermission "getAttribute";

	// Allow read of JAXP compliant XML parser debug
	permission java.util.PropertyPermission "jaxp.debug", "read";

    // Precompiled JSPs need access to this package.
    permission java.lang.RuntimePermission "accessClassInPackage.org.apache.jasper.runtime";
    permission java.lang.RuntimePermission "accessClassInPackage.org.apache.jasper.runtime.*";
    
};


// 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";
// };

Starting JBoss Web With A SecurityManager

Once you have configured the catalina.policy file for use with a SecurityManager, JBoss Web can be started with a SecurityManager in place by using the "-security" option:

$CATALINA_HOME/bin/catalina.sh start -security    (Unix)
%CATALINA_HOME%\bin\catalina start -security      (Windows)

Configuring Package Protection in JBoss Web

Starting with Tomcat 5, it is now possible to configure which JBoss Web internal package are protected againts package definition and access. See http://java.sun.com/security/seccodeguide.html for more information.

WARNING: Be aware that removing the default package protection could possibly open a security hole

The Default Properties File

The default $CATALINA_HOME/conf/catalina.properties file looks like this:

  
#
# 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.

Once you have configured the catalina.properties file for use with a SecurityManager, remember to re-start JBoss Web.

Troubleshooting

If your web application attempts to execute an operation that is prohibited by lack of a required Permission, it will throw an AccessControLException or a SecurityException 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 JBoss Web. The easiest way to do this is via the CATALINA_OPTS environment variable. Execute this command:

export CATALINA_OPTS=-Djava.security.debug=all    (Unix)
set CATALINA_OPTS=-Djava.security.debug=all       (Windows)

before starting JBoss Web.

WARNING - This will generate many megabytes 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.

© 1999-2007, Apache Software Foundation. © 2007-2008 Red Hat Middleware, LLC. All Rights Reserved.