issrg.pba.rbac.xmlpolicy
Class XMLPolicyParser

java.lang.Object
  issrg.pba.rbac.xmlpolicy.XMLPolicyParser

All Implemented Interfaces:

PolicyParser, org.xml.sax.ContentHandler, org.xml.sax.ErrorHandler

public class XMLPolicyParser
extends java.lang.Object
implements PolicyParser, org.xml.sax.ContentHandler, org.xml.sax.ErrorHandler

This class parses the given XML into an internal representation. It creates rules for the DelegationPolicy and AccessPolicy objects.

The parser was written in 2000 when XML DOM3 parsers were not readily available with JDK, so we went for a (lightweight) SAX API. Effectively, this parser converts XML into a tree of PolicyXMLNode objects or its subclasses, very much like modern DOM3 parsers convert XML into a tree of Nodes.

To extend the set of XML elements understood by XML Parser, you need to extend the PolicyXMLNode class and provide a special constructor that contains two arguments: XMLPolicyParser and org.xml.sax.Attributes. Note that the inner classes will have an additional implied argument that is of the type of the containing class (for example, this is why the extensions of the PolicyXMLNode internal to this class do not have XMLPolicyParser as one of their parameters to the constructor - it is there implicitly).

This is a Role based implementation, so it constructs the RoleHierarchy along with Role based rules for the Delegation and Access policy objects.

Note that if the XML complies to a different syntax, the results are unpredictable.

Version:

1.0

Author:

A Otenko

Nested Class Summary

class	XMLPolicyParser.ActionPolicyNode The class representing an ActionPolicy XML node.
class	XMLPolicyParser.DomainPolicyNode This class represents the object that can store many Subject or Target Domain specifications.
class	XMLPolicyParser.DomainSpecNode This class represents the abstract DomainSpec, of which there are two extensions: SubjectDomainSpec and TargetDomainSpec.
class	XMLPolicyParser.MSoDPolicySetNode This class represents the MSoDPolicy set.
class	XMLPolicyParser.PMIXMLPolicyNode This class represents the topmost node: the policy.
class	XMLPolicyParser.RepositoryPolicyNode This class represents the RepositoryPolicy node.
class	XMLPolicyParser.RoleAssignmentPolicyNode This node implements the RoleAssignmentPolicy XML node.
class	XMLPolicyParser.RoleHierarchyNode This is the class representing SupRole nodes.
class	XMLPolicyParser.RoleHierarchyPolicyNode This is the class that represents the RoleHierarchyPolicy node.
class	XMLPolicyParser.RoleListNode This is an implementation of Role List.
class	XMLPolicyParser.RoleSpecNode This class is the implementation of the RoleSpec XML node.
class	XMLPolicyParser.SOAPolicyNode This class implements the SOAPolicy XML node.
class	XMLPolicyParser.SubjectDomainPolicyNode This is a simple extension of DomainPolicyNode that makes sure that SubjectPolicy is constructed correctly.
class	XMLPolicyParser.SubjectDomainSpecNode This is a simple extension of DomainSpecNode that makes sure that only SubjectDomainSpecs are interpreted, and no ObjectClasses are allowed.
class	XMLPolicyParser.TargetAccessPolicyNode This class represents the TargetAccessPolicy XML node.
class	XMLPolicyParser.TargetDomainPolicyNode This is a simple extension of DomainPolicyNode that makes sure that TargetPolicy is constructed correctly.
class	XMLPolicyParser.TargetDomainSpecNode This is a simple extension of DomainSpecNode that makes sure that only TargetDomainSpecs are interpreted, and ObjectClasses are allowed.

Field Summary

protected org.xml.sax.Attributes	attrs This is used when creating new nodes
protected XMLPolicyParser.RoleAssignmentPolicyNode	delegationPolicy This is the reference to the object, containing the rules for role assignment
protected static java.util.Map	knownNodes This is a collection of all known nodes.
protected org.xml.sax.Locator	locator This is a parsing-specific variable.
protected java.util.Vector	nodeStack The node stack represents the current state of the parsing tree.
protected XMLPolicyParser.PMIXMLPolicyNode	pmiXMLPolicy This is the whole Policy as a parsed tree of XML nodes.
protected XMLPolicyParser.RoleHierarchyPolicyNode	roleHierarchyPolicy This is a reference to a <RoleHierarchyPolicy> XML node.
protected ValidityPeriod	validityForRoleList This variable is used by the RoleList node to assign the correct validity period to the roles in the role list.

Constructor Summary

protected	XMLPolicyParser()
	XMLPolicyParser(org.xml.sax.InputSource xmlSource) This constructor can build a policy out of an InputSource, containing an XML Policy.
	XMLPolicyParser(java.lang.String xml) This constructor can build a policy out of the string representation of the XML.

Method Summary

void	characters(char[] arr, int start, int len) This is a callback function that is invoked by the SAX parsing process.
void	endDocument() VOID
void	endElement(java.lang.String URI, java.lang.String localName, java.lang.String qName) This is the end of the recursion body; it is called each time the element closing tag is encountered: You should not invoke it manually.
void	endPrefixMapping(java.lang.String prefix) VOID
void	error(org.xml.sax.SAXParseException spe)
void	fatalError(org.xml.sax.SAXParseException spe)
java.util.Map	getAccessRules() This method returns a Map of Target Access Rules, indexed by action name.
java.util.Map	getAssignmentRules() This method returns the set of delegation and assignment rules, as specified by RoleHierarchyPolicy.
java.util.Map	getAuthzTokenParsingRules() This method returns a Role Hierarchy Policy as the only rule.
java.util.Set	getEnvAttributes() This method returns the Set of environment nodes in a target access policy.
java.util.List	getMSoDSet() This method returns a List of Multi-Session Separation of Duties statements.
java.lang.String	getPolicyID() This method returns the ID of the parsed Policy.
java.lang.String[]	getRepositoryURLs() This method returns the URLs of the repositories specified in the RepositoryPolicy.
XMLPolicyParser.RoleHierarchyNode	getRole(java.lang.String roleType, java.lang.String roleValue) Returns the role with the given value from the RoleHierarchy.
java.util.Map	getSOAs() This method returns the SOA policy of the current XML policy
Subtree	getSubjectDomains() This method returns the domain covering all the allowed subjects.
static XMLPolicyParser	getXMLPolicyParser(java.io.InputStream is) This is a utility method that parses the policy provided as a InputStream.
static XMLPolicyParser	getXMLPolicyParser(java.lang.String policy) This is a utility method that parses the policy provided as a String.
void	ignorableWhitespace(char[] arr, int start, int len) VOID
static void	printNodes() For debugging purposes.
void	processingInstruction(java.lang.String target, java.lang.String data) VOID
static void	registerDefaultNodes() This method registers a set of default XML Nodes understood by XML Parser.
static void	registerXMLNode(java.lang.String nodeName, java.lang.Class nodeClass) This method can register any PolicyXMLNode constructor with parameters XMLPolicyParser and org.xml.sax.Attributes to it.
void	setDocumentLocator(org.xml.sax.Locator l) This method sets a source locator, which is used when sending error messages: You should not invoke this method manually.
void	skippedEntity(java.lang.String what) VOID
void	startDocument()
void	startElement(java.lang.String URI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attrs) This is the start of the recursion body of the parser; it is called any time the opening tag of an element is encountered: You should not invoke it manually.
void	startPrefixMapping(java.lang.String prefix, java.lang.String URI) VOID
void	warning(org.xml.sax.SAXParseException spe)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

knownNodes

protected static final java.util.Map knownNodes

This is a collection of all known nodes. It is useful for quick lookup of the needed node to create for a given node name.

pmiXMLPolicy

protected XMLPolicyParser.PMIXMLPolicyNode pmiXMLPolicy

This is the whole Policy as a parsed tree of XML nodes.

nodeStack

protected java.util.Vector nodeStack

The node stack represents the current state of the parsing tree. The nodes are inserted at the beginning, its parent is the object number 1, etc.

roleHierarchyPolicy

protected XMLPolicyParser.RoleHierarchyPolicyNode roleHierarchyPolicy

This is a reference to a <RoleHierarchyPolicy> XML node. However, it is functional on its own.

validityForRoleList

protected ValidityPeriod validityForRoleList

This variable is used by the RoleList node to assign the correct validity period to the roles in the role list. This value is changed by the RoleAssignmentPolicy and by the TargetAccessPolicy.

locator

protected org.xml.sax.Locator locator

This is a parsing-specific variable. It is used to locate the error point.

delegationPolicy

protected XMLPolicyParser.RoleAssignmentPolicyNode delegationPolicy

This is the reference to the object, containing the rules for role assignment

attrs

protected org.xml.sax.Attributes attrs

This is used when creating new nodes

Constructor Detail

XMLPolicyParser

protected XMLPolicyParser()

XMLPolicyParser

public XMLPolicyParser(org.xml.sax.InputSource xmlSource)
                throws PbaException

This constructor can build a policy out of an InputSource, containing an XML Policy.

Parameters:

xmlSource - is the source, containing the XML Policy to parse

Throws:

PbaException

XMLPolicyParser

public XMLPolicyParser(java.lang.String xml)
                throws PbaException

This constructor can build a policy out of the string representation of the XML.

Parameters:

xml - is the XML text of the policy

Throws:

PbaException

Method Detail

registerDefaultNodes

public static void registerDefaultNodes()

This method registers a set of default XML Nodes understood by XML Parser. The general XML syntax does not need to be extensible, but the IF-statement is extensible through this mechanism. You do not have to call this method, if you have registered other classes to handle the nodes that appear in the IF-statement; otherwise, you need to call this method to use the default implementation.

See Also:

registerXMLNode(java.lang.String, java.lang.Class)

getXMLPolicyParser

public static XMLPolicyParser getXMLPolicyParser(java.lang.String policy)
                                          throws PbaException

This is a utility method that parses the policy provided as a String.

Parameters:

policy - - the XML text of the PERMIS XML Policy

Returns:

XMLPolicyParser that has successfully parsed the policy; use its methods to retrieve the subpolicies and other rules

Throws:

PbaException, - if there was a problem parsing the policy

PbaException

getXMLPolicyParser

public static XMLPolicyParser getXMLPolicyParser(java.io.InputStream is)
                                          throws PbaException

This is a utility method that parses the policy provided as a InputStream.

Parameters:

is - - the InputStream with the XML text of the PERMIS XML Policy

Returns:

XMLPolicyParser that has successfully parsed the policy; use its methods to retrieve the subpolicies and other rules

Throws:

PbaException

printNodes

public static void printNodes()

For debugging purposes. It prints out the names of all known nodes to System.out.

registerXMLNode

public static void registerXMLNode(java.lang.String nodeName,
                                   java.lang.Class nodeClass)
                            throws java.lang.NoSuchMethodException

This method can register any PolicyXMLNode constructor with parameters XMLPolicyParser and org.xml.sax.Attributes to it.

Parameters:

nodeName - is the name of the XML element the provided class can parse

nodeClass - is the class of the parser; it must have a constructor with the first parameter being XMLPolicyParser and the other being org.xml.sax.Attributes, where XMLPolicyParser will be the reference to the XMLPolicyParser that performs parsing, and the Attributes is the set of attributes of the element being parsed

Throws:

java.lang.NoSuchMethodException

skippedEntity

public void skippedEntity(java.lang.String what)

VOID

Specified by:

skippedEntity in interface org.xml.sax.ContentHandler

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)

VOID

Specified by:

processingInstruction in interface org.xml.sax.ContentHandler

ignorableWhitespace

public void ignorableWhitespace(char[] arr,
                                int start,
                                int len)

VOID

Specified by:

ignorableWhitespace in interface org.xml.sax.ContentHandler

characters

public void characters(char[] arr,
                       int start,
                       int len)

This is a callback function that is invoked by the SAX parsing process. It will be invoked when the parse encounter string text in the xml file.

For the details of the parameters please refer to the XML SAX API documentation.

Specified by:

characters in interface org.xml.sax.ContentHandler

startElement

public void startElement(java.lang.String URI,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes attrs)
                  throws org.xml.sax.SAXParseException

This is the start of the recursion body of the parser; it is called any time the opening tag of an element is encountered: You should not invoke it manually. It creates a proper PolicyXMLNode implementation object and maintains a stack of nodes for the current branch.

Specified by:

startElement in interface org.xml.sax.ContentHandler

Throws:

org.xml.sax.SAXParseException

See Also:

PolicyXMLNode

endElement

public void endElement(java.lang.String URI,
                       java.lang.String localName,
                       java.lang.String qName)
                throws org.xml.sax.SAXException

This is the end of the recursion body; it is called each time the element closing tag is encountered: You should not invoke it manually. This method simply maintains the node stack and constructs the XML node tree, and invokes the construct method of the closing element.

Specified by:

endElement in interface org.xml.sax.ContentHandler

Throws:

org.xml.sax.SAXException

startDocument

public void startDocument()

Specified by:

startDocument in interface org.xml.sax.ContentHandler

endDocument

public void endDocument()

VOID

Specified by:

endDocument in interface org.xml.sax.ContentHandler

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator l)

This method sets a source locator, which is used when sending error messages: You should not invoke this method manually.

Specified by:

setDocumentLocator in interface org.xml.sax.ContentHandler

startPrefixMapping

public void startPrefixMapping(java.lang.String prefix,
                               java.lang.String URI)

VOID

Specified by:

startPrefixMapping in interface org.xml.sax.ContentHandler

endPrefixMapping

public void endPrefixMapping(java.lang.String prefix)

VOID

Specified by:

endPrefixMapping in interface org.xml.sax.ContentHandler

warning

public void warning(org.xml.sax.SAXParseException spe)

Specified by:

warning in interface org.xml.sax.ErrorHandler

fatalError

public void fatalError(org.xml.sax.SAXParseException spe)

Specified by:

fatalError in interface org.xml.sax.ErrorHandler

error

public void error(org.xml.sax.SAXParseException spe)

Specified by:

error in interface org.xml.sax.ErrorHandler

getRole

public XMLPolicyParser.RoleHierarchyNode getRole(java.lang.String roleType,
                                                 java.lang.String roleValue)

Returns the role with the given value from the RoleHierarchy.

Parameters:

roleType - - the type of the role, as defined in the RoleHierarchyPolicy; if there is no RoleSpec with this type, null is returned

roleValue - - the value of the role of the given type, as defined in the RoleSpec defining the role hierarchy of the given type

Returns:

RoleHierarchyNode representing the role, or null, if there is no such type defined in the policy, or no such value for the given type

getAccessRules

public java.util.Map getAccessRules()

This method returns a Map of Target Access Rules, indexed by action name. There are other entries as well, as explained in TargetAccessPolicyNode documentation.

Specified by:

getAccessRules in interface PolicyParser

Returns:

Map of Target Access Rules

getAssignmentRules

public java.util.Map getAssignmentRules()

This method returns the set of delegation and assignment rules, as specified by RoleHierarchyPolicy.

Specified by:

getAssignmentRules in interface PolicyParser

Returns:

java.util.Map object with the rules; can be empty, but never null

See Also:

AssignmentRule

getAuthzTokenParsingRules

public java.util.Map getAuthzTokenParsingRules()

This method returns a Role Hierarchy Policy as the only rule. The key in the map is issrg.pba.rbac.RoleHierarchyPolicy.class, and the object is the RoleHierarchyPolicy. These rules are used by AuthTokenParsers to extract valid roles from Authorisation Tokens.

Specified by:

getAuthzTokenParsingRules in interface PolicyParser

Returns:

java.util.Map object that contains rules for extracting Credentials from a Token

getPolicyID

public java.lang.String getPolicyID()

This method returns the ID of the parsed Policy.

Specified by:

getPolicyID in interface PolicyParser

Returns:

the String identifier of the policy (the string representation of the OID in the dotted form for PERMIS XML policies)

getRepositoryURLs

public java.lang.String[] getRepositoryURLs()

This method returns the URLs of the repositories specified in the RepositoryPolicy.

Specified by:

getRepositoryURLs in interface PolicyParser

Returns:

array of Strings, each being a non-null URL; may return an empty array or null, if no repositories are defined in the policy

getSubjectDomains

public Subtree getSubjectDomains()

This method returns the domain covering all the allowed subjects. This is a union of all Subject Domains declared in the policy.

Returns:

Subtree that is a union of all Subject Domains.

getSOAs

public java.util.Map getSOAs()

This method returns the SOA policy of the current XML policy

Returns:

the soa policy

getMSoDSet

public java.util.List getMSoDSet()

Description copied from interface: PolicyParser

This method returns a List of Multi-Session Separation of Duties statements. If no MSoD rules are defined, returns null or an empty List.

Each element in the List is a issrg.pba.rbac.policies.MSoDRule.

Specified by:

getMSoDSet in interface PolicyParser

getEnvAttributes

public java.util.Set getEnvAttributes()

This method returns the Set of environment nodes in a target access policy.

Returns:

a Set of NamedTerms representing the environment attributes mentioned in this policy