Classloader

Element	Occurance	Description
permission	0..n	The permission descriptor.

Element

Occurance

Description

permission

0..n

The permission descriptor.

Element	Occurance	Description
action	0..n	The action descriptor.

Element

Occurance

Description

action

0..n

The action descriptor.

Attribute	Required	Description
class	yes	The name of the Permission class. This classname must be a subclass of the java.security.Permission class.
name	no	This is the first argument passed into the constructor. Most Permission classes calls this the "name" argument, but the has other names for certain permission classes, e.g. FilePermission calls it "path".

Attribute

Required

Description

class

yes

The name of the Permission class. This classname must be a subclass of the java.security.Permission class.

name

This is the first argument passed into the constructor. Most Permission classes calls this the "name" argument, but the has other names for certain permission classes, e.g. FilePermission calls it "path".

Name	Default	Description
Name	Default	Description	Since
urn:composition:deployment.timeout	5000	+ 3.2.5 +
urn:composition:security.enabled	false	+ This is a global switch for turning the code level security + on or off. For compatibility reasons, the default is false, + but any production system should have this true. In the + kernel.xml it is set to true, and for the debug.xml it is + set to false. +	+ 3.3 +

Name

Default

Description

Name

Default

Description

Since

urn:composition:deployment.timeout

5000

+ 3.2.5 +

urn:composition:security.enabled

false

+ This is a global switch for turning the code level security + on or off. For compatibility reasons, the default is false, + but any production system should have this true. In the + kernel.xml it is set to true, and for the debug.xml it is + set to false. +

+ 3.3 +

Starting from Merlin 3.3, it is possible to grant permissions to classes within a container. This is done by the declaration of a <grant> element in the classloader definition section in the block descriptor (e.g. block.xml).

In the example below you should be able to see the mechanism. The multiple <action> elements, instead of a single String value as is more common, was chosen for easier tool support while still allowing you to place multiple comma separated actions into a single <action> element, passed to the Permission constructor as-is.

read write read read write ]]>

There can only be a single <grant> for each <classloader> and any number of <permission> elements within.

If you are only looking for basic security, similar to any typical stand-alone application, that would depend on a Java Security Policy file, you don't need to do anything special. All classes in Java will perform the security checks behind the scenes, protecting files, network connection and many other system resources. Please refer to your Java Security documentation for full details.

If you want to guard some resource or a section of code, you will need to;

Create a subclass of java.security.Permission, or one of its subclasses such as java.lang.BasicPermission, and override the implies(), equals() and hashCode() methods.
Insert a AccessController.checkPermission() at the relevant points in your code. (See examples below.)

This first example uses a simple named RuntimePermission.

In this example, we utilizes the existing java.lang.RuntimePermission to do a very simple check, i.e is the current protection domain allowed to use the SuperGlue.

And to make this work in your Merlin application, you would need to insert the appropriate permission in the <grant> element.

]]>

If you need something more complicated that can not be fulfilled with the existing Permission classes, you will need to create your own. This can be rather tricky, depending on what you are actually trying to do.

In the example below, we have a Permission class that ensures that an amount is within its boundaries, for instance for a banking application. The semantics are;

The name argument for a granted permission (declared) contains a minimum value, followed by a dash and then followed by a maximum value.
The name argument for a required permission (programmatically) only contains a single value, which is the requested amount. The amount is expressed in cent, and no fractional numbers needed.
If any of the two values are missing, the default is used. The default is 1000000 for each.
The action argument contains either "deposit" or "withdrawal".
The granted permission must contain the action of the required permission, and the required permission's amount must be within the limits of the granted permission.

As we can see it is a fairly straight forward algorithm, but a bit hard to put in words, and I hope I haven't missed something. To do this with Java Security permissions is fairly easy.

0 ) return false; if( requesting.m_Minimum < m_Minimum ) return false; if( requesting.m_Minimum > m_Maximum ) return false; return true; } private void parseAmount( String amount ) { m_Minimum = 1000000; m_Maximum = 1000000; if( amount == null || "".equals( amount ) ) return; int dash = amount.indexOf( '-' ); if( dash < 0 ) { try { m_Minimum = Long.parseLong( amount ); } catch( NumberFormatException e ) {} // ignore, use default } else { String am1 = amount.substring( 0, dash ); String am2 = amount.substring( dash + 1 ); try { m_Minimum = Long.parseLong( am1 ); } catch( NumberFormatException e ) {} // ignore, use default try { m_Maximum = Long.parseLong( am2 ); } catch( NumberFormatException e ) {} // ignore, use default } } private void parseActions( String actions ) { // This should probably be done differently. m_Actions = 0; if( actions.indexOf( "withdrawal" ) ) m_Actions = 1; if( actions.indexOf( "deposit" ) ) m_Actions += 2; } } ]]>

Please note that the code has not yet been tested. If you do please post any mistake to dev@avalon.apache.org. Thank you.

Then in the actual code, we would do something like this;

Wasn't that easy? Well, it would have been if we could tie the principal customer/client/user to the protection domain that is checked. This is currently on the drawing board for Avalon Merlin, and will probably not be ready until version 4.0, somewhere mid or late 2004. While awaiting this Subject-based, generic, pluggable security system, you can hack the above example a little bit, for some basic subject driven security.

In the implies() method, you reach out and detect who is executing the current thread, for instance through a ThreadLocal variable, ask some authoritive object instance for the amounts allowed and perform the check. This is NOT the recommended method for larger and more complex system (such as banks), but can work as a temporary solution for the time being.