<document>
<header>
  <product>resin</product>
  <title>Security Manager with Resin</title>
  <description>
<p>In ISP environments, it's important that each user have 
restricted permissions to use the server.  Normally, the
web server will be run as a non-root user so the users can't
read system files, but that user will still have read access.  The use of RMI
also requires a security manager.</p>

<p>Don't use a security manager if you're not in an ISP environment or
using RMI.  There's no need for it and the security manager does slow the
server down somewhat.</p>
</description>
</header>

<body>
<summary/>

<p>Adding a Java security manager puts each web-app into a
"sandbox" where Java limits the things that can be done from code
within th web-app.</p>

<p>The security manager is enabled by adding a <a
config-tag="security-manager"/> tag in the resin.conf.</p>

<example title="enabling security-manager in resin.conf">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core"&gt;

  &lt;security-manager/&gt;

  ...
</example>

<section title="java.policy">
<p>The security manager determines a <var/policy/> that applies to the current
virtual machine.  The security manager is controlled by policy file's.</p>

The simplest way to change the policy  is to change one of the default 
policy file's.  There are two default policy files that are used by the JDK:

<def>
${'${'}java.home}/lib/security/java.policy
${'${'}user.home}/.java.policy
</def>

<p>
An additional policy file can be set using the <code/java.security.policy/>
system property at the command line: 
</p>

<example>
unix$ bin/httpd.sh -Djava.security.policy=<i>file:/path/to/java.policy</i>
win$ bin/httpd.exe -Djava.security.policy=<i>file:/path/to/java.policy</i>
</example>

<p>
The resulting policy for the virtual machine is the union of all granted
permissions in all policy files. 
</p>

</section>

<section title="java.policy syntax">

<p>A useful resource is Sun's <a href="external|sun|security">documentation
about security</a>, in particular the <a
href="external|sun|security/permissions">policy permissions</a> and <a
href="external|sun|security/policyfiles">policy file syntax</a> files are
useful.</p>

<p>Each web-app automatically has permissions to read, write and
delete any file under the web-app's directory, including WEB-INF.  It
also has read permission for the classpath, including &lt;classpath>
from the &lt;host> and &lt;server> contexts.</p>

<example title="sample java.policy">
#
# Permissions allowed for everyone.
#
grant {
  permission java.util.PropertyPermission "*", "read";
  permission java.lang.RuntimePermission "accessClassInPackage.*";
  permission java.net.SocketPermission "mysql.myhost.com:3306" "connect";
  permission java.io.FilePermission "/opt/resin/xsl/*", "read";
};

#
# Give the system and Resin classes all permissions
#
grant codeBase "file:${'${'}resin.home}/lib/-" {
	permission java.security.AllPermission;
};

grant codeBase "file:${'${'}java.home}/lib/-" {
	permission java.security.AllPermission;
};

grant codeBase "file:${'${'}java.home}/jre/lib/-" {
	permission java.security.AllPermission;
};

#
# Give a specific web-app additional permissions.
#
grant codeBase "file:/opt/web/webapps/ejb/WEB-INF/-" {
	permission java.io.FilePermission "/opt/web/doc/*", "read";
};
</example>
</section>

</body>
</document>
