This document contains the software documentation for the implementation of the BioCASE rights management and access control component. Mainly based on the standards eXtensible Access Control Markup Language (XACML) Version 2.0 [MOS05] and XML-Signature Syntax and Processing (XML-DSIG) the implemented software components provide an application level firewall working on the BioCASE protocol. The components realise task like user authentication, authorisation, role based access control, access rights management, content signing and a simple client API. The software is completely implemented in Java.

The following sections describe the software implementation. First, an overview of the general system architecture is given. Next, the system requirements are presented followed by the user documentation. The latter comprises the configuration and usage of the different software components and its integration within the BioCASE scenario. Then, the installation procedure is described including the example scenario. Finally, a reference to the developer documentation is given.

2 System Architecture

The starting point of the system architecture represents the current BioCASE scenario. Within this scenario, the client uses a common web browser to control a BioCASE application located at the provider's web server (see figure 1). This application communicates with the PyWrapper whenever access to the provider's Unit Database is required. Usually, the PyWrapper also runs on this web server.

figure 1 Overview primary BioCASE protocol

To realise authentication and access rights management, an additional access control layer was introduced, filtering the communication between the client and the application. So, the filter acts like an, so called, application level firewall. This means, it scans the client-provider communication for relevant BioCASE protocol messages and evaluates correspondent access control policies defined according to the RBAC Profile of XACML v2.0 [A05].

figure 2 Overview system components

This may result in blocking client BioCASE requests completely or filtering out XML elements of the content of the provider's BioCASE response on a permitted client request. Any permitted request is redirected unchanged to the relating BioCASE provider host. Further, the implementation of the access control layer founds on several components sub dividable to handle the two main tasks authentication and access rights management (see figure 2). First, there is the Trust Center component responsible for the management of the Public Key Infrastructure (PKI). The main task of the provider’s Trust Center is the issuance of certificates required for the mutual authentication between clients and servers. Second, the Policy Enforcement Point (PEP) realises the application level firewall functionality and enforces a set of XACML based role bases access control policies defined by the provider. To support system administrators managing these policies, the Role Manager component was introduced.

For security reasons, it is very important to emphasize, that it must be assured, that the provider's web server can not be reached from the internet or other unauthorised networks directly. The only access point to outside clients should be the Policy Enforcement Point. Otherwise, any of the measures to implement authentication and access control mechanisms may be bypassed easily by communicating with the provider application directly.

The implemented components are described in more detail in the following sections. Meanwhile, two scenarios for the access control layer may come into operation, the application interface scenario, and the client API scenario. Both are enlightened in the next two sections.

2.1 Application interface scenario

This next paragraph describe the application interface scenario. The two figures figure 1 and figure 3 illustrate the components interactions of the original BioCASE protocol and the access control enhanced system architecture described below.

figure 3 Overview access control enhanced BioCASE protocol

Within the original scenario (see figure 1) the user selects the URL of the provider's application web interface in his browser. Clicking on an interactive element, such as a button, he sends an Http-request to the web server, which is handled by the application interface. Whenever the request requires access to the provider's unit database, the interface creates an adequate BioCASE request and sends this request to the PyWrapper. The PyWrapper queries the unit database, builds the BioCASE response and sends this response back to the application interface. The application interface formats a web page from this response and returns the data to the client.

The starting point within the access control enhanced system architecture remains the same (see figure 3), except that the URL of the provider begins with "https". Furthermore, the client must import his certificate on his web browser. Otherwise, the PEP assigns to him the guest role, defining minimal access rights to the system only. In this scenario, the PEP, located at the provider's access control layer, receives the client request. Then, the PEP authenticates the client verifying its certificate got from the SSL handshake with the client browser. If the client can not be authenticated, then the PEP also assigns to him the guest role. When the client is authenticated, the PEP requests the Role Enablement Authority (REA) subcomponent, to evaluate all roles enabled for this client within the Role Assignment policies defined by the provider's system administrators. Then, the PEP adds this list of client roles and the internal URL of the PEP as parameters to the original client request and forwards it to the provider's application interface. The application interface proceeds the request as described for the primary BioCASE scenario. If the interface needs to access the PyWrapper, then the interface uses the URL received as request parameter from the PEP before. So, the Interface connects to the PEP and sends the generated BioCASE request to him. When no database request is required, then the application interface responds the request from the PEP as described for the primary BioCASE scenario and the PEP returns this response to the client.

When the PEP receives a request for the PyWrapper, its PEP subcomponent evaluates this request using the role list evaluated before (appended to the request from the interface as additional Http-request parameter). The Policy Decision Point (PDP) evaluates the BioCASE request against the defined XACML Role Permission policies for each of the evaluated roles. If the request is permitted for one of these roles, the PDP returns a permit decision to the PEP. If the request is denied, then the PEP creates a BioCASE error response and returns this response to the application interface.

Otherwise, the PEP forwards the BioCASE request unchanged to the PyWrapper. Then, the PyWrapper's BioCASE response is evaluated against the defined XACML Role Permission policies also. If the PDP denies the access to any of the sub elements or element attributes of the content of the BioCASE response, then the PDP also eliminates this element (and all its attributes and sub elements) or the attribute from the content element of the BioCASE response respectively.

Finally, the BioCASE response filtered by the PDP is returned to the provider's application interface, which proceeds the response as normal. The application interface returns its final Http-response to the PEP returning this final response directly to the client.

2.2 Client API scenario

Unlike the application interface scenario, there are only a few changes using the client API. The main change is that there is no interaction between the PEP and the application interface. The PEP receives BioCASE requests through the client API and delivers the permitted requests directly to the PyWrapper of the original BioCASE scenario. Also, the PEP receives BioCASE responses directly from the PyWrapper and delivers them to the client API.

The major task of the client API is the provision of a simple, but easy to use communication interface, which may be used by any other client application or application interface. The location of the client API should not be at the provider hosting the PyWrapper. Because in addition, the client API now supports the verification signed content document received in BioCASE responses from the PEP. The result of this verification will be reported through the addition of some Diagnostic element to the original BioCASE response. You will agree with, because it makes no sense if the provider would verify its own signature on behalf of the client user. The default application interface scenario does currently not support signature verification.

The second feature not supported within the default application interface, is that the client API supports some kind of single-sign-on mechanism e.g. for web portals realising their own client authentification. Assumed, that the BioCASE provider trusts this web portal, it accepts the identity of all clients authenticated by that trusted application. Therefore, a special role – called trustedClient - may be assigned to this client application in the PEP’s XACML policies permitting proxying of user identities by passing the client identity in form of an X.509 certificate to the PEP.

2.3 Components

The following sections describe the components presented in the overview in more detail, such as the

· BioCASE Provider

· Public Key Infrastructure

· Web Browser

· RoleManager

· Policy Enforcement Point

· Client API

2.3.1 BioCASE Provider

To support the access control enhancements, the original BioCASE scenario [BIO05] has been subject to some minor modifications already suggested above. The enhanced scenario should be supported in the provider software starting with version 2.31. This version has been implemented for the computer demonstration at the TDWG 2005 meeting in September 2005. The following paragraphs describe the required modifications.

First, the provider software must store the role list sent from the PEP included since the initial request forwarded to the application interface (see clause 4.5). The role list is sent within the Http-parameter role. The provider interface must include this parameter to any PyWrapper request (redirected to the PEP). This indicates to the PEP, that the request was initiated from the PyWrapper and intended for the PyWrapper.

Next, for the redirection of PyWrapper-requests initiated by the provider’s application interface, the PEP uses the already defined Http-parameter wrapperURL for any Http-POST requests or url for any Http-GET requests respectively. For that, the PEP must be configured with its own (PyWrapper)-URL, such it can be connected from the internal network, i.e. the web server hosting the provider's application interface (see clause 4.1.2.3).

2.3.2 Browser

Within the BioCASE scenario, the web browser usually serves as graphical user interface enabling the client to interact with the provider software. To be suitable for the enhanced access control environment, the client's web browser must support the Https-protocol (e.g. Mozilla Firefox [MOZ05], Microsoft Internet Explorer). Furthermore, the user must install its own X509 certificate and, to verify the authenticity of the provider host, the certificate of the provider. Both certificates should be available from the provider’s Trust Center.

2.3.3 Trust Center

The main task of the provider’s Trust Center is reliable authenticity management. Therefore, the Trust Center ensures the authenticity of entities by generating key pairs and issuing certificates for these entities. With the issuance of certificates (see clause 4.2), it guarantees that the owner of the corresponding private key is the entity described within the certificate's attributes. The Trust Center must also ensure to hand out the related private key to the correct entity. An entity may be a person, like a system user, but may also be a system, such as the provider's Policy Enforcement Point.

Usually, a Trust Center provides further information services allowing to query for certificates of given entities or to provide information about the current state of a certificate (valid, revoked, and expired) [SS04]. But in the current scenario, the Trust Center just serves as a secure user or server registry on behalf of the provider. So, it creates key pairs for registered clients and server hosts of this provider and issues the corresponding certificates. Then it ensures to hand out the key pairs and certificates to their correct owners, i.e. the registered system user or the server administrator respectively. Finally, the provider has to publish the relevant server certificates, such as to make possible to authenticate the provider servers to the client. For that, the client just has to install its private key and certificate, and the server certificates within its security enabled web browser (e.g. Firefox, Internet Explorer).

This project provides a basic Trust Center solution based on the OpenSSL project. The implemented Public Infrastructure should be suitable not only for single providers, but for providers belonging to the same security domain or hosting multiple provider databases also. The solution should be extensible to more complex infrastructures. Very useful information about the construction of Public Key Infrastructures gives [DFN00]. Anyway, the following section shortly describes the provided Public Key Infrastructure.

2.3.3.1 Public Key Infrastructure

The Public Key Infrastructure bases on the X.509 standard [IET05] and realises the mutual authentication between client and provider within the Policy Enforcement Point of the Access Control Layer using the Secure Socket Layer (SSL) protocol. Every X.509 PKI founds on a Root Certification Authority (RootCA), which must be at the same time the most trustworthy and most secured entity in the whole security infrastructure. The RootCA provides certificates for Registration Authorities (RA) thus enabled to issue certificates for users or servers. We established two RAs: a ServerCA, issuing certificates for provider servers and a UserCA issuing certificates for users. Both issue certificates on request of the provider administrators, when a new provider host shall be setup, or the provider's system administrators, when they register a new client. The following figure illustrates the hierarchy of the demonstration scenario, where keys and certificates for one provider and three clients were issued. As stated above, this infrastructure may be easily extended to support several provider or providing hosts and the addition of an arbitrary amount of users. The definition of roles and the assignment of users to these roles bases on the issued X509 user certificates and is supported by the RoleManager tool.

figure 4 Public Key Infrastructure

2.3.4 RoleManager

The RoleManager is a small command line application permitting the

· definition of roles

· assignment of users to roles

· definition of permission policies

· assignment of permission policies to roles

· definition of permissions

· assignment of permissions to permission policies

· assignment of conditions to permissions

The RoleManager supports the provider's system administrators to manage and configure an adequate XACML policy hierarchy according to the XACML Role Based Access (RBAC) profile [A05]. The detailed commands and parameters are described in clause 4.3.2. The policies defined with the RoleManager are stored as XML files in a special configuration directory on the file system (see clause 4.1.1). Configured with the same policy directory location, the Policy Enforcement Point (PEP) and its subcomponents Role Enablement Authority (REA) and Policy Decision Point (PDP) evaluates the enabled roles or access rights for a given action and resource from these policy files respectively.

2.3.5 Policy Enforcement Point

As its name suggests, the Policy Enforcement Point (PEP) represents the system entity enforcing authentication and access control on behalf of a given provider. Thereby, the PEP becomes the only access point to the provider's application interface and/or PyWrapper respectively.

To realise the authentication, the PEP accepts all incoming requests on behalf of the provider using the SSL-protocol (https). For the realisation of the Role Based Access Control, the PEP involves two subcomponents:

· Role Enablement Authority (REA)

· Policy Decision Point (PDP)

The REA's task is to evaluate a list of enabled roles for a given client identified by its X.509 certificate. The REA is a special instance of an XACML PDP, focusing on Role Assignment Polices only (see clause 4.3.1) and specifying user-to-role assignments. To process the request the REA requires a X.509 certificate. The REA evaluates all roles specified within the Role Assignment Policies and evaluates for each role, if this role is enabled for the client authenticated by the given X.509 certificate. Finally, the REA returns the resulting list to the requester, i.e. the PEP.

If the authentication of the client fails, then the PEP creates a role set containing the predefined role guest only.

The PDP's task is to evaluate access rights for a given set of roles, on a given resource with a given action. Therefore, the PDP just focuses on Role Policy Sets, referencing the Permission Policies defined for a given role (see clause 4.3.1). Permission Policies include of a set of Permissions specifying resources enabled for a given action. Thus, the same policies can be referenced from different roles.

Within the BioCASE environment, we have to distinguish request and response policies. Within request policies, resources are defined as paths to concepts, which may be subject of a scan or search request. Unlike request policies, resources are defined as paths to elements or attributes within the XML document included in the content sub element of a BioCASE response. Actions are defined on each of the specified BioCASE protocol method, such as capabilities, scan and search. To allow the definition of permissions for requests and responses, the suffixes "-request" or "-response" has to be appended to the method names within Permissions. So, the PDP needs at least a role, a resource and the related BioCASE request method to evaluate if access to the given request or a response content element may be granted or not.

After a successful client authentication, the PEP gets the client's certificate and queries the REA for the set of enabled roles. When receiving a request designated to the PyWrapper, the PEP analyses this BioCASE request and generates an evaluation request to the PDP with the role set evaluated by the REA as subject, the requested concept(s) as resource(s) and the request method as action. If the PDP permits the request, the PEP forwards the request to the PyWrapper. After receiving the BioCASE response from the PyWrapper, the PEP examines the resulting content document and creates an evaluation request to the PDP with the role set as subject and the response method as action for each element or attribute path in this content document. If the PDP does not permit the access to any of the content's sub elements, then the PEP eliminates this element and all its attributes and sub elements from the BioCASE response. If access is denied for an attribute, the PEP eliminates this attribute only.

More details about the integration of the PEP in the BioCASE protocol have been described in the clause 4.5).

2.3.6 Client API

The main objective of the client API is the communication management with the Policy Enforcement Point (PEP) of a BioCASE provider. The API may be used to provide security related facilities like authentication or signature verification within any third party BioCASE application interface.

The client API was implemented in Java, where the main interface was realised in the class nbi.xmlsec.PEPClient. It can be used to send and receive requests and responses of the BioCASE protocol. Further, it supports SSL authentication against the PEP and the signature verification of possibly signed content documents within BioCASE responses. The result of the verification process is reported within the Diagnostics of the original BioCASE response. Therefore, the newly create code attribute “SECURITY”is used.

Finally, the classes of the package nbi.xmlsec.biocase.protocol (e.g. Request, Response) provide an easy to use interface to create and evaluate BioCASE request and responses respectively.

3 System Requirements

The following sections include an overview of the system requirements needed to install and run the software. Currently the following third party or open source components are indispensable to run the system:

· Java OS

· OpenSSL

· Ant

· bash-shell

The Java section also contains a list of open software projects, which libraries have been used to implement the system.

3.1 Java Platform

The software implementation builds up on the Java 2 Platform, Standard Edition (J2SE) Version 1.4.2 [SUN05]. The current release number is 10. Furthermore, the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 1.4.2 are required, enabling to use third party JCE provider on the Java Platform.

The Java Platform is available for all popular Windows, Linux and Solaris operating systems. Using the Java Platform, the software implementation uses the following open source third party software components:

Bouncy Castle JCE provider	[TAU05]
Sun's XACML Implementation	[SUN04a]
Jetty Java Http Servlet Server	[MOR05]
Apache Jakarta Subproject Commons components: - CLI - Collection - Configuration - IO - Lang	[THE05a]
Log4j project	([APA05])
JSR-105 XML Digital Signature APIs	[SUN04b]

See the installation guide (see clause 5) for further information.

3.1.1 OpenSSL

The OpenSSL Project [THE05b] offers an Open Source implementation of the Secure Sockets Layer (SSL)/Transport Layer Security (TLS) protocol and a general purpose cryptography library. OpenSSL is used in this system to provide the Trust Center functionality such as the generation of Public Key pairs and X.509 certificates.

Binary distributions of OpenSSL are included in most popular Linux distributions and for Microsoft Windows. During the implementation of this system, the OpenSSL package included in Cygwin (see clause 3.1.2) was used to build up a test PKI. In the course of the development, some a basic OpenSSL configuration has been developed, supporting the creation of the PKI (see 4.2).

3.1.2 Cygwin

Cygwin is a Linux-like environment for Windows providing a collection of useful Linux/Unix tools like the bash-shell or the OpenSSL package [RED05]. The software distribution contains some useful bash-scripts to install the software and run the PEP and RoleManager application. Thus, the software should run under the Windows Operating System, it could be time-saving to start working with Cygwin first.

3.1.3 Ant

The Apache Ant Project [THE05c] provides a Java-based build tool. Ant is used within this project to

· compile a distribution zip-file

· compile the distribution's source code

· generate the JavaDoc-based developer documentation from the distribution's source files

· install the software from the unzipped distribution

It is quite comfortable to use ant from the eclipse platform IDE [ECL05]. Anyway, refer to the project pages for current installation instructions.

3.1.4 BioCASE Provider

Of course, to see the system working, a BioCASE provider is needed. The system should cooperate with the BioCASE provider version 2.3.1 [BIO05]. This is the version used for the computer demonstration at the TDWG 2005 Meeting in September 2005. If the version is not available on the web page, please contact the BioCASE developers for support.

3.1.5 Web Browser

The web browser is required to drive the provider's application interface and manage the Public Key Pair of the client and the certificates of the provider host running the PEP during the authentication. The web browser of choice must support the https protocol, X.509-certificates and PKCS#12 key pair files. The software has been developed using the Mozilla Firefox Browser version 1.0x [MOZ05] and has been tested with the Microsoft Internet Explorer version 5.x or higher included in Windows XP.

4 User Documentation

This section of the document contains the user documentation of the implemented system components. It shall support system administrators to configure the software and define XACML policies. The documentation starts with a description of the configuration issues of the implemented components. Then it explains the policy management structures and shows how to set up the PKI using OpenSSL. Next it provides a user manual of the Role Manager component and concludes with a detailed description of the BioCASE system integration of the PEP.

4.1 Configuration (general)

The configuration of the RoleManager, the Policy Enforcement Point and the Role Enablement Authority is build up on the subproject Commons Configuration of the Apache Jakarta Project (http://jakarta.apache.org/commons/configuration/). The configuration consists of the file "config.xml" specifying the configuration objects to load. We decided to use an XML based configuration object, which is stored in an XML file to be configured within the attribute "fileName" of the element "xml" in the config.xml.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>
<xml fileName="PEPconfig.xml"/>
</configuration>

Currently, there is not DTD or XML schema to describe the format, neither from the Commons Configuration project, nor from us. So, the relevant parameters will be explained in the configuration sections of the correspondent component. (see clauses 4.1.1, 4.1.2 and 4.1.2.5).

Generally, the root element is ignored, so the configuration of a component starts with its corresponding element name such as RoleManager, PolicyEnforcementPoint or RoleEnablementAuthority.

4.1.1 RoleManager

The configuration largely represents the class architecture of the RoleManager's software architecture. The aim of the RoleManager's configuration framework is to keep the configuration of the RoleManager's components as flexible as possible. So, any of the particular components implementing classes may be interchangeable whenever wanted.

The RoleManager element has two attributes:

RoleManager
Attribute	Function
class	The class of the RoleManager implementation to be loaded.
defaultDomain(required)	The default domain specifies the domain to be used, when the command line interface is invoked without the -D option.

Furthermore, the RoleManager element must contain a PolicyManager element described in clause 4.1.2.5.1.

As an example, look at the example RoleManager configurations delivered with this distribution (see also clause 5.5).

If the specification of any class attribute is omitted, the implementation loads the default classes of this distribution. Anyway, for comfort reason you should define the default domain and the policyBaseDir within the PolicyManager element as default values. Otherwise, you will be forced to state the options -D and --policyBaseDir in every command invoked (see clause 4.3.2).

4.1.2 PolicyEnforcementPoint

The configuration largely represents the configurable objects of the PolicyEnforcementPoint's software architecture. The aim of this configuration framework is to keep the configuration of the components as flexible as possible. So, any of the particular components implementing classes may be interchangeable whenever wanted.

The PEP element has one optional attribute:

/PEP
Attribute	Function
class	The class of the PEP implementation to load

Furthermore, the RoleManager element must contain a Filter element. The Filter implements the filtering of incoming requests and responses. Currently, this filter builds up on the HttpServer implementation of the Jetty Project [MOR05].

/PEP/Filter
Attribute	Function
class	The class of the PEP implementation to load

Thus, Jetty's software architecture determines the items to be configured, such as

· Context path

· Listener