GeoXACML Framework
The GeoXACML 1.0 Framework implements the Open Geospatial Consortium (OGC) standard "Geospatial eXtensible Access Control Markup Language (GeoXACML) [R1], Version 1.0". GeoXACML is a geo-specific extension of the Organization for the Advancement of Structured Information Standards (OASIS) standard "eXtensible Access Control Markup Language (XACML), Version 2.0" [R2]. XACML is a language to encode authorisation decision requests and to encapsulate security rules in policies. GeoXACML extends XACML with spatial data types and spatial authorization decision functions which enables you to define additional spatial constraints for XACML based policies.
Sun Microsystems (Sun) provides a XACML 2.0 framework [R3] which is written in Java [R4]. This framework allows you to extend its architecture with own implementations of data types and functions. Therefore the GeoXACML 1.0 Framework is based on it since the GeoXACML 1.0 standard can be realised only by integrating the required functions and data types in the right extension points provided by the architecture of Sun's XACML implementation. Due to the bugs in this architecture the patch SICSCAML [R5] from the Swedish Institute of Computer Science (SICS) is used to achieve the full XACML 2.0 functionality. According to the relying framework the GeoXACML 1.0 Framework does also provide the opportunity to extend or change its architecture as it is explained in this document besides the full GeoXACML functionality. The configuration concept of the GeoXACML framework is realised with the Spring Framework [R10] using the Inversion of Control (IoC) Container functionality.
Besides the condition and bag functions, all functions and attributes are implemented with the Java Topology Suite (JTS) [R7] as well as the processing of GML encoded geometric values since its geometric funcionality is sufficient to implement the OGC GeoXACML 1.0 standard.
The GeoXACML framework is based on the XACML implementation of Sun [R3] and uses its mechanisms. Some classes are only modifications or extensions of the Sun implemenetation which are needed to satisfy the GeoXACML v1.0 specification. Therefore it is recommended to have a look at the API documentation of the Sun XACML framework v2.0.
IGeoPDPFactory factory = new GeoPDPFactory(); // instantiates the factory IGeoPDP pdp = factory.createPDP(); // gets the pdp from the factory pdp.setup(); // executes the configuration of the PDP
The setup() method activates the GeoXACML functionality and installs the configured modules needed to access policies and request properties. If this method has not been invoked, the PDP will not work. In the current configuration this PDP has only one test policy and uses a module to hold policies which is only provided as an example and for testing purposes. The preinstalled module is intended to access policies which are located in files and encoded in GeoXACML 1.0 or XACML 2.0. It is possible to change the current set of policies by modifying the config file GeoPDP.xml as follows.
Example 2: Adding a policy
...
<bean class="net.eig.geoxacml.pdp.finder.GeoFilePolicyModule">
<constructor-arg>
<list>
<!- - the new policy - ->
<value> my_policy_file.xml </value>
<!- - the preinstalled policy - - >
<value>res/test/test_geopolicy_area_designator.xml</value>
</list>
</constructor-arg>
</bean>
...If you run Example 1 the PDP contains the policies specified in the files my_policy_file.xml and res/test/test_geopolicy_area_designator.xml. In the current implementation the GeoPDP provides the method evaluate() for the evaluation of authorization decision requests. Its parameter can either be the root node (org.w3c.dom.Node) of the request, the stream of the request or an RequestCtx instance. The listing below shows how the evaluation can be done:
Example 3: Evaluating an authorisation decision request
String requestFile = "res/test/test_georequest_designator.xml";
FileInputStream requestStream = new FileInputStream(requestFile);
IGeoPDPFactory factory = new GeoPDPFactory();
IGeoPDP pdp = factory.createPDP();
pdp.setup();
ResponseCtx response = pdp.evaluate(requestStream);
Result result = Helper.extractResultFromResponse(response);
int decision = result.getDecision();
switch(decision)
{
case Result.DECISION_DENY:
System.out.println("request denied");
break;
case Result.DECISION_PERMIT:
System.out.println("request permitted");
break;
case Result.DECISION_INDETERMINATE:
System.out.println("decision is indeterminate");
break;
case Result.DECISION_NOT_APPLICABLE:
System.out.println("no applicable policies");
}If you want to use the GeoPDP in a productive environment you should use your own policy finder module.
The GeoBuilder is the core of this GeoXACML implementation. It adds all functions and attributes to the corresponding Sun's XACML framework factories to satisfy the GeoXACML v1.0 specification. Generally it is not necessary to use it directly but if you already have an implementation based on the Sun XACML framework you can apply it to extend your existing implementation with GeoXACML functionality. This is possible since in Sun's XACML framework the responsible factories for functions and attributes can be accessed via static factory methods. Ensure that your implementation is XACML 2.0 compliant. It is recommended to patch the Sun XACML 2.0 framework with the SICSACML patch before you use this GeoXACML framework since the patch fixes several bugs in this XACML 2.0 implementation.
Example 4: Using the GeoBuilder
IGeoBuilderFactory factory = new GeoBuilderFactory(); IGeoBuilder builder = factory.createGeoBuilder(); builder.setup(); //activates the GeoXACML functionality
The GeoXACML framework is highly configurable. All GeoXACML related components in the framework are assembled via the Spring framework which allows you to change or extend the existing configuration without modifying existing source code. In a nutshell it is only needed to implement the appropriate interface and to add this implementation to the appropriate configuration file. Usually it is not necessary to change the existing configuration unless you want to use your own modules to hold policies in the GeoPDP.
The functions are divided into sections in the package net.eig.geoxacml.function like it is done in the GeoXACML specification. Each section has its own GeometryXXXFunctionFactory.xml configuration file which specifies its set of functions. With this defined set of functions an instance of the class GeometryFunctionFactory will be created at runtime automatically. This factory will be passed to the GeoBuilder with the appropriate setter method. In general you need to implement the interface com.sun.xacml.cond.Function and add it to the configuration file of the appropriate factory to extend the GeoXACML framework with a own function. Abstract classes are provided for functions which belong to the same section and have common implementation characteristics. These classes make it more comfortable to implement functions for specific purposes since you can concentrate on the actual function behaviour. Such abstract classes are ATopologicalFunction of the package net.eig.geoxacml.function.topological for topological functions, AConversionFunction from the package net.eig.geoxacml.function.conversion and AGeometryGeometricCharacteristicsFunction in net.eig.geoxacml.function.geometric.characteristics.
Adding new Attribute data types should not be necessary because GeoXACML introduces only one new data type urn:ogc:def:dataType:geoxacml:1.0:geometry. This data type represents the abstract super class of all geometries. The concrete instances are encoded in the Geography Markup Language (GML) [R13] which is a language for expressing geographical features. According to the OGC GeoXACML specification (Version 1.0 Page 14) there will not be a new geospatial datatype:
"... Please note that the actual XML encoding of these geometries can vary. Therefore, this standard provides multiple extension parts in which a particular encoding is defined. ..."
These extensions [R1] define the encoding of geometries which are GML2 or GML3.
"... By using a super class for all geometric data types (see [R4]) as the only spatial data type in GeoXACML, this standard remains "stable" even if new extensions parts are added. Additionally, the use of the geometric super class as the only new data type in GeoXACML simplifies the declaration of the function signatures as well as the implementation of GeoXACML conformant access control systems. ..."
This GeoXACML implementation supports GML2 [R13]. You can change the supported GML encoding by implementing the interface IGMLReader and changing the IGMLReader in the configuration file GeometryAttribute.xml with this implementation. In spite of the fact that there will be no new GeoXACML data type, you can introduce your own geospatial data types or the one. For that purpose you need to extend the class com.sun.xacml.attr.AttributeValue and implement the interface IGeometryAttribute. After that it is necessary to create an appropriate proxy of this attribute which satisfies the interface IGeometryAttributeProxy since a proxy know how to create its attribute. At last you need to make an adequate entry in the configuration file GeometryAttributeProxyFactory.xml to add your attribute implementation to the GeoXACML framework.
As mentioned before this implementation relies on the Sun XACML framework. Therefore it is necessary to work with some of its concepts. One of these concepts is the PolicyFinder with its PolicyFinderModules. PolicyFinderModules are used by the PolicyFinder to have access to policies from specific datasources such as a file system or a database. In order to achieve the GeoXACML v1.0 standard it is necessary to extend these components since the existing solution does not provide a way to report processing errors which can occur when processing policies. If you want to introduce a PolicyFinderModule which is GeoXACML conform, you need to implement the abstract class AGeoPolicyFinderModule. This class extends com.sun.xacml.finder.PolicyFinderModule by providing the methods setHasProcessingError() and hasProcessingError() for reporting processing errors. When you implement AGeoPolicyFinderModule you need to take care that the method setHasProcessingError() is invoked when an error occurs during policy processing. Afterwards put your module in the configuration file GeoPDP.xml as follows to add it to the PDP:
Example 5: Adding new policy finder module
<!-- PolicyFinderModules -->
<constructor-arg>
<list>
<bean class="my.new.GeoPolicyDBFinderModule"/>
<bean class="net.eig.geoxacml.pdp.finder.GeoFilePolicyModule">
<constructor-arg>
<list>
<!-- add further policy files by adding
<value> my_policy_file </value> -->
<value>res/test/test_geopolicy_area_designator.xml</value>
</list>
</constructor-arg>
</bean>
</list>
</constructor-arg>Certainly it is possible to add ordinary PolicyFinderModules in that way. But there is no standardised way to report processing errors for these modules. A new PDP instance from created by the factory GeoPDPFactory contains the submitted changes.
In general there is no need to change the existing configuration of the set of attribute finder modules unless you want to improve the XPath functionality of the GeoSelectorModule (see API documentation of the class GeoSelectorModule for more details). Keep in mind that the module CurrentEnvModule should always be passed to the PDP since it supports the current time, date and dateTime values which shall always be available to a PDP according to the XACML specification. Also there has to be a SelectorModule which can handle GML descriptions to be standard conformant. The way of adding new attribute finder modules is quite similar to adding new policy finder modules. For introducing the new attribute finder module you must extend the class AttributeFinderModule and add your implementation to the configuration file GeoPDP.xml as follows:
Example 6: Adding new attribute finder module
<!-- AttributeFinderModules -->
<constructor-arg>
<list>
<bean class="my.new.SpecialAttributeFinderModule" />
<bean class="com.sun.xacml.finder.impl.CurrentEnvModule" />
<bean class="net.eig.geoxacml.pdp.finder.GeoSelectorModule" />
</list>
</constructor-arg>The functions urn:ogc:def:function:geoxacml:1.0:convert-to-metre and urn:ogc:def:function:geoxacml:1.0:convert-to-square-metre use the class UnitConverter for converting the given area values in the given unit of measure in metre or square metre. For that purpose UnitConverter uses the two properties files UnitConverter_convert_to_metre_units.properties and UnitConverter_convert_to_square_metre_units.properties which contain appropriate measure units with its corresponding multiplier values for the conversion. The entries are taken from the National Institute of Standards and Technology (NIST Guide to SI Units: B. 9 Factors for units listed by kind of quantity or field of science, http://physics.nist.gov/Pubs/SP811/appenB9.html) as specified in the GeoXACML standard. If you want to support an additional measure unit, you only need to put a new key value pair in the appropriate UnitConverter properties file.