glenn 01/06/26 14:00:31
Modified: catalina/docs tomcat-security.html
Log:
Updated documentation for JndiPermission, merged in docs from separate
tomcat-security-unix.html
Revision Changes Path
1.2 +245 -7 jakarta-tomcat-4.0/catalina/docs/tomcat-security.html
Index: tomcat-security.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/tomcat-security.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tomcat-security.html 2001/02/03 16:41:09 1.1
+++ tomcat-security.html 2001/06/26 21:00:30 1.2
@@ -1,9 +1,9 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
- <title>Using the Java SecurityManager with Tomcat</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; I; SunOS 5.7 i86pc)
[Netscape]">
+ <title>Using the Java SecurityManager with Tomcat</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#FF0000"
alink="#000088">
@@ -23,8 +23,18 @@
<li>
<a href="#permissions">Types of Permissions</a></li>
+<li>
+<a href="#custom">Tomcat Custom Permissions</a></li>
+
+<li>
+<a href="#config">Configuring Tomcat for use with a SecurityManager</a></li>
+
+<li>
+<a href="#start">Starting Tomcat with a SecurityManager</a></li>
+
<li>
-<a href="tomcat-security-unix.html">Tomcat SecurityManager setup with Unix</a></li>
+<a href="#trouble">Trouble shooting catalina.policy configuration and Security
+Violations</a></li>
<li>
<a href="#violation">What happens when the SecurityManager detects a Security
@@ -57,9 +67,9 @@
<h3>
<a NAME="precautions"></a>Precautions</h3>
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, JSP's, servlets, beans, or tag libraries.
+or had a security audit. Make sure that you are satisfied with your SecurityManager
+configuration before allowing untrusted users to publish web applications,
+JSP's, servlets, beans, or tag libraries.
<p>Still, running with a SecurityManager is definitely better than running
without one.
<br>
@@ -70,8 +80,8 @@
of the JDK and you can even create your own Permission class for use in
your own web applications.
<p>This is just a short summary of the System SecurityManager Permission
-classes applicable to Tomcat. Please refer to the JDK documentation
-for more information on using the below Permissions.
+classes applicable to Tomcat. Please refer to <a
href="http://java.sun.com/security/";>http://java.sun.com/security/</a>
+for more information on using the Java SecurityManager and the below Permissions.
<p><b>java.util.PropertyPermission</b>
<br> Controls read/write access to JVM properties such
as java.home.
@@ -93,6 +103,234 @@
<br> Allows access to all permissions, just as if you
were running Tomcat without a SecurityManager.
<br>
+<h2>
+<a NAME="custom"></a>Tomcat Custom Permissions</h2>
+Tomcat provides a custom permission class called
<b>org.apache.naming.JndiPermission</b>,
+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 pattern matching for a JNDI named
+file resource when granting permission.
+<p>Example:
+<p> <tt>permission org.apache.naming.JndiPermission
"jndi://localhost/examples/*";</tt>
+<br><tt></tt>
+<h3>
+<a NAME="config"></a>Configuring Tomcat for use with a SecurityManager</h3>
+<b>catalina.policy</b>
+<p>The security policies implemented by the Java SecurityManager are configured
+in the <tt>catalina.policy</tt> file located in the tomcat <tt>conf</tt>
+directory. The <tt>catalina.policy</tt> file replaces any system
+<tt>java.policy</tt>
+file. The
+<tt>catalina.policy</tt> 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.
+<p>Entries in the <tt>catalina.policy</tt> file use the standard
<tt>java.policy</tt>
+file format as follows:
+<table BORDER=0 CELLPADDING=8 WIDTH="95%" BGCOLOR="#EEEEEE" >
+<tr>
+<td>
+<pre>// Example policy file entry
+
+grant [signedBy <signer> [,codeBase <code source>] {
+ permission <class> [<name> [, <action list>]];
+};</pre>
+</td>
+</tr>
+</table>
+The <b>signedBy</b> and <b>codeBase </b>entries are optional when granting
+permissions. Comment lines begin with <tt>//</tt> and end at a new line.
+<p>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.
+<p>Default catalina.policy file
+<table BORDER=0 CELLPADDING=8 WIDTH="95%" BGCOLOR="#EEEEEE" >
+<tr>
+<td>
+<pre>// ============================================================================
+// 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: tomcat-security.html,v 1.2 2001/06/26 21:00:30 glenn 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.utim.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
+//
+// Permissions granted to a web applications /WEB-INF/classes
+// need to use the JNDI naming convention Tomcat 4 uses to identify
+// these resources. The naming convention is
+// "jndi:/<virtual host name>/<web application directory>/WEB-INF/classes/
+//
+// grant codeBase "jndi:/localhost/examples/WEB-INF/classes/-" {
+// };
+//
+// Permissions granted to a web applications /WEB-INF/lib
+// need to use the JNDI naming convention Tomcat 4 uses to identify
+// these resources. The naming convention is
+// "jar:jndi:/<virtual host name>/<web application directory>/WEB-INF/lib/
+//
+// The permission granted to your JDBC driver
+// grant codeBase "jar:jndi:/localhost/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:jndi:localhost/webapps/examples/WEB-INF/lib/scrape.jar" {
+// permission java.net.SocketPermission
"*.noaa.gov:80", "connect";
+// };</pre>
+</td>
+</tr>
+</table>
+
+<h3>
+<a NAME="start"></a>Starting Tomcat with a SecurityManager</h3>
+Once you have configured the catalina.policy file for use with a SecurityManager,
+Tomcat can be started with the SecurityManager in place by using the "-security"
+option to bin/startup.sh.
+<br>
+<h2>
+<a NAME="trouble"></a>Trouble shooting catalina.policy configuration and
+Security Violations</h2>
+You can turn on Java SecurityManager debug logging by settting the environmental
+variable <tt>CATALINA_OPTS=-Djava.security.debug=all</tt>. You will find
+the debug output in the log file <tt>logs/catalina.out</tt>.
+<br>This generates many MB's of output, for more verbose security debug
+output use <tt>CATALINA_OPTS=-Djava.security.debug=access,failure.
+Use the following shell command to determine all the security debug options
+available: java -Djava.security.debug=help</tt>
<h3>
<a NAME="violation"></a>What happens when the SecurityManager detects a
Security violation?</h3>
