Difference between revisions of "Jetty/Tutorial/Jetty-Policy"

Revision as of 16:10, 7 April 2011

Introduction

Jetty Policy provides a mechanism for integrating with the core JDK security mechanisms.

Details

Do I need this?

Typically users do not need to deal with java security permissions or what is called the SecurityManager or Policy objects in java. Normally a user trusts the application they are developing or are trusting enough to deploy a webapp into an instance of jetty. If you don't know that you need to use the security manager setup, you probably don't.

However, if you are running untrusted webapps and you want to gain a bit more control over the application this is an option. Using the Jetty policy setup allows you to declaratively specify permissions that jetty and the webapp will operate under. These permissions can be FilePermissions restricting read and write access, to PropertyPermissions which detail what system properties are available to be read.

How does it all work?

An excellent reference is available at Oracle -> http://download.oracle.com/javase/6/docs/technotes/guides/security/permissions.html

But beyond that we have made a few changes to make dealing with this system a bit easier. This involves our own subclass of the Policy object that allows for multiple policy files to be loaded and aggregated together for easier management. There is a debug mode and dump() method for the jetty policy that will all cached protection domains to be printed out. There is a reload mode that allows changes to the policy files to be loaded and changes to protection domains resolve while the security manager is running.

In broad strokes, when jetty is started the SecurityManager and JettyPolicy objects are loaded so that from then on all security sensitive actions are taken, the entire call stack of code up to that point is checked to validate that every object has been granted that permission. This will be explained in greater detail below.

Jetty Policy

Typically the JettyPolicy object is configured through the use of policy files that adhere to the specification laid out by Sun/Oracle in the link in the previous section. We have expanded on this a bit to make it easier to manage these files. To understand the layout it is important to understand what a codesource is. In java security land, a codesource is simply a location where classes can be found. A codesource can be specified to a specific location on disk or it can refer to a directory where jar files or class files are located. The binding of specific permissions to a codesource is referred to as a protection domain.

We have broken out our policy files along the following lines. It should be noted that this is just how we have laid out the files, you are free to alter as desired.

lib/policy/global.policy

permissions that are applied to all protection domains

lib/policy/jetty-start.policy 

permissions which apply to start.jar and immediate startup of jetty

lib/policy/jetty.policy 

permissions that apply to jetty as a whole, and any jar files under the lib directory

lib/policy/temp-dirs.policy 

permission that apply to the contents of tmp directories, this can include unpacked webapps unless you follow the recommended conventions

lib/policy/jetty-work.policy 

permissions that apply to webapps unpacked to the work directory.

Adding and removing permissions required a lot of in-depth knowledge about how whatever java code your running operates and it is no different with jetty or webapps running inside of jetty, it is just a little more complex.

Web Application Policies

A common concern with dealing with this sort of system is how to grant permissions to one webapp without having to grant permissions to another. For this approach we recommend something along the following lines:

• use context deployment so you can specify where your war file will unpack to
• create a policy file in lib/policy for that webapp
  • this policy file should contain two codebases
    • ${jetty.home}/work/<webapp dir>
    • ${jetty.home}/lib/-
  • this allows you to grant both the webapp and jetty itself any permissions needed

Remember that when permission is checked for any call, the entire call stack is checked for permission being granted. What this means in practice is that if you are granting permission to read and write directory A, then both the webapp classes and the jetty classes have to be granted access to read and write that directory. What having per webapp permissions setup allows you is the ability to _not_ grant another webapp read and write access to that directory. This could be potentially important if your running untrusted webapps, or some combination of trusted and untrusted webapps. Below is an example of what a typical webapp policy file might look like.

//
// Permissions granted to the webapp
//
grant codebase "file:${jetty.home}/work/policy-tests/-" {
  // testSystemPropertyAccess
  permission java.util.PropertyPermission "__ALLOWED_READ_PROPERTY", "read";
  permission java.util.PropertyPermission "__ALLOWED_WRITE_PROPERTY", "write";
}
 
//
// Permissions granted to jetty lib
//
grant codeBase "file:${jetty.home}/lib/-" {
   // testSystemPropertyAccess
  permission java.util.PropertyPermission "__ALLOWED_READ_PROPERTY", "read";
  permission java.util.PropertyPermission "__ALLOWED_WRITE_PROPERTY", "write";
}

Additional Resources

Insert more here.