THE MELCOE PDP

The Melcoe PDP is a stand alone web service that provides a Policy Decision Point. It also provides a facility for the storage, indexing and management of policies.

The default policy store for the Melcoe PDP is a Berkeley DB XML database, which is a native XML database. A web service is provided for the management of policies within the policy store. Policies can be validated when being added to the policy store to ensure that all policies within the store are properly defined.

The Melcoe PDP architecture allows for plugging in different modules for the policy store. If you do not like the Berkeley DB XML solution, you can create and a module that better suits your needs.

You are also able to create and use different XACML combination algorithms with the PDP in a modular fashion. Using a simple XML configuration file, it is trivial to change your policy combination algorithms.

The Melcoe PDP uses the Sun XACML policy evaluation engine for the evaluation of policies.

In summary the Melcoe PDP provides the following features:

  • Web service interface to the PDP
  • XML database back-end for the policy store which is used for storing, indexing and providing quick access to policies (Berkeley DB XML 2.3.10 from Oracle)
  • Web service interface for the policy store so that new policies can be added/deleted to/from the database for immediate effect
  • Interface for querying the policy store to retrieve the possible applicable policies for a given request before matching (increasing evaluation speed significantly)

Life of an XACML Request

  1. An XACML request is sent to the PDP Web Service
  2. The PDP Web Service receives the request and invokes the Sun XACML PDP evaluation engine to evaluate the request
  3. The Sun XACML PDP evaluation engine checks its registered Policy Finders for the policy and hands it off to them to locate the policy (there can be only one policy. Multiple policies are combined into a single policy using the policy combination algorithm)
  4. The Policy Finder hands the request to a Policy Manager, which is responsible for organising returned policies into a single policy in conjunction with the specified policy combination algorithm
  5. The Policy Manager hands the request off to the Policy Data Manager
  6. The Policy Data Manager is responsible for communication with the Policy Store. Each kind of Policy Store requires its own Policy Data Manager (PDM)
  7. The PDM queries the Policy Store to retrieve all 'potentially applicable' policies. This is based on a policy target index and matches all policies that COULD be applicable but includes all applicable policies in this subset. This indexing feature significantly narrows down the number of policies which need to be evaluated as this is an expensive operation
  8. Once the Policy Manager gets the potentially applicable policies, it goes through each and attempts to match them to the request
  9. All the matching policies are then combined and returned as a single XACML policy to the Policy Finder
  10. The Policy Finder can now hand the single policy back to the PDP
  11. The PDP then evaluates the policy against the request and generates an XACML Response. If necessary the PDP can also invoke attribute finders to obtain additional information to assist it evaluate a request
  12. The PDP returns the result to the PDP Web Service
  13. The PDP Web Service returns an XACML Response
  1. Add, Delete, Modify Policies within the Policy Store
  2. Query the policy store to retrieve policies.

Prerequisites

  • You need to have a working Tomcat (> 5.x.x) deployment and both your shell environments $TOMCAT_HOME, and $CATALINA_HOME set to that directory.
  • Java JDK 1.5.x
  • Ant
  • axis2.war (v1.2)
  • DB XML 2.3.10
  • melcoe-pdp Download

Installation Guide

  1. Download DB XML 2.3.10 from Oracle.
  2. Unzip and build it. Make sure to enable the java driver. Eg. 
    ./buildall.sh --prefix=/usr/local/dbxml-2.3.10 --enable-java
  3. Note: the build process will take some time.
  4. Set your shell profile to have the following variables set: (assuming bash shell) 
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/dbxml-2.3.10/lib
export MELCOEPDP_HOME=/usr/local/melcoe-pdp
    If you are a Macintosh OSX user, use the following as well as the above: 
    export DYLD_LIBRARY_PATH=/usr/local/dbxml-2.3.10/lib:$DYLD_LIBRARY_PATH
  5. Download axis2.war (v1.2 NOT 1.3!) from apache website and deploy it into $TOMCAT_HOME/webapps.
  6. Download the latest MELCOE-PDP code, unzip and run: 
    $ant install

$ant load-policies
  7. The second command loads a list of policies that can be used to bootstrap your system. By default they allow users with administrator role, and "admin" and "fedoraAdmin" users to do everything. They also allow anonymous users (ie. with role "public"), as well as people with role "student" or "staff" to connect to the repository and perform search operation. Naturally, if there are no policies to allow either public, student or staff roles to view a particular collection or resource, those collections or resources will not show up in the search results.
  8. Restart Tomcat
  9. Check that your deployment is successful by going to this URL http://<yourhost:8080>/axis2. Under Services, you should see MelcoePDP and PolicyDataManagerService. Please note the URL of the PolicyDataManagerService service since you will need it when deploying mura.
  • NOTE: To uninstall melcoe-pdp, you can use the ant script: "ant uninstall".

Directory Structure and Contents

Post install you should have the following directory structure in existence under where you installed the PDP to. (designated by $MELCOEPDP_HOME or %MELCOEPDP_HOME%) $MELCOEPDP_HOME/

  • axis2 - Contains a copy of the Axis Application Archive
  • conf - Contains all the configuration files for the pdp
    • config-attribute-finder.xml
    • config-dbxml.xml
    • config-pdp.xml
    • config-policy-manager.xml
    • log4j.properties
  • database - Contains the DB XML database
  • doc - Contains the javadocs for the source
  • jar - Contains the application as a Jar file allowing use of components
  • policies - Contains the bootstrap policies for the Fedora repository
  • xsd - Contains a copy of the XACML schemas

Configuring the Melcoe PDP

Configuring the Melcoe PDP is a matter of understanding its configuration files and the options that are available. In addition it would be useful to know how the Sun XACML Implementation works and how to configure it.

config-attribute-finder.xml

This configuration file is for managing one of the attribute finder modules.

Additional modules may be added by creating new 'AttributeFinder' element with the configuration details for your AttributeFinder module.

The default module is designed to work with the Fedora Resource Index Search interface. It makes use of various elements and attributes that allow it to connect to and retrieve information from the Fedora RI Search service.

The name attribute is the class name of the Attribute Finder. In this case it is melcoe.xacml.pdp.finder.attribute.FedoraRIAttributeFinder. In addition there is an element called resolver which tells the Attribute Finder which URL to use as well as username and password to connect to the Fedora Repository.

The 'attribute' elements tells the PDP which attributes are available for use within policies. Ideally, these attributes will exist in the Fedora Resource Index. The designator attribute tells the PDP which type of attribute it is, Subject, Action, Resource or Environment. This is important to get right as they have to match where the policies are going to look for them. That is, if you have a policy that has a rule referring to an attribute as a 'ResourceAttributeDesignator', and if that attribute is coming from the Resource Index, then this configuration file would have to specify it as designator="resource". You can add as many attributes as you like to this configuration. 

<?xml version="1.0"?>
<AttributeFinders>
	<AttributeFinder name="melcoe.xacml.pdp.finder.attribute.FedoraRIAttributeFinder">
		<resolver url="http://localhost:8080/fedora/melcoerisearch" username="" password=""/>
		<!--  designator: subject, action, resource, environment -->
		<attribute designator="resource" name="info:fedora/fedora-system:def/view#mimeType"/>
		<attribute designator="resource" name="info:fedora/fedora-system:def/model#ownerId"/>
		<attribute designator="resource" name="info:fedora/fedora-system:def/model#state"/>
		<attribute designator="resource" name="info:fedora/fedora-system:def/model#createdDate"/>
		<attribute designator="resource" name="info:fedora/fedora-system:def/model#label"/>
		<attribute designator="resource" name="http://www.w3.org/1999/02/22-rdf-syntax-ns#type"/>
		<attribute designator="resource" name="http://muradora.ramp.org.au/sf#isSmartFolder"/>
	</AttributeFinder>
</AttributeFinders>

config-dbxml.xml

This is one of the more complicated configuration files. It is responsible for controlling the DB XML Policy Store and how items are indexed which is critical to the performance of the PDP.

The database/directory element states where the database will be located. This is relative to $MELCOEPDP_HOME. It also allows you to specify what to call your database container. In this case the container will be $MELCOEPDP_HOME/database/policies.dbxml.

The schemaConfig section controls whether policies are validated when they are added to the database. It is usually a good idea to validate them unless they are validated elsewhere before entry. Validation does incur a small performance cost when adding policies. This section also specifies where policies for the two XACML namespaces can be located.

The indexMap section tells the repository how you plan on indexing your policies with targets. This will depend on how you plan to structure your policies. In the case of the Fedora policies for Muradora, we have targets that specify some combination for subjects and resources with the actions placed in the rules. Our policies for subjects and resources use some combination of the attributes listed in the below sections. This means that when an XACML request comes in, it will likely have either no subject attributes at all (which equates to 'AnySubject') or one or more of:

  • urn:oasis:names:tc:xacml:1.0:subject:subject-id
  • urn:fedora:names:fedora:2.1:subject:loginId
  • urn:fedora:names:fedora:2.1:subject:role

and either no resource attributes (which equates to 'AnyResource') or one or more of:

  • urn:oasis:names:tc:xacml:1.0:resource:resource-id
  • urn:fedora:names:fedora:2.1:resource:object:pid
  • urn:fedora:names:fedora:2.1:resource:datastream:id

When searching for possible policies from the policy store, the query will select all policies that contain values matching the values in the request for the attributes listed in the indexMap. This will pull out a suitable subset of policies for the policy engine to do a proper match. This makes the process significantly quicker as matching a policy can be an expensive operation. If you had 10,000 policies in your database for instance, the index might pull out just 30 or so policies to match against instead of 10,000. 

<?xml version="1.0"?>
<dbxml>
	<database>
		<directory name="/database"/>
		<container name="policies.dbxml"/>
	</database>
	<schemaConfig validation="false">
			<schema
				namespace="urn:oasis:names:tc:xacml:2.0:context:schema:os"
				location="http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-context-schema-os.xsd"/>
			<schema
				namespace="urn:oasis:names:tc:xacml:2.0:policy:schema:os"
				location="http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-policy-schema-os.xsd"/>
	</schemaConfig>
	<indexMap>
		<subjectAttributes>
			<attribute name="urn:oasis:names:tc:xacml:1.0:subject:subject-id" type="http://www.w3.org/2001/XMLSchema#string"/>
			<attribute name="urn:fedora:names:fedora:2.1:subject:loginId" type="http://www.w3.org/2001/XMLSchema#string"/>
			<attribute name="urn:fedora:names:fedora:2.1:subject:role" type="http://www.w3.org/2001/XMLSchema#string"/>
		</subjectAttributes>
		<resourceAttributes>
			<attribute name="urn:oasis:names:tc:xacml:1.0:resource:resource-id" type="http://www.w3.org/2001/XMLSchema#anyURI"/>
			<attribute name="urn:fedora:names:fedora:2.1:resource:object:pid" type="http://www.w3.org/2001/XMLSchema#string"/>
			<attribute name="urn:fedora:names:fedora:2.1:resource:datastream:id" type="http://www.w3.org/2001/XMLSchema#string"/>
		</resourceAttributes>
	</indexMap>
</dbxml>

config-pdp.xml

This configuration file is for the Sun XACML Engine. Detailed documentation on this file is available on the Sun XACML Project page.

This file specifies the PDP configuration. Note the addition of the attributeFinderModule for the Fedora Resource Index. 

<?xml version="1.0" encoding="UTF-8"?>
<config defaultPDP="melcoePDP" defaultAttributeFactory="attr" defaultCombiningAlgFactory="comb" defaultFunctionFactory="func">
	<pdp name="melcoePDP">
		<policyFinderModule class="melcoe.xacml.pdp.finder.policy.GenericPolicyFinderModule"/>
		<attributeFinderModule class="com.sun.xacml.finder.impl.CurrentEnvModule" />
		<attributeFinderModule class="com.sun.xacml.finder.impl.SelectorModule" />
		<attributeFinderModule class="melcoe.xacml.pdp.finder.attribute.FedoraRIAttributeFinder" />
	</pdp>
	<attributeFactory name="attr" useStandardDatatypes="true" />
	<combiningAlgFactory name="comb" useStandardAlgorithms="true" />
	<functionFactory name="func" useStandardFunctions="true" />
</config>

config-policy-manager.xml

This is a simple XML configuration file for the Policy Manager. There are two elements in this file:

PolicyDataManager - specifies the PolicyDataManager to use. This can be changed to any class that supports the PolicyDataManager interface and is usually specific to your policy store. By default the Melcoe PDP ships with the DB XML Policy Store, so the DbXmlPolicyDataManager class is the one to use. PolicyCombiningAlgorithm - This specifies how you want your PDP to deal with multiple applicable policies. All applicable policies must be combined into a single policy for evaluation. How they are combined, however, is up to you. The XACML specification suggest some basic examples and the Sun XACML Engine provides the implementation for these.

Combining Algorithms

The basic combination algorithms include the following:

  • Deny-overrides

If any applicable Policy or Policy Set evaulates to Deny, the the result is Deny regardless of the value of any other applicable Policies or Policy Sets

Sun XACML Engine provides this algorithm in com.sun.xacml.combine.DenyOverridesPolicyAlg

  • Permit-overrides

If any applicable Policy or Policy Set evaulates to Permit, the the result is Permit regardless of the value of any other applicable Policies or Policy Sets

Sun XACML Engine provides this algorithm in com.sun.xacml.combine.PermitOverridesPolicyAlg

  • First-applicable

The result of evaluating the first applicable Policy or Policy Set that is found is evaluated is used

Sun XACML Engine provides this algorithm in com.sun.xacml.combine.FirstApplicablePolicyAlg

  • Only-one-applicable

Ensures that only one Policy or Policy Set is found. If there are no policies found, the result is Not Applicable, but if more than one is found the result is Indeterminate

Sun XACML Engine provides this algorithm in com.sun.xacml.combine.OnlyOneApplicablePolicyAlg

The Melcoe PDP uses a customised combining algorithm that is specifically designed to work with hierarchies for the Muradora implementation. If you are not using Muradora it is suggested that you use one of the above combination algorithms or use your own. 

<?xml version="1.0"?>
<PolicyManager>
	<PolicyDataManager>melcoe.xacml.pdp.data.DbXmlPolicyDataManager</PolicyDataManager>
	<PolicyCombiningAlgorithm>melcoe.xacml.pdp.HierarchicalLowestChildDenyOverridesPolicyAlg</PolicyCombiningAlgorithm>
</PolicyManager>

log4j.properties

This is used to control the logging output of the Melcoe PDP. There is a ton of documentation on the internet that explains the use of the log4j logging system so I will not elaborate on that here.

However, to disable the verbose logging of the Melcoe PDP simply change the line that says: 

log4j.logger.melcoe=DEBUG, Console

to: 

log4j.logger.melcoe=WARN, Console

for only showing warning and error messages or: 

log4j.logger.melcoe=ERROR, Console

for only showing error messages 

# Set root logger level to WARN and its only appender to A1.
#log4j.rootLogger=WARN, Console

# A1 is set to be a ConsoleAppender.
log4j.appender.Console=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.Console.layout=org.apache.log4j.PatternLayout
log4j.appender.Console.layout.ConversionPattern=%d{yyyyMMdd HH:mm:ss.SSS} %-5p [%C{2}]: %m%n
#log4j.appender.Console.layout.ConversionPattern=%d{yyyyMMdd HH:mm:ss.SSS} %-5p [%C{2} %4L]: %m%n
#log4j.appender.Console.layout.ConversionPattern=[%t] %-5p %c %x - %m%n

log4j.logger.melcoe=DEBUG, Console
log4j.additivity.melcoe=false

Attachments