Chapter 3   Routing


The router component has two specific functions:

• Provide a means of authorising requests to particular services

• Provide a means of controlling the flow of transactions

The router has a rule based architecture that allows the developer to modify the behaviour of a transaction in many cases without recourse to writing Java Code. This is achieved by producing a set of XML rules that determine the flow of a message through the system, and comparing these rules to the values held in the v's message.

The following sections define the concepts used in the router architecture, the function of the router, and the default implementation for Identrus message processing.

Messages

---

An iPlanet Trustbase Transaction Manager message is an entity that moves from one part of iPlanet Trustbase Transaction Manager to another. The message is an encapsulation of the message sent to iPlanet Trustbase Transaction Manager together with internal data about the message. The basic components of an iPlanet Trustbase Transaction Manager message are as follows:

• Message Type

• Attributes

• Data Content

  
  

  ---

  Note	Further details of the content of an iPlanet Trustbase Transaction Manager message can be found in the API documentation for uk.co.jcp.tbase.environment.Message.

  ---

  
  

The Message Type and Attributes determine how the framework itself will handle the iPlanet Trustbase Transaction Manager Message. Anything in the Data Content is treated as opaque by the iPlanet Trustbase Transaction Manager framework; i.e. any changes to the Data Content will not be visible to the iPlanet Trustbase Transaction Manager framework.

The Router determines the state of a message by interacting with the message's attributes. The router uses a set of pre-conditions based on attribute values to determine the state of the message and therefore which actions should be applied to that message. These pre-conditions and actions are stored in the form of router rules that are described later.

Message Attributes

Message Attributes are just name-value pairs in the same way as Java properties. Attribute names and values are always string types.

A protocol handler, message reader, message writer, the router or a service may read and write message attributes. This allows each stage in the message processing pipeline to add its own state information.

Attributes may be defined by any user application code, but a number of standard attributes are used by the iPlanet Trustbase Transaction Manager framework. These are defined below:

• messageType
  This attribute is treated specially by the Message API class, the message type is used in conjunction with the message MIME type to determine which Message Readers, Message Writers and Protocol Handlers should be used in the processing of this message. It is the responsibility of the Protocol Handler for the MIME type to set this attribute correctly. The messageType attribute may change during the processing of a message.

• security.role
  This attribute contains the security role to which this message has been attributed. The authenticator service sets this attribute to one of the following values: the role name for successful authentication, default when no role can be assigned

• security.cert.dn.<n> [ 1 <= n <= cert chain length ]

  security.cert.sn.<n> [ 1 <= n <= cert chain length ]

  These attributes describe the certificate chain authenticating a message. Each certificate in the chain [ starting with the subject cert, numbered 1 ] is identified by it's issuer Distinguished Name and serial number

• security.cert_encoding
  This is always BASE64.

• security.cert_present
  Is there a valid certificate present for authentication purposes?

• security.username
  A username for authentication purposes.

• security.password
  A password for authentication purposes.

• security.user_pass_present
  Is there any valid username/password evidence for authentication present on this message.

• security.auth_failed
  Authorisation failed when an executeServiceDirective was called, this means that there was no role/serviceName mapping in iPlanet Trustbase Transaction Manager. This means that the message is not authorised to be sent to the requested service.

  
  

  ---

  Note	The attribute names for security specific attributes are declared as constants in uk.co.jcp.tbaseimpl.authenticator.SecurityContext Also see uk.co.jcp.tbase.environment.attribute.

  ---

  
  

Identrus Message Attributes

In the case of the Identrus message processing, the following additional message attributes are used:

• DocType
  The DOCTYPE of the XML message that will identify the type of message. e.g. CSCRequest or PingRequest

• SigningCertPurposeId
  This optional attribute is only interpreted by the default Identrus Message Writer, if present it specifies the Certificate Store Attribute to be used to extract the signing certificate and private key. If this is not present then the message writer assumes that the Level 1 Inter-participant Signing Certificate is to be used.

• XMLSystemId
  This contains the 'system identifier' attribute from the incoming XML message - it is used by the Identrus Message Writer to fill in the XML System identifier on the corresponding response message.

  
  

  ---

  Note	The attribute names for Identrus specific attributes are declared as constants in com.iplanet.trustbase.identrus.IdentrusConstants.

  ---

  
  

Router Architecture

---

The Router performs the core rule based message routing which is central to the flexibility offered by iPlanet Trustbase Transaction Manager, but it is also responsible for gating access to services on the basis of authentication information and authorisation settings. Figure 3-1 shows the basic elements involved with getting a message through iPlanet Trustbase Transaction Manager and into the service that can process it.

Figure 3-1    Router Architecture

• The message arrives at iPlanet Trustbase Transaction Manager and makes its way through the presentation layers (protocol handlers and message readers), during which time the messageType is identified and set and a number of other standard attributes are also set. These attributes form the basis of the authentication evidence for the message.

• The message then arrives at the router. All messages are initially sent to the service identified by the name "Authenticator". There is a default 'Authenticator' service that comes with iPlanet Trustbase Transaction Manager, but this may be replaced by an alternative implementation if required.

• The message is sent to the default Authenticator Service that examines the attributes on the message to assess the authentication level of the message. The function of this service is defined in more detail below.

• The message arrives back at the router with a security context attribute (security.role) set, this context attribute determines the Role into which the message has been authenticated.

• The target service is located by processing the message through the routing rules and then the message is sent to the service. The detailed definition of these rules is given later on in this section.

• Before the message arrives at the service it must pass through an authorisation gate, this authorisation gate checks that there is a mapping between the role attribute assigned to the message and the target service. If such a mapping exists then the message is passed to the service, if no such mapping exists then the message is sent to an authorisation error service.

The stages described above are the basic stages which all iPlanet Trustbase Transaction Manager messages go through. The processing pipeline has been streamlined from the developers point of view when working with Identrus XML messages and is defined in the Default routing section in this chapter.

Authentication and Authorisation

---

The authentication mechanisms of iPlanet Trustbase Transaction Manager are not a separate component. Authentication data is gathered by the default iPlanet Trustbase Transaction Manager framework, this can be added by domain specific services. These services must map an identity onto a particular set of attributes, and iPlanet Trustbase Transaction Manager then uses these attributes to impose access control on other services.

Authentication

In order to ensure that the authentication and authorisation mechanisms are suitable for the widest variety of organisation, the iPlanet Trustbase Transaction Manager framework does not perform the authentication operations itself, but expects a service to be capable of verifying identity and mapping this to a particular role or roles. The system comes supplied with a basic identity that uses a digitally signed data item and an accompanying X509 digital certificate. The service is capable of mapping this data into a role or set of roles The basic authentication information may be presented in one of two ways:

• Implicitly - within the Transport protocol e.g. SSL

• Explicitly - within the message content e.g. signed message block of an Identrus XML message

The architecture is designed to reduce both of these to explicit authentication by removing the certificate used in the SSL handshake and using it to decorate the message passed to the authentication service. This allows the target system to impose different levels of authentication that would be difficult to achieve with an implicit 'black box' approach to transport level authentication.

The default service also provides a means of mapping a username and password onto a role for use by the router when authorising requests. This mechanism is commonly used when presenting configuration and administration information using the HTMl templating mechanism. It is recommended that the closed community mechanism be replaced by an enterprise wide username and password mechanism if the platform is to be used for large scale HTML based applications.

Authorisation

Given that we can identify the originator of a message, either through the digital certificate or an alternative means, we now require a mechanism of:

• Identifying the appropriate level of authorisation for the user

• Enforcing access to each service on the basis of authorisation

The identification of the proper authorisation level (or role) is performed by a service named 'Authenticator' in iPlanet Trustbase Transaction Manager. This service has a default implementation that uses the username/password tables and certificate tables in the authorisation database to determine a mapping for the security attributes on the message. The mapping of this information is described in the iPlanet Trustbase Transaction Manager Configuration & Installation Guide. Enforcing the access to each service is done automatically by the router. If a routing rule is matched and the body contains an 'executeServiceDirective' then before that directive is executed the router establishes if there is a mapping between the role assigned to the message and the required service. These mappings are held in the authorisation table and this table's use is described in the Trustbase Configuration & Installation Guide. If the mapping exists then the message is passed to the service. If no mapping exists then a new attribute is added to the message "security.auth_failed" and the message is sent back to the router. The routing rules should always detect an authorisation failure and execute an appropriate service to send an 'unauthorised' response to the client. Services may be executed unconditionally by using the 'unauthorisedExecuteServiceDirective' that does not attempt check for authorisation.

Default routing

---

In order to provide a simple development path for Identrus Messaging services, iPlanet Trustbase Transaction Manager provides a default routing mechanism for Identrus Messages. This default routing is applied to all Identrus Services developed and deployed as described in Chapter 8 Building Identrus solutions of this document.

It is anticipated that this default routing will be sufficient for most Identrus Services in the near term. Where the default routing is inadequate, the developer must write new routing rules.

Router Rules

The updates made to the Router for version 2.2 of the iPlanet Trustbase Transaction Manager allow a very simple approach to basic rules handling to be taken. In previous versions of the system, all services had to define a set of rules that explicitly mapped the transport of a message to and from the service. Now that rules can be defined dynamically by the system, this basic behaviour can be automatically defined. We now discuss how this is achieved.

Routing to service

The deployment descriptor contained in the service JAR file will name the service that it contains. At system startup, the rules handler will determine which services are to be loaded, and for each service in the list will dynamically create a routing rule that forwards messages with the specified doctype to the service. If a service has a user-defined ruleset, the dynamically created rule will pass the message to this ruleset instead of directly to the service. This user defined ruleset lives in the JAR file with the service implementation and will normally not be required for services with simple message flows.

Return path

In order that the routing be kept as simple as possible, a message will be returned to a user if a specified attribute has been set on the message. This "ReturnToUser" attribute should be set by the service once processing is complete. This also applies to error messages produced at the service level.

Figure 3-2    Default routing rules

Advanced Routing

---

This section describes routing rules in detail, for simple Identrus services the developer should not have to write any routing rules in order to get messages to their service. If the default routing is inadequate or non-Identrus message processing is required then developers must resort to writing their own rules.

Routing Rulesets

The routing tables have two logical areas, one private and one public. Public rule sets may be added or configured through the management interface, private rule sets are used by iPlanet Trustbase Transaction Manager to provide basic services and may not be configured by the developer or systems administrator. At the top of this structure is the Root Rule Set which governs the way in which the private rules are executed and if none of the private rules match the parameters then the Public Root Rule Set is executed. System developers may then link their own task Rule Sets from this Rule Set (See Rule set definition in the next section)

Figure 3-3    Rule Sets

Each area contains a number of rule sets. Each public rule set will have a name, usually indicating the business task performed by the set of rules. The public rule sets are loaded from disk each time the platform starts up, and may be loaded explicitly by name as the result of a rule execution in the root rule set.

When a message is passed to the router, it will have already been associated with a context. Each context has an association with a rule set. This implies:

• The message is operating in its root context, and has the root rule set associated with it.

• The message is operating in a sub-context, and has a rule set from the public rules area associated with it.

• The exception to this is if an iPlanet Trustbase Transaction Manager message is being processed in which case a private rule set will be associated.

Rule Sets are processed sequentially, and the first rule to match the current conditions is used. The router takes each rule from the rule set in turn, starting with the first, and attempts to match the message type with a rule pre-condition. If a match is found then the action is executed. If no match is found then an error condition is returned. It is important to bear in mind that because rules are processed sequentially it is necessary to keep the more explicit rules at the beginning of the rule set with more general rules occurring later. Otherwise it is entirely possible that a general rule could preclude other rules from ever being executed.

It is considered good practice to keep the root rule set as small as possible. To achieve this, a rule in the root rule set should only match the first message in a business task i.e. an unsolicited message. The action should always be to start a new context, indicating the name of a rule set (and potentially the rule name to start at), that the message should be executed in. In doing this, the router will create a new context and associate the named rule set with it. The message will now be processed in the same manner.

A rule set is a single complete XML document that conforms to the DTD outlined in the next section. When the router starts up it looks in the Router section of the iPlanet Trustbase Transaction Manager initialisation file for the directory to find the rules that have been written by hand. It then looks for .xml files, and compiles these into the public rule set area. Each Rule Set contains zero or more rules as shown in the DTD fragment shown below:

<!ELEMENT ruleSet (rule*)>    <!ATTLIST ruleSet name CDATA #REQUIRED>

Each rule in the ruleset has a structure that is defined in the next section.

Router Rule Syntax

This section works through the Rule set DTD describing the purpose of each component. Each rule has three components:

• An attribute which names the rule. This is optional; the name may be used when starting new contexts if a specific rule should be evaluated.

• A set of pre-conditions that must all be met before the execution of the directives in the body.

• The body of the rule, this is the list of actions to be carried out if the pre-conditions are all met.

A typical rule name is illustrated below.

<!ELEMENT rule ( preconditions, body )> <!ATTLIST rule name CDATA #IMPLIED> <!ELEMENT preconditions (attributeCondition*)>

The preconditions are made up of zero or more Attribute conditions. Each attributeCondition must be satisfied for the body to be executed.

<!ELEMENT attributeCondition EMPTY> <!ATTLIST attributeCondition name CDATA #REQUIRED> <!ATTLIST attributeCondition operator ( greaterThan | greaterThanEqualTo | lessThan | lessThanEqualTo | notEqual | startsWith | contains | endsWith | equals ) "equals"> <!ATTLIST attributeCondition valueType ( any | null | string ) "string"> <!ATTLIST attributeCondition value CDATA #IMPLIED>

Each AttributeCondtion is evaluated by iPlanet Trustbase Transaction Manager as though it were in the form:

IF ( name operator value ) then pre-condition met

The valueType is normally defaults to 'string' and is not required in rules that have a value field. Where there is a requirement to test for the presence of an attribute, or if it needs to be tested against null, then the valueType field is used and the value field is ignored/not required.

<!ELEMENT body ((setAttribute | executeServiceDirective | unauthorisedExecuteServiceDirective )*, (startContextDirective | endContextDirective | returnToUserDirective )?)>

Once the pre-conditions have been met the body of the rule can be executed. The body of the rule may contain multiple actions that are carried out sequentially in the order that they appear. There are three actions, that are considered to be 'terminal' actions, which may only appear once in a rule and they must appear as the final action. Table 3-1 shows each of the allowable body directives.

Table 3-1    DTD Rule Body

Directive	Description
SetAttribute	Sets a iPlanet Trustbase Transaction Manager attribute on a message
executeServiceDirective	Transfers control from the router to the named service, ensuring that the mandatory authorisation checks are passed
unauthorisedExecuteServiceDirective	Transfers control from the router to the named service, without performing any of the mandatory authorisation checks.
ForkContextDirective	Duplicates an execution environment
EndProcessDirective	Discards the current execution environment, and returns control to the user
StartContextDirective	Transfers router control from one rule set to another
EndContextDirective	Ends the current context, and starts rule search again
ReturnToUserDirective	Returns control from the router to the system user

<!ELEMENT setAttribute EMPTY> <!ATTLIST setAttribute name CDATA #REQUIRED> <!ATTLIST setAttribute value CDATA #REQUIRED> <!ATTLIST setAttribute location (MESSAGE | CONTEXT) "CONTEXT"> <!ATTLIST setAttribute type (ASCEND_TRANSITIVE | NONE | INHERIT_TRANSITIVE | INHERIT) "ASCEND_TRANSITIVE">

The setAttribute action allows the router to add attributes to either the message or the context. The name, value, location and type fields are all the same as the settings for creating an attribute via the API.

---

Note	See API documentation for uk.co.jcp.tbase.environment.attribute.Attribute for more details.

---

<!ELEMENT executeServiceDirective EMPTY> <!ATTLIST executeServiceDirective name CDATA #REQUIRED>

An executeServiceDirective must specify the name of the service to invoke. This form of executing a service will always perform an authorisation check before passing the message to the requested service.

The name of the service relates to the name given to the service in the ServiceRegistry section of the tbase.properties file where each new service.description entry consists of a service name and a classpath for that particular service.

<!ELEMENT unauthorisedExecuteServiceDirective EMPTY> <!ATTLIST unauthorisedExecuteServiceDirective name CDATA #REQUIRED>

An unauthorisedExecuteServiceDirective must specify the name of the service to invoke. This form of executing a service will not perform any authorisation check before passing the message on to the service.

The name of the service relates to the name given to the service in the ServiceRegistry section of the tbase.properties file where each new service.description entry consists of a service name and a classpath for that particular service.

<!ELEMENT startContextDirective EMPTY> <!ATTLIST startContextDirective ruleset CDATA #REQUIRED> <!ATTLIST startContextDirective rule CDATA #IMPLIED>

In executing a startContextDirective the router discards the current rule set it has been searching and loads the rule set named in the directive. If an individual rule is also named in the directive then the router attempts to find that rule in the new rule set, otherwise the router begins at the start of the rule set and searches for the first rule with fulfilled preconditions.

A start context directive must contain a name for the rule set to be used. It may optionally contain a rule name to be executed in the specified rule set.

<!ELEMENT endContextDirective EMPTY>

An end context directive has no attributes or children.

<!ELEMENT returnToUserDirective EMPTY> <!ATTLIST returnToUserDirective endContext ( true | false ) #REQUIRED>

A return to user directive tells the router whether to end the current context or not.

In some cases the context serves no further purpose once a service has been executed on behalf of the user and may therefore be discarded. However it is possible to envisage scenarios e.g. whenever authentication is required for a user to run services, where one would wish to maintain the 'Authorised' context between user interactions, thus allowing the user to repeatedly use services without being required to be authorised every time.

<!ELEMENT forkContextDirective EMPTY>

<!ELEMENT forkContextDirective EMPTY>

A ForkContextDirective produces a new environment identical to the current context.The message returned to the user will have the contextID set to the original context id, but will also contain a property FORKED_CONTEXT, with the new context id. This allows the client to subsequently interact with both environments.

<!ELEMENT endProcessDirective EMPTY>

EndProcessDirective terminates the current environment. It is designed to take some of the burden off the garbage collection by explicitly terminating an environment and removing it from persistent storage.The EndProcessDirective is also a ReturnToUserDirective.

---

Note	Example rules and rulesets for core Trustbase services that comply with these data structures can be found in /opt/ittm/current/Config/Rules/Public.

---

Complete Router Rule DTD

The complete DTD that specifies all of the allowable routing rules within iPlanet Trustbase Transaction Manager is shown below.

<!-- A rule set is zero or more rules --> <!ELEMENT ruleSet (rule*)> <!ATTLIST ruleSet name CDATA #REQUIRED> <!-- A rule optionally has a name attribute and precodonditions and body elements --> <!ELEMENT rule ( preconditions, body )> <!ATTLIST rule name CDATA #IMPLIED> <!-- preconditions element is a set of zero or more attribute condition elements --> <!ELEMENT preconditions (attributeCondition*)> <!-- an attributed condition is an empty tage with name, valueType and value attributes --> <!-- the name is mandatory. The valueType may be any, null or string. if string is selected --> <!-- then value must be present. If any is selected then the value matches any value and if --> <!-- null is selected then the value is disregarded and assumed to be null --> <!ELEMENT attributeCondition EMPTY> <!ATTLIST attributeCondition name CDATA #REQUIRED> <!ATTLIST sttributeCondition operator ( greaterThan | greaterThanEqualTo | lessThan | lessThanEqualTo | notEqual | startsWith | contains | endsWith | equals ) \equals\> <!ATTLIST attributeCondition valueType ( any | null | string ) \string\> <!ATTLIST attributeCondition value CDATA #IMPLIED> <!-- The body contains one of four directives --> <!ELEMENT body ((setAttribute | executeServiceDirective | unauthorisedExecuteServiceDirective )*, (startContextDirective | endContextDirective  | returnToUserDirective )?)> <!-- A setAttribute directive --> <!ELEMENT setAttribute EMPTY> <!ATTLIST setAttribute name  CDATA #REQUIRED> <!ATTLIST setAttribute value  CDATA #REQUIRED> <!ATTLIST setAttribute location (MESSAGE | CONTEXT) \CONTEXT\> <!ATTLIST setAttribute type  (ASCEND_TRANSITIVE | NONE | INHERIT_TRANSITIVE | INHERIT) \ASCEND_TRANSITIVE\> <!-- A start context directive must contain a name for the rule set to be used --> <!-- it may optionally contain a rule name to be executed in the specified rule set --> <!ELEMENT startContextDirective EMPTY> <!ATTLIST startContextDirective ruleset CDATA #REQUIRED> <!ATTLIST startContextDirective rule CDATA #IMPLIED> <!-- An end context directive has no attributes or children --> <!ELEMENT endContextDirective EMPTY> <!-- An execute service directive must specify a name for the service to be executed --> <!ELEMENT executeServiceDirective EMPTY> <!ATTLIST executeServiceDirective name CDATA #REQUIRED> <!-- An unauthorisedExecute service directive must specify a name for the service to be executed --> <!ELEMENT unauthorisedExecuteServiceDirective EMPTY> <!ATTLIST unauthorisedExecuteServiceDirective name CDATA #REQUIRED> <!-- A return to user directive has one attribute specifying whether to end the current context --> <!ELEMENT returnToUserDirective EMPTY> <!ATTLIST returnToUserDirective endContext ( true | false ) #REQUIRED> <!-- A fork context directive has no attributes or children --> <!ELEMENT forkContextDirective EMPTY> <!-- An end process directive has no attributes or children --> <!ELEMENT endProcessDirective EMPTY>