java container banner

Java Container

This library makes creation of execution containers for your application very easy and painless.
My Mug

All source code is released under : Apache License V2
Latest release and changes : WHATSNEW
Installation instructions : INSTALL

If you feel generous, donate and be honored forever : Donate
If you feel like business, sign up a maintenance contract and be privileged : Sign-Up
If you feel cool, buy a t-shirt and make a statement : T-shirt
If you feel like hacking, send me a patch : Submit patch
If you feel nothing like it don't panic, drink water and hangover will soon be over

Executing Java code in constrained environment is relatively straight forward task using Java Security API. It actually boils down to two thinks:
  • Enabling upon startup of your application
  • Executing the constrained code via method
The tricky part here is dealing with the permissions.

Java Applets and Java WebStart are two great examples of running code in constrained environment. But both are separate executable binaries, they are not java.
In order to get normal Java applications operate in constrained environment one has to enable the security manager and provide a policy file<some url> upon JVM startup.

But these permissions are global i.e. they will be valid for any code running within that same JVM.

Now, how about if you have some unknown code you want to run from your application?
Apparently the code should be executed in a constrained environment (in order to protect yourself).

Security manager would allow you to do that. This is the easy part.
The problem comes with the assembling of permission sets. You'd have to do that manually.
Why? Because there is no interface able to read policy files at your disposal.
The only available is built-in in Sun's security framework and there is no publicly available interface.

For addressing this and few more problems, this library is.

Using the library is rather straight forward:
	import net.sf.container.Container;
	import net.sf.container.imp.CodebaseFactory;

	URL policyUrl = new URL( "file://myPermissions.policy" );
	CodebaseFactory factory = new CodebaseFactory( policyURL );

	Container sandbox = factory.newContainer( "file://no.domain/sandbox" );

	Runnable myAction = ...;
	sandbox.doPrivileged( myAction );
where "file://myPermissions.policy" content is:
	grant codeBase "file://no.domain/sandbox" {
	  permission java.util.PropertyPermission "java.version", "read";

	grant codeBase "file://${java.home}/no.domain/trusted" {
	  permission java.util.PropertyPermission "java.path", "read";
	  permission java.util.PropertyPermission "java.version", "read";
would result in executing "myAction" in constrained environment of type "sandbox".
Passing different codebase
factory.newContainer( "file://no.domain/sandbox" )
would result in executing myAction in "trusted" type of environment.

In order to

Container objects are abstracting execution of custom code in a constrained environment. The exact set of permissions is defined during their instantiation.

ContainerFactory objects are abstracting creation of Container objects in a configurable manner.
Typically they are instantiated with an input policy file, outlining all permission sets one would need.
One can instantiate a varying set of Container object by passing various permissionsCriteria to
ContainerFactory.newContainer(Object permissionsCriteria)
. Actual rules how these permissions will vary depends on the particular ContainerFactory implementation.
Currently available are net.sf.container.imp.CodebaseFactory and net.sf.container.imp.CertificateAuthorityFactory implementations.

PolicyParser objects are abstracting parsing of various policy-file formats.
As Java Security Policy file format presumably would not be the only one file format to express policy rules, implementing this interface would integrate it within the library.
Currently available is net.sf.container.imp.PolicyFileParser implementation.

©2006-2007 Nikolay Fiykov SourceForge