Final TrustCoM Reference implementation and associated

..
..
..
..
..
.
.
Deliverable
64
Final TrustCoM
Reference
implementation and
associated tools and
. user
. manual
.
.
.
.
.
WP34 Reference implementation methods
and tools
.
June 2007
Version 3.0
TrustCoM
A trust and Contract Management framework enabling secure collaborative business
processing in on-demand created, self-managed, scalable, and highly dynamic Virtual
Organisations
SIXTH FRAMEWORK
PROGRAMME
PRIORITY IST-2002-2.3.1.9
Networked business and governments
Prepared for the European Commission under FP6 Contract No. 01945 as a deliverable form
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
LEGAL NOTICE
The following organisations are members of the Trustcom Consortium:
Atos Origin,
Council of the Central Laboratory of the Research Councils,
BAE Systems,
British Telecommunications PLC,
Universitaet Stuttgart,
SAP AktienGesellschaft Systeme Anwendungen Produkte in der Datenverarbeitung,
Swedish Institute of Computer Science AB,
Europaeisches Microsoft Innovations Center GMBH,
Eidgenoessische Technische Hoschschule Zuerich,
Imperial College of Science Technology and Medicine,
King's College London,
Universitetet I Oslo,
Joris Claessens (editor)
Stiftelsen for industriell og Teknisk Forskning ved Norges Tekniske Hoegskole,
European Microsoft Innovation Center
Universita degli studi di Milano,
The University of Kent,
28 July 2005
International Business Machines Belgium SA .
Version 0.2
© Copyright 2007 Atos Origin on behalf of the Trustcom Consortium (membership defined above).
WP13 Standards and Collaboration
Neither the Trustcom Consortium, any member organisation nor any person acting on behalf of those
organisations is responsible for the use that might be made of the following information.
The views expressed in this publication are the sole responsibility of the authors and do not necessarily
reflect the views of the European Commission or the member organisations of the Trustcom Consortium.
TrustCoM
All information
provided
in this Management
document is framework
provided 'as-is'
with
all faults
without business
warranty of any kind, either
A trust
and Contract
enabling
secure
collaborative
expressed or
implied. in
This
publication
is forself-managed,
general guidance
only.
reasonable
and skill has been
processing
on-demand
created,
scalable,
andAll
highly
dynamic care
Virtual
Organisations
used in the compilation of this document. Although
the authors have attempted to provide accurate
information in this document, the Trustcom Consortium assumes no responsibility for the accuracy of the
information.
Information is subject to change without notice.
SIXTH FRAMEWORK
PROGRAMME
IST-2002-2.3.1.9
Mention of products or services from vendorsPRIORITY
is for information
purposes only and constitutes neither an
endorsement nor a recommendation.
Reproduction is authorised provided the source is acknowledged.
IBM, the IBM logo, ibm.com, Lotus and
Lotus Notes
areand
trademarks
of International Business Machines
Networked
business
governments
Corporation in the United States, other countries or both.
Microsoft is a trademark of Microsoft Corporation in the United States, other countries or both.
SAP is a trademark of SAP AG in the United States, other countries or both.
'BT' and 'BTexact' are registered trademarks of British Telecommunications Plc. in the United Kingdom,
other countries or both.
Other company, product and service names may be trademarks, or service marks of others. All third-party
trademarks are hereby acknowledged.
Page 2
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Deliverable datasheet
Project acronym: TrustCoM
Project full title:
A trust and Contract Management framework enabling secure collaborative business processing
in on-demand created, self-managed, scalable, and highly dynamic Virtual Organisations
Action Line:
2
Activity:
2.3
Work Package:
34
Task:
34.1
Document title:
Enhanced set of TrustCoM methods and support
tools
Version:
3.0
Document reference:
Official delivery date:
31 May 2007
Actual publication date:
31 May 2007
File name:
Type of document:
Report
Nature:
Public
Authors:
Contributions by Work Packages 28-35; coordinated
by Ivaylo Glavchovski and Alexey Orlov, Microsoft
Approved by:
Version
Date
Sections Affected
1.0
September 2005 Basic TrustCoM reference implementation (D19)
2.0
September 2006 Reference implementation methods and tools – Update on
status
3.0
June 2007
Reference implementation methods and tools – Final
description and complete user guide (D64, this document)
Page 3
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Table of Content
1
Introduction ............................................................................................................................................................. 10
2
Architecture Overview ............................................................................................................................................. 11
The Subsystem Segmentation ..................................................................................................................................... 11
Subsystem Interactions ............................................................................................................................................... 12
Deployment Overview ................................................................................................................................................. 13
3
TrustCoM implementation methodology ................................................................................................................ 15
4
Component overview................................................................................................................................................ 17
Virtual Organization Management Toolkit (SAP) ................................................................................................... 18
Notification subsystem ................................................................................................................................................ 18
Reputation Service ...................................................................................................................................................... 19
Secure Audit Web Service .......................................................................................................................................... 20
Security Token Service ............................................................................................................................................... 21
STS Overview .......................................................................................................................................................... 21
TrustCoM modules and interactions ......................................................................................................................... 21
Policy Decision Point Service...................................................................................................................................... 22
SICS SLA Management Subsystem ........................................................................................................................... 22
HPC SLA Monitoring Infrastructure ........................................................................................................................ 22
TrustCom Policy Server ............................................................................................................................................. 22
BT Gateway ................................................................................................................................................................. 23
Policy Enforcement Point ........................................................................................................................................... 23
Service Instance Registry (SIR) ................................................................................................................................. 23
5
Tools ......................................................................................................................................................................... 25
Legal Risk Analysis tool .............................................................................................................................................. 25
The CORAS Tool ..................................................................................................................................................... 25
Improvements to the CORAS Tool .......................................................................................................................... 27
6
Appendix A – Components installation and user guides, samples ......................................................................... 29
Virtual Organization Management Toolkit (SAP) ................................................................................................... 29
Installation Guide ..................................................................................................................................................... 29
6.1.1.1
Package Contents .............................................................................................................................. 29
Requirements ............................................................................................................................................................ 32
Installation Steps ...................................................................................................................................................... 32
Installation Process Description ............................................................................................................................... 33
Initialization process description .............................................................................................................................. 36
User’s Guide ............................................................................................................................................................. 37
6.1.1.2
Installation ........................................................................................................................................ 37
6.1.1.3
Installation Procedure ....................................................................................................................... 37
6.1.1.4
Registration of Editions .................................................................................................................... 38
6.1.1.5
Service Registration .......................................................................................................................... 39
Creation of a VO (Initiator Edition) ......................................................................................................................... 40
6.1.1.6
VO Identifying (VO Name) .............................................................................................................. 40
6.1.1.7
Select Choreography (Load WSCDL) .............................................................................................. 40
6.1.1.8
Choose Access Policies Templates (Policies) ................................................................................... 41
6.1.1.9
Select ECA Policies Templates (ECAs) ........................................................................................... 42
6.1.1.10
Select SLAs ...................................................................................................................................... 43
Page 4
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.11
Create GVOA Context (General VO context) .................................................................................. 44
6.1.1.12
Role Assignment (Role Overview) ................................................................................................... 45
6.1.1.13
Potential Member Overview ............................................................................................................. 45
6.1.1.14
Send Invitations ................................................................................................................................ 46
6.1.1.15
Process Invitations (Mailbox) ........................................................................................................... 47
6.1.1.16
Assign Members (Role overview) .................................................................................................... 48
6.1.1.17
Assign Member to Role .................................................................................................................... 49
6.1.1.18
Connect Notifiers .............................................................................................................................. 50
VO Operation ........................................................................................................................................................... 51
6.1.1.19
Policy Deployment ........................................................................................................................... 51
6.1.1.20
Show GVOA..................................................................................................................................... 53
VO Evolution ........................................................................................................................................................... 54
6.1.1.21
Select Member .................................................................................................................................. 54
6.1.1.22
Replace Member ............................................................................................................................... 54
6.1.1.23
Confirm Replacement ....................................................................................................................... 55
6.1.1.24
New Member after Replacement ...................................................................................................... 56
Developer's Guide .................................................................................................................................................... 58
6.1.1.25
Design of the VO Toolkit ................................................................................................................. 58
6.1.1.26
Packages and Use Cases ................................................................................................................... 58
6.1.1.27
Database Design ............................................................................................................................... 62
6.1.1.28
The VO Management Web Services................................................................................................. 65
6.1.1.29
Membership Manager – MM ............................................................................................................ 66
6.1.1.30
VOManagementInitiator – VOMI .................................................................................................... 67
Use Case “Member Replacement” ........................................................................................................................... 67
CDL2BPEL .............................................................................................................................................................. 72
6.1.1.31
Web Services .................................................................................................................................... 75
6.1.1.32
The Knowledge Base ........................................................................................................................ 76
6.1.1.33
The CDL2BPEL Algorithm .............................................................................................................. 78
6.1.1.34
Steps in the CDL2BPEL Algorithm ................................................................................................. 79
6.1.1.35
Integration With Other TrustCoM Services ...................................................................................... 80
6.1.1.36
WS-CDL ........................................................................................................................................... 82
6.1.1.37
WS-CDL Example ............................................................................................................................ 84
6.1.1.38
Usage of CDL2BPEL in the Toolkit ................................................................................................. 89
6.1.1.39
CDL2BPEL FAQ ............................................................................................................................. 91
Typical Tasks ........................................................................................................................................................... 97
6.1.1.40
Problem: A Web Service Interface Should be Changed. .................................................................. 97
6.1.1.41
Problem: A new Web Service Should be Added. ............................................................................. 97
6.1.1.42
Problem: A new Global Configuration Item Should be accessible during Runtime. ........................ 98
6.1.1.43
Problem: A new Library must be copied during Installation. ........................................................... 98
6.1.1.44
Problem: A new 3rd Party Tool should be installed during Installation ........................................... 98
6.1.1.45
Problem: A Model Class should load/store new Data in the Database ............................................. 98
6.1.1.46
Problem: A new Web Site should be integrated ............................................................................... 98
6.1.1.47
Problem: UDDI and/or Database Tables should be prefilled ............................................................ 99
6.1.1.48
Problem: The Keywords of my UDDI Business Entities should be changed ................................... 99
6.1.1.49
Problem: New Business Entities and Business Cards should be added ............................................ 99
Example .................................................................................................................................................................... 99
Notification subsystem ................................................................................................................................................ 99
Installation Guide ..................................................................................................................................................... 99
6.1.1.50
Package Contents .............................................................................................................................. 99
6.1.1.51
Requirements .................................................................................................................................. 100
6.1.1.52
Installation ...................................................................................................................................... 100
User’s Guide .............................................................................................................................................................. 100
Basic setup .............................................................................................................................................................. 100
6.1.1.53
Instantiating the broker ................................................................................................................... 100
6.1.1.54
Registering the broker at the Registry ............................................................................................ 100
Setting up a notification proxy ............................................................................................................................... 101
6.1.1.55
Instantiating a proxy ....................................................................................................................... 101
Page 5
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.56
Configure the proxy ........................................................................................................................ 101
Registering as notification producer ....................................................................................................................... 102
6.1.1.57
Specify topic ................................................................................................................................... 102
Subscribing as notification consumer ..................................................................................................................... 102
6.1.1.58
Specify topic ................................................................................................................................... 102
6.1.1.59
Specify consumer EPR ................................................................................................................... 103
Sending notifications .............................................................................................................................................. 103
6.1.1.60
Compose message ........................................................................................................................... 103
List received notifications ...................................................................................................................................... 103
Detailed view of a proxy/broker resource/overview over all resources .................................................................. 103
6.1.1.61
Notification Broker ......................................................................................................................... 104
6.1.1.62
Notification Proxy .......................................................................................................................... 104
6.1.1.63
Service Instance Registry ............................................................................................................... 104
6.1.1.64
Manage resources ........................................................................................................................... 104
Developer's Guide .................................................................................................................................................. 105
6.1.1.65
Notification Proxy .......................................................................................................................... 105
6.1.1.66
Interface .......................................................................................................................................... 105
6.1.1.67
Example .......................................................................................................................................... 108
6.1.1.68
Notification Proxy Factory ............................................................................................................. 110
6.1.1.69
Notification Broker ......................................................................................................................... 112
Reputation Service .................................................................................................................................................... 117
Installation Guide ................................................................................................................................................... 117
6.1.1.70
The Reputation Service Release Package ....................................................................................... 117
6.1.1.71
Package Contents ............................................................................................................................ 117
Requirements .......................................................................................................................................................... 118
Installation .............................................................................................................................................................. 118
6.1.1.72
<Step #1 Make sure that the Tomcat Application server is installed and working correctly >....... 118
6.1.1.73
<Step #2 Make sure that the MySQL server is installed and working correctly > ......................... 118
6.1.1.74
<Step #3 Install Axis on Tomcat > ................................................................................................. 118
6.1.1.75
<Step #4 Copy files to Tomcat > .................................................................................................... 119
6.1.1.76
<Step #5 Edit the database configuration file > .............................................................................. 119
6.1.1.77
<Step #6 Deploy web services on Tomcat and Axis > ................................................................... 120
6.1.1.78
<Step #7 Initialise the Database > .................................................................................................. 121
User’s Guide ........................................................................................................................................................... 121
6.1.1.79
Get reputation score ........................................................................................................................ 122
6.1.1.80
Rate an entity .................................................................................................................................. 122
6.1.1.81
Add a new or existing entity ........................................................................................................... 122
Developer's Guide .................................................................................................................................................. 122
6.1.1.82
Extension method ........................................................................................................................... 122
6.1.1.83
API Documentation ........................................................................................................................ 123
6.1.1.84
Example Client ............................................................................................................................... 123
Secure Audit Web Service ........................................................................................................................................ 123
Installation Guide ................................................................................................................................................... 123
6.1.1.85
Package Contents ............................................................................................................................ 123
6.1.1.86
Requirements .................................................................................................................................. 124
6.1.1.87
Installation of SAWS ...................................................................................................................... 124
6.1.1.88
Installation of JSATS ...................................................................................................................... 132
User’s Guide ........................................................................................................................................................... 132
6.1.1.89
<Initialisation>................................................................................................................................ 132
6.1.1.90
SAWS startup ................................................................................................................................. 136
6.1.1.91
The SAWS Viewing Tool ............................................................................................................... 138
6.1.1.92
The use of JSATS ........................................................................................................................... 140
Developer's Guide .................................................................................................................................................. 140
6.1.1.93
Invoke SAWS ................................................................................................................................. 140
6.1.1.94
Invoke JSATS ................................................................................................................................. 140
6.1.1.95
API Documentation ........................................................................................................................ 141
6.1.1.96
Example .......................................................................................................................................... 141
Page 6
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.97
6.1.1.98
6.1.1.99
SAWS API test ............................................................................................................................... 142
SAWS Web service test .................................................................................................................. 142
Input file used by SAWSFileCallbackHandler ............................................................................... 143
Security Token Service (Microsoft) ......................................................................................................................... 146
Installation Guide ................................................................................................................................................... 146
6.1.1.100
Package Contents ....................................................................................................................... 146
6.1.1.101
Requirements and dependencies ................................................................................................ 147
6.1.1.102
Cryptographic key requirements ................................................................................................ 148
6.1.1.103
Installation of the STS Base Component ................................................................................... 151
6.1.1.104
Installation of the TrustCoM STS Module ................................................................................. 155
6.1.1.105
Installation of the STS Management Tools ................................................................................ 156
6.1.1.106
Frequently asked questions and common problems ................................................................... 160
User’s Guide ........................................................................................................................................................... 162
6.1.1.107
Management in the TrustCoM deployment ............................................................................... 162
6.1.1.108
Management client GUI module configuration ......................................................................... 162
6.1.1.109
Connect to the STS .................................................................................................................... 164
6.1.1.110
Creating a new federation .......................................................................................................... 165
6.1.1.111
STS modules .............................................................................................................................. 166
6.1.1.112
The “Manually-established partner list” STS module ................................................................ 167
6.1.1.113
The “Claims for real users” STS module ................................................................................... 169
6.1.1.114
The “TrustCoM pure claims validation” STS module ............................................................... 171
Developer's Guide .................................................................................................................................................. 173
6.1.1.115
STS Design overview ................................................................................................................ 173
6.1.1.116
Management model .................................................................................................................... 174
Core data structures ................................................................................................................................................ 176
6.1.1.117
Organization-internal IDs, Owners and Subjects ....................................................................... 176
6.1.1.118
FederationUUID ........................................................................................................................ 176
6.1.1.119
Business cards ............................................................................................................................ 176
6.1.1.120
Federation partner identifiers ..................................................................................................... 177
6.1.1.121
Claims-issuer policy filters ........................................................................................................ 179
Provider implementations ....................................................................................................................................... 179
6.1.1.122
Federation selector ..................................................................................................................... 180
6.1.1.123
Federation-partner providers ...................................................................................................... 180
6.1.1.124
Client-claims provider ............................................................................................................... 182
6.1.1.125
Service-access and claims-validation providers ......................................................................... 183
Policy Decision Point Service.................................................................................................................................... 184
6.1.1.126
Installation Guide ....................................................................................................................... 184
6.1.1.127
Package Contents ....................................................................................................................... 184
6.1.1.128
Requirements ............................................................................................................................. 184
6.1.1.129
Installation ................................................................................................................................. 185
6.1.1.130
Build Options ............................................................................................................................. 185
6.1.1.131
Manual Installation .................................................................................................................... 186
6.1.1.132
Testing ....................................................................................................................................... 186
6.1.1.133
Dependencies ............................................................................................................................. 187
User’s Guide ........................................................................................................................................................... 188
6.1.1.134
Configuring root policies ........................................................................................................... 188
Developer’s Guide .................................................................................................................................................. 189
6.1.1.135
The TrustCoM PDP Access Request Interface .......................................................................... 189
6.1.1.136
The TrustCoM PDP Management Interface .............................................................................. 189
6.1.1.137
The TrustCoM PDP Debugging and Testing Interface. ............................................................. 190
6.1.1.138
The TrustCoM PDP schema ...................................................................................................... 191
SICS SLA Management Subsystem ......................................................................................................................... 194
Installation Guide ................................................................................................................................................... 194
6.1.1.139
Package Contents ....................................................................................................................... 194
6.1.1.140
Requirements ............................................................................................................................. 195
6.1.1.141
Installation ................................................................................................................................. 195
Page 7
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.142
Configuration ............................................................................................................................. 196
6.1.1.143
Testing ....................................................................................................................................... 196
6.1.1.144
Dependencies ............................................................................................................................. 197
User’s Guide ........................................................................................................................................................... 199
Developer's Guide .................................................................................................................................................. 199
6.1.1.145
SLA Repository ......................................................................................................................... 199
6.1.1.146
VO SLA Manager Service ......................................................................................................... 199
6.1.1.147
SLA Evaluator Manager Service ............................................................................................... 200
6.1.1.148
SLA Evaluator Factory Service ................................................................................................. 200
6.1.1.149
SLA Evaluator Service .............................................................................................................. 200
6.1.1.150
SLA Performance Log ............................................................................................................... 200
6.1.1.151
SLA Template Repository ......................................................................................................... 201
6.1.1.152
The SLAM Graphical User Interface ......................................................................................... 201
HPC SLA Monitoring Infrastructure ...................................................................................................................... 201
Installation Guide ................................................................................................................................................... 201
6.1.1.153
Package Contents ....................................................................................................................... 201
6.1.1.154
Requirements ............................................................................................................................. 202
6.1.1.155
Installation ................................................................................................................................. 202
User’s Guide ........................................................................................................................................................... 203
Developer's Guide .................................................................................................................................................. 203
6.1.1.156
SLA-Manager ............................................................................................................................ 203
6.1.1.157
SLARepository .......................................................................................................................... 204
6.1.1.158
Ganglia Service .......................................................................................................................... 205
6.1.1.159
SLAMonitoringDaemon ............................................................................................................ 206
TrustCom Policy Server ........................................................................................................................................... 206
Installation Guide ................................................................................................................................................... 206
6.1.1.160
Package Contents ....................................................................................................................... 207
6.1.1.161
Requirements ............................................................................................................................. 207
6.1.1.162
Installation ................................................................................................................................. 208
6.1.1.163
Installing the Web Services Interface in Axis ............................................................................ 208
6.1.1.164
Running the Policy Server ......................................................................................................... 209
6.1.1.165
Testing the Implementation ....................................................................................................... 210
User’s Guide ........................................................................................................................................................... 211
6.1.1.166
Sending XML to the Policy Server ............................................................................................ 211
6.1.1.167
Sending an Event to the Policy Server ....................................................................................... 213
6.1.1.168
Command Line Shell ................................................................................................................. 215
Developer's Guide .................................................................................................................................................. 216
6.1.1.169
Policy Server XML .................................................................................................................... 216
6.1.1.170
Anatomy of an Event ................................................................................................................. 217
6.1.1.171
Anatomy of a Policy .................................................................................................................. 217
6.1.1.172
API Documentation ................................................................................................................... 219
6.1.1.173
Example ..................................................................................................................................... 219
BT Gateway ............................................................................................................................................................... 219
Installation Guide ................................................................................................................................................... 219
6.1.1.174
Package Contents ....................................................................................................................... 219
6.1.1.175
Requirements ............................................................................................................................. 219
6.1.1.176
Installation ................................................................................................................................. 220
6.1.1.177
Third party software installation ................................................................................................ 220
6.1.1.178
Installing the gateway ................................................................................................................ 221
User’s Guide ........................................................................................................................................................... 225
6.1.1.179
Gateway Interfaces List ............................................................................................................. 225
6.1.1.180
Gateway Federation Manager Client ......................................................................................... 225
6.1.1.181
Gateway Instantiator .................................................................................................................. 228
Developer's Guide .................................................................................................................................................. 231
6.1.1.182
BT Gateway Design & Specification ......................................................................................... 231
6.1.1.183
API Documentation ................................................................................................................... 231
Page 8
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.184
Example ..................................................................................................................................... 231
Policy Enforcement Point ......................................................................................................................................... 232
Installation Guide ................................................................................................................................................... 232
6.1.1.185
Package Contents ....................................................................................................................... 232
6.1.1.186
Requirements ............................................................................................................................. 232
6.1.1.187
Installation ................................................................................................................................. 233
6.1.1.188
Install Enforcement Management Web service ......................................................................... 233
6.1.1.189
Installation of Enforcement Runtime ......................................................................................... 233
User’s Guide ........................................................................................................................................................... 233
Developer's Guide .................................................................................................................................................. 234
6.1.1.190
Enforcement Runtime (Proxy Server) ........................................................................................ 234
6.1.1.191
Enforcement Runtime (XML Payload Processing) .................................................................... 237
6.1.1.192
Management Service .................................................................................................................. 241
Service Instance Registry (SIR) ............................................................................................................................... 241
Installation Guide ................................................................................................................................................... 241
6.1.1.193
Package Contents ....................................................................................................................... 241
6.1.1.194
Requirements ............................................................................................................................. 242
6.1.1.195
Installation ................................................................................................................................. 242
User’s Guide ........................................................................................................................................................... 243
6.1.1.196
Testing the Installation ............................................................................................................... 243
6.1.1.197
Working with the SIRGUIClient ............................................................................................... 244
Developer's Guide .................................................................................................................................................. 246
6.1.1.198
SIR ............................................................................................................................................. 246
Page 9
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
1 Introduction
This document concludes the overall TrustCoM development process and contains the description
of the Reference Implementation components
Chapter 2 presents a short architecture overview.
Chapter 3 reflects on the history of the development process.
Chapter 4 lists the major system components, while Appendix A contains complete installation guide
and user manual.
Chapter 5 presents Risk Analysis tool developed by the project, explains its functionality and its
importance for the project.
This document does NOT include component developer reference. Instead such reference is
provided in the electronic form, convenient for development work together with the published
software.
Page 10
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
2 Architecture Overview
The implementation and integration process in Action Line 2 is strongly coupled with the design work
in Action Line 1: whilst the conceptual and architectural models define the high-level functional
requirements, the implementation work actually verifies and refines the models in more detail, i.e.
identifies potential gaps on the protocol level.
Implementation is proceeding along the directions of the architecture and is broadly aligned with the
architecture specifications. Therefore, we briefly summarise the TrustCoM architecture in this
section to better place in context the subsequent sections. This will also help understanding a) the
choice of components for implementation and b) their respective roles in the overall processing of a
Virtual Organisation.
The Subsystem Segmentation
Within TrustCoM we distinguish components logically according to the functionalities they realise
within the full framework. These logical groups are denoted as “subsystems” that each comprise
multiple components. With the general requirements of TrustCoM in mind, we have designed and
are in the process of implementing and integrating the following subsystems:
 VO Management (VOM)
In order to allow for coordinated, well-structured and secure operation of Virtual Organisations,
management services and components are required to maintain information about status of the VO
(like participants, their location, relationships etc.) and to coordinate the enactment with respect to
the individual requirements (like triggering the necessary steps to replace a participant; starting,
pausing and/or halting a business process etc.).
Though such functionality could be distributed across VO participants this would both significantly
increase the complexity and the burden on each of the VO participant‟s infrastructure.
 Business Process Enactment and Orchestration (BP)
Each Virtual Organisation pursues a business goal, which it tries to achieve using a business process
describing each participant‟s behaviour. Note that each participant may enact a business process on
its own to realise its task(s). This is encouraged by TrustCoM, yet not mandated, in order to cater for
businesses that choose to implement their services through their own private models.
The Business Process Enactment and Orchestration subsystem caters for the necessary
functionalities to derive, enact and manage VO-wide workflows achieving initial (business) goal. It
furthermore supports conversion of VO-wide task description to local, participant-specific workflows.
 SLA Management Services (SLA)
Participants in a Virtual Organisation are bound by contracts specifying the terms and conditions
(rights, privileges, limitations etc.) of their involvement in the VO. Beyond legal issues (like law
applicability etc.), many terms of such contracts may be supervised and enforced electronically
through the means of Service Level Agreements.
The SLA subsystem is responsible for supporting the generation and management of the SLAs, as
well as for providing the means (supervision and evaluation) necessary for their enforcement. Note
that “enforcement” does not imply that SLA management provides the agreed service but rather it
monitors the service provided and checks compliance with the contractual terms and conditions
including service performance and other SLA parameters.
 Trust & Security Services (T)
Security is obligatory for the enactment of Virtual Organisations as most message exchange contains
sensitive data. In order to reduce the risk of misuse of the involved resources, access must be
restricted to certified collaboration partners only. Notably, these access rights may be delegated
between participants, if the service provider allows such behaviour. Components of this subsystem
Page 11
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
take care of issuing, distributing and managing the relevant security tokens for identification within a
Virtual Organisation. Note that the access rights themselves are encoded as policies.
Furthermore, this subsystem caters for management of reputation by collecting performance
information within the Virtual Organisation and maintaining these outside for cross-VO availability.
 Policy Control (P)
Policies may be regarded as the “heart and soul” of every VO enactment next to the business
processes. Policies define the general management strategy of the VO in the form of declarative
rules which specify how the VO should behave (or adapt) in specific conditions such as for VO
evolution, enforcement actions on SLAs (cf. above) etc. Note that policies only define which actions
need to be performed, they do not provide an implementation of those actions e.g., in the form of a
workflow.
In addition, access control policies comprise both authorisation policies that define which entities are
permitted to access services within the TrustCoM framework and under which constraints, and
delegation policies which specify permissions on the delegation of administrative permissions.
 Infrastructure Support (I)
Not a real subsystem in itself, the respective components and services comprise a set of
functionalities enabling general messaging and supporting essential tasks in the overall VO
execution. Infrastructure Support may be considered as underlying most functionalities within the
framework, covering such issues as notification support, message interception, information registries
etc.
Subsystem Interactions
Each of the subsystems described in the previous section realises a specific subset of the
functionalities required for the full TrustCoM framework. In order to realise the full set of capabilities,
the subsystems depend upon each other regarding information exchange - these relationships
between the individual subsystems are summarised in Figure 1. Note that VO Management services
play a very central role in this design, as they coordinate the distribution of relevant data and trigger
the according (general) functionalities.
For example, the VO Management components can not issue and manage security components
itself, whilst the Trust & Security related components do not maintain information about the members
in a Virtual Organisation or when they are integrated and configured. Thus VO Management will
provide the required information in time to the Trust & Security subsystem which will then configure
the Security components according to the respective conditions and requirements.
Page 12
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Information
Coll. Def.
.
pr
ov
ide
po
lic
ies
phases
Policy
actions
Policy Services
- „authorises“ access
- enacts policies (ECA rules)
- triggers adaptation actions
es
Po
te
nt
ial
QoS status
pa
rtn
er
s
Status, SLA
VO Management
- triggers phases
- maintains membership
- manages roles
- specifies context information
phases
phases
Reputation
as
ph
SLA templates
SLA Management
- publishes QoS information
- monitors & supervises
performance
- negotiates SLA terms
rights
phases
Trust & Security
- issues & validates tokens
- authenticates senders
- provides reputation
Infrastructure support
- enables messaging/notification information
- supports discovery
- maintains instances & resp. info.
ta
- triggers instantiation
da
ce
n
a
rm
rfo
pe
BP Management
- provides collaboration defs.
- derives process views for
roles
- leverages invocations
Figure 1: The subsystems and their relationships
Deployment Overview
Following the concepts of Service Oriented Architectures, the deployment of the aforementioned
components is strongly usage-dependent, i.e. the components required by each participants in the
Virtual Organisation not only depend on his/her local demands with respect to realising the required
functionalities, but also on the individual requirements towards the VO, including such issues like
outsourcing critical capabilities to third parties (e.g. SLA evaluation, policy verification etc.).
Accordingly, there is not “a single” deployment of the TrustCoM framework but a wide range of
possible deployments depending on the requirements for VOs within the Enterprise Network context
in which they must be created. This makes it difficult to describe all the possible deployments and
thus the full capabilities of the framework. Instead, this section focuses on a typical setup which is
described in (Figure 2). Such a setup attempts to maximise support for VO participants and thus
minimising the requirements placed on their own infrastructure support, so that no participant
contributions (besides for the actual resources) are required. Implicitly, all components deployed
locally may be considered optional in the sense that they may be omitted if the respective
functionality is not required. In the simplest case, all participants of the VO - besides for the VO
Manager - would hence be configured as depicted in Figure 2, bottom right, i.e. by deploying parts of
the Trust & Security, Infrastructure support, Policy Services, SLA Management and BP Management
subsystems. Note that this does not involve all components of the respective subsystems, but only a
specific subset. As such, “Trusted Third Parties” are concerned, even though they generally require
less strict support, whilst “Supporting Services” should realise their functionality independently from
1
the TrustCoM framework support . The most striking exception is the VO Management service that
can realise its maintenance and coordination tasks only with the support from other subsystems‟
components (like e.g. Trust & Security).
1
This does not hold true completely, as most of the Supporting Services are actually developed in
the TrustCoM project and thus logically belong to the aforementioned subsystems - however, for
these types, services and components have to be considered identical, i.e. no additional supporting
components are required.
Page 13
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Supporting Services
BP
Repository
Service
Description
Repository
SLA Template
Repository
Reputation
Management
Service
Trusted Third Parties
VO Policy
Service
Discovery
Service
Reputation
Evaluator
Notification
Broker
Secure
Audit Log
„Gateway“
Trust &
Security
Infrastructure
Support
SLA
Management
SLA
Evaluator
SLA
Performance
Log
„Gateway“
Policy Services
Trust &
Security
VO
Management
SLA
Management
Infrastructure
Support
Policy Services
BP
Management
VO Management Service(s)
Resources
Resources
LEGEND
Service
Service with
Gateway
Subsystem
specifc
Components
Sevice Provider (any)
Figure 2: A possible deployment of subsystems in a Virtual Organisation. Note that in
particular Trusted Third Party services may realise a structure similar to the Service Provider
(bottom right). TTP and Supporting Services may consist of just one component of the
subsystems.
The architectural view on the TrustCoM framework reflects a more “ideal” model than
implementation can realise in the given time – hence the integration efforts as depicted in the
following sections must be regarded as excerpts of the model described here. The Integration
Scenarios have generally been chosen with particular care to address particular interaction issues
rather than a complete view on the framework. As such they may omit specific functionalities, even
though conceptually required (e.g. non-security enhanced interactions). This does not mean,
however, that the respective functionalities have been considered irrelevant or otherwise discarded,
nor does this mean that the functionalities can not been added retrospectively.
Page 14
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
3 TrustCoM implementation methodology
The work on development of Reference Implementation has started during the spring of 2005, i.e.
around Month 13-14 of the project. By that time the core TrustCoM architecture was developed. At
the same time quite a lot of preliminary components were also available as pre-existent knowledge
or as results of the first development efforts performed during the first year of the project.
The first big workshop targeted to common and integrated development of Reference
Implementation was held in May 2005 in Stuttgart. During that workshop initial development plans
and overall strategy was created.
We have started from extensive review of all software components available by that time (like STS,
Gateway or Reputation service); created feature list for each component and agreed on the features
that needed to be implemented during the first period.
That initial implementation took entire summer of 2005. The work was coordinated via e-mail
communication, sharing the code and documents through SubVersion installation and via two
workshops in Aachen and London (July and September 2005 respectively).
By October 2005 the project has reach and extensive set of components that had ~70% of the
features required by the Reference Implementation. However these components were isolated –
there were no integration and common interfaces necessary for the components interaction were not
available.
Nevertheless, the availability of the components was quite a milestone achievement in itself. The
initial demos were prepared and showed to the project reviewers in October 2005. (The components
showed were described in details in D19)
The same month has marked the beginning of the “integrated development” that resulted in
Reference Implementation production. In other words the development process transformed from
the isolated partners effort to the “true” collaboration.
To make the process of such serious and complicated development possible the project has
approached the methodology of “Integration Scenarios”.
This means that several sample scenarios were created for implementation. Each scenario was a
simplified and restricted version of the complete Reference Implementation. (The scenarios were
described in details in D53)
Overall three scenarios existed. Each was divided in three phases. Each phase delivered more
functionality than the previous one. And in the end, after phase three, the complete Reference
Implementation together with the two test beds were supposed to be delivered.
Page 15
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 3. TrustCoM Integration Scenarios
The work during this phase was coordinated via weekly conference calls and regular developer
workshop (we had roughly one work shop each two months).
In July 2006 the software developed during Phase 1 was made available to the Reviewers and in
October 2006 demos based on the outcome of the Phase 2 were presented during the project
review.
Final development phase (Phase 3) spanned four months between October 2006 and February
2007 and included intensive work on finalizing and freezing interfaces specification, workflow
diagrams as well as testing and bug fixing.
The coordination was done in the same way but the number of workshops was increased – we had
three of them during the last period.
Finally by the end of February Reference Implementation was developed and presented during the
project review in March 2006.
Project human resources were limited; because of that the work of making the component
documentation was initiated only after the major development was done. Also the last three months
of the project were dedicated to work on industrial demonstrations that will be presented during the
last project review in July 2007.
Page 16
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
4 Component overview
This section contains general overview of each of the key components listed in the table below, with
their respective owners.
Name of the component
Responsible Organization
VO Toolkit (VOM)
SAP
Notification subsystem
HLRS
Reputation Service
UoK
Secure Audit Web Service (SAWS)
SICS
Security Token Service (STS)
EMIC
Policy Decision Point (PDP)
SICS
SLA Management Subsystem
SICS
HPC SLA Monitoring Infrastructure
HLRS
Policy service
IC
Gateway
BT
PEP
BT
Service Instance registry
HLRS
For clarity and neatness of the documentation we have chosen to place the installation and user
guides for the components in Appendix A of this document.
Page 17
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Virtual Organization Management Toolkit (SAP)
The VO management of TrustCoM includes the first implementation of a management architecture
spanning the entire life-cycle of VOs providing services and protocols for each of the phases, called
the VO Management Toolkit. It provides a unified GUI management interface supporting the
administrator to easily handle all aspects of VO management. Furthermore, it offers a high degree of
greatly reducing management efforts.
Virtual Organization Management Toolkit: The VO Management Toolkit development goals are to
provide services, tools and interfaces required to create an on-demand VO. It is considered as
complementary to the Enterprise Network support tools, in that it was developed with a top-down
view on the application support required for an on-demand VO. The toolkit is deployed as three
distinct components, called editions. These editions bundle the functionality as required by different
companies within a VO:



The “Host Edition” provides VO-wide services such as member registration and monitoring of
VOs. It is the central place of storage for VO databases and services.
The “Initiator Edition” allows the creation of VOs. It provides the user interface to all services
required for managing a VO. It can trigger all the changes in the lifecycle of a VO.
The “Member Edition” allows the participation in a VO. It stores the state of the member in each
VO and provides basic communication services.
The lifecycle of a VO contains four phases which are covered by the toolkit‟s management services
and protocols. In the “Identification” phase a new VO and its business goals, workflow, policies and
SLAs are defined. During the “Formation” phase potential member candidates of the VO are
searched, combined and assigned to their individual roles. During the “Operation” phase the
business workflows are executed to achieve the actual business goal of the VO. In particular this
means that the companies‟ services are executed as part of BPEL processes generated out of
WSCDL data defined in the first phase. The current state of the VO can be monitored with the toolkit
during this phase. Finally, in the “Dissolution” phase the VO is dissolved.
It is intended that the Toolkit can be used as a test system for simulating the on-demand creation
and operation of virtual organizations, integrating the functionality of the various components and
subsystems developed in the TrustCoM project. This includes the user interface required for
administration of a VO throughout its lifetime, as well as the integration of the various services
required to secure and monitor the reputation and contractual-compliance of interactions in the VO.
Notification subsystem
The initial Notification subsystem consists of two components: the Notification Proxy (local to the
nodes on which the notification producing and consuming services reside) and the Notification
Broker. Their task is to allow notification passing in the VO Infrastructure with a minimal
implementation effort for the service providers – this involves topic handling, notification forwarding,
subscription management, etc. In general, the Notification Proxy takes over notification management
at the service provider nodes, while the Broker is responsible for managing multiple topic sources
and subscriptions to them. The Broker may also act as an intermediary for notification forwarding, if
subscribers are unknown to the notification source.
Page 18
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Service Provider 1
Service Provider 2
Tester Application
Tester Application
raise event
raise event
log
log
instantiate
subscribe
to topic
subscribe
to topic
event handler
instantiate
event handler
Notification
Proxy
Notification
Proxy
event message
na
ve
s
nt
In
te
r
le
le
na
ve
nt
s
r
te
In
4) register
as producer
2) subscribe
to topic
5) forward
subscription
Notification
Broker
1) Get Broker EPR
3) Get Broker EPR
„Registry“
instantiate
broker
Register broker
Tester Application
The scenario assumes two service providers, one acting as a notification producer and the other as
an event sink. The provider acting as event source will register with the relevant topic. The event
sink will subscribe to this topic, in order to register any notifications produced by the event source.
Notably, any producer of the same topic registered at a later time would automatically update the
subscriptions of the event sink, unless otherwise specified.
Reputation Service
The reputation service is a web service, which can be invoked remotely for maintaining the
reputation of service providers (or indeed of any entity). Each service provider in a virtual
organisation must be added into the reputation service with an initial reputation score before its
reputation can be updated. The reputation score of an entity may change when one entity of the
reputation service (the trustor) provides a reputation score for another (the trustee) but the trustor
can not be the same entity as the trustee (i.e. you cannot alter your own reputation). For example,
the reputation evaluator is an entity, which may provide a reputation score for a particular service
provider, based on the SLA message it received.
The reputation service provides four methods: addActor and addActorExisting- to add an entity into
the service; rate - to provide a reputation score for an entity, and getReputation - to get the
reputation score of an entity.
Each entity in the reputation service is identified by a string, which may represent a url e.g.
http://csharp.hlrs.de/necantenna.asmx:WSDLSOAPsomeOperationNew, or anything else. Each
identifying string must be unique within the reputation service, but the service does not care what the
string values are.
A valid reputation score is between 0 and 1, where 0 represents the worst reputation (completely
untrustworthy) and 1 denotes the best reputation (completely trustworthy). Every entity that is added
Page 19
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
to the reputation service without an initial reputation will be given the value 0.5 as its initial reputation
score, which denotes a neutral reputation.
The reputation-scoring equation is
score  Overall _ score
C 1
where C is the number of reputation scores given to the entity.
Initially for new entities, Overall_score is set to S and C is set to N, where S denotes the initial
reputation score given to the entity; N denotes the Initial number of scores. The default value for S
and N are 0.5 and 0 respectively. Any pair of S and N given to a new entity, where N>0, represents
the entity has imported reputation from another system. If an entity is given the reputation score with
the value V then the new overall score of the entity is obtained by
Overall _ score  P  2 * P *V
C * (1  (2 * P C  1) * (2 *V  1))
where P denotes the previous overall score the entity has.
A reputation score can have a value between 0 and 1. A value less than 0.5 denotes a negative
reputation, which will cause the reputation score to drop. However, a value greater than 0.5 denotes
a favourable reputation, which will increase the reputation score. A score of 0.5 will not affect the
score. The more reputation scores an entity has been given, the less effect one more score will
have.
In order to facilitate initialisation of the database, in which entities and their reputation score are
stored, a database management service is also provided. This management service has two
methods i.e. initialise and drop. The initialise method is invoked to create all needed tables and
initialise them for the reputation service, according to given database schemas. These tables can be
removed by calling the drop method so that the initialise method can be called again.
Secure Audit Web Service
The secure audit web service (SAWS) provides a secure audit trail service for multiple clients. Client
log messages are sent to SAWS so that administrators can at a later point in time know who did
what, by using either the Viewing Tool (VT) that is part of the package, or their own analysis
software. SAWS will store any information that is sent to it by clients. since it treats all client
messages as opaque binary strings. The secure audit trail generated by SAWS can be stored on
any untrusted machine and it is impossible to be modified or destroyed without detection, and its
integrity can be validated by any client by checking the digital signature on the audit file. Optionally,
the audit file can be encrypted, making it impossible for unauthorized parties to read its contents.
SAWS meets the following basic security requirements and functionalities:
(1) Only append mode of access is allowed, so that users or applications cannot rewind the audit file
and delete or modify information that has already been stored there.
(2) Only authorised parties are able to append log records to the audit trail. Though unauthorised
applications or attackers may gain access to the audit trail and try to append fake log records to the
audit trail, or modify or remove genuine records from the audit trail, this can be detected.
(3) Every record in the audit trail is time-stamped by SAWS to provide a trusted record of when the
audit data was received.
Page 20
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
(4) The communications between a SAWS client and the SAWS server ensure tamper resistance,
data integrity and authorised connection.
(5) The SAWS security mechanism ensures persistent and resilient storage of the audit trail, and
ensures detection of tampering of the audit trail – modification, deletion, insertion, truncation, or
replacement. If tampering is detected, SAWS is able to notify the security auditor.
(6) SAWS is accessible via a web service, and is able to serve multiple client applications
simultaneously.
(7) SAWS is able to record any digital content coming from any SAWS client.
(8) Optionally, SAWS is able to encrypt the audit files and ensure that only authorised applications or
people have permission to decrypt and read the audit files.
(9) A Java Secure Audit Trail Service (JSATS) is also provided as a Java API and this forms the
basis and core functionality of SAWS. JSATS can be integrated directly into Java applications,
thereby improving performance and bypassing the web services overhead of SAWS.
The core of SAWS is a SAWS server working on top of a web service server i.e.Tomcat + Axis.
SAWS clients send their logging messages to the SAWS server via the web service interface, and
the communication between SAWS clients and SAWS is protected by SSL for security purposes.
SAWS works on both Linux and Windows platforms.
Security Token Service
STS Overview
The security token service (STS) is a web service which issues and validates security tokens. Web
service clients and services use security tokens to protect web service invocations, i.e., a token can
be used to digitally sign and/or encrypt SOAP messages. The STS‟ communications protocol is WSTrust, i.e., token issuance and validation is done through WS-Trust compliant message exchanges.
A SOAP message can be protected with a security token using the security mechanisms defined by
the set of WS-Security specifications and profiles, which define how digital signatures and
encryption are applied to SOAP messages.
Beside the core WS-Trust token exchange functionality, the security token service is manageable
through a web services-based management interface. The management tools package contains a
graphical client application for accessing that management interface and managing the STS. In
addition to GUI-application, the STS can be managed programmatically through .NET-based proxy
classes which expose the management functionality to custom applications.
The Microsoft EMIC STS is an extensible hosting environment, which allows developers to write
customized modules (plug-ins) for the STS. The STS can host multiple module configurations at the
same time, which allows highly dynamic scenarios: For example, the functionality how security
tokens are generated (including the token format), is extensible; an installed STS can support
generation of custom XML tokens, SAML assertions, and X.509 certificates at the same time. Each
token request can be dispatched to different token generation configurations, which offers a wide
range of scenarios. Other extension points include the supported claim types, or the way how claims
can be retrieved or validated (a „claim‟ is a statement such as a role statement, which can be
embedded and crypt.
TrustCoM modules and interactions
The STS‟s TrustCoM-profile configuration contains a specific set of modules: A token generator for a
TrustCoM-specific SAML profile, XACML attributes as claims, a partner (VO membership) module
Page 21
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
based on cryptographic business cards, and a token validation module which allows the TrustCoM
environment to only validate security tokens and have the access control decision outsourced to a
given XACML-based policy decision point.
In the TrustCoM environment, an STS interacts with two major components:


The gateway of a VO member configures the STS during the initiation of the VO, i.e., the
gateway sets up the federation information in the STS.
The client‟s and service‟s policy enforcement points (PEP) use the STS during the operational
phase of the VO to request and validate security tokens.
Policy Decision Point Service
The role of the Policy Decision Point Service (PDP) is to assist services in their access control. A
service can use an associated PDP Service for determining whether a particular access to the
service should be allowed or not. The PDP will have access to the relevant access control policies of
the VO and return its decision based on the policy contents. The PDP Service does not enforce the
decision. Enforcement is left to a function called Policy Enforcement Point (PEP) in the service
calling the PDP.
In addition to the access request method, the PDP Service has functions that are used by policy
administration points (PAPs), to update the policies that the PDP has access to.
The PDP is based on the XACML standard with extensions for handling delegation.
2
SICS SLA Management Subsystem
The SLA Management subsystem provides a set of services that allow autonomous observation of
individual service providers‟ performance and comparing these to a set of previously agreed upon
quality of service parameters. The part of the SLA Management subsystem developed by SICS
provides the functionalities to compare the observed information with the terms agreed upon during
negotiation of the SLA. Upon SLA violations, the SLA subsystem generates notifications that can be
picked up by the Policy Subsystem in order to apply the proper adaptation policies.
HPC SLA Monitoring Infrastructure
The HPC SLA Monitoring Infrastructure provides components allowing the monitoring of a HPC
provider against an agreed SLA. Therefore components are provided to handle the management of
the corresponding SLAs as well as components to provide the system performance information. This
information is necessary to compare the current system status with the agreed service performance
objectives in the corresponding SLA.
TrustCom Policy Server
The TrustCom Policy Server combines a general-purpose object management system with a
Domain Service, Obligation Policy Interpreter and a Command Interpreter. The Domain Service
provides an hierarchical structure for managing objects such as policies and event types. The
Obligation Policy Interpreter handles Event, Condition, Action rules (ECA). The Command
Interpreter accepts sets of commands in the form of XML documents via a number of
communications interfaces; these documents may perform invocations on a ManagedObject
registered in the Domain Service.
2
Refer to the TrustCoM Framework Profiles document (D63 TrustCoM Framework V4 - Appendix A)
for details on the use of XACML.
Page 22
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Within the TrustCom environment, the Policy Server receives events in the form of notifications from
the TrustCom Notification Broker, turns them into internal event which are picked up by the ECA
policies. When a policy receives an event that satisfies its conditions, using the event‟s values, it
executes one or more actions. The actions typically interact with other TrustCom services
depending upon the commands written into the action.
BT Gateway
The BT gateway is the set of components that ensures the virtualization, exposure, and protection of
capabilities within a given virtual organization. The BT gateway is a set of two levels of services:
-
core services which achieve the basic functionality of the gateway such as keeping track of
capabilities, virtual resources, creating internal identities, managing infrastructure profiles; and
-
peripheral infrastructure services which achieve the overall security. These peripheral services
can change, be easily swapped for other ones. They include security token services, policy
enforcement points, event-condition-action services, policy decision points. Their list is not
definitive and typically a gateway administrator could choose to register a new one and make
use of it.
The description of the infrastructure services is outside the scope of this document. Within WP34,
the EMIC STS, the BT PEP, the SICS PDP are examples of infrastructure services that are
described in their respective documents.
This document, on the other hand, focuses on the following core services:
-
the gateway federation manager
-
the gateway instantiator
-
the token generator
-
the gateway registry
Each of these components are further described in the corresponding Appendix A.
Policy Enforcement Point
The PEP is an adaptable policy enforcement component that does SOAP level processing on behalf
of an application service. It is composed of different parts that are discussed seperately and
distributed in two packages, i.e. the enforcement application and the management service thereof.
The management component deals with virtualization of resources and the management of the
corresponding policies. It maintains an internal database that the enforcement component uses to
locate the policy for a given endpoint.
The interceptor component is responsible for handling the message on the network. It intercepts the
message, strips the encapsulated application message from the transport protocol, feeds it into the
enforcement engine and embeds the processed message into a new transport level message and
sends this on to the next destination.
The enforcement component processes the SOAP message based on the policy it retrieves for this
virtualized resource and any other information that can be derived from the state of the virtualized
resource or the context of the message exchange. It sends relevant information about the
enforcement process to the management interface of the virtualized resource which publishes these
messages to WS-Notification consumers.
Service Instance Registry (SIR)
The Service Instance Registry (SIR) is in principal a kind of storage system based on a relational
database. It allows the handling of logical names (e.g. could be an identifier or anything else) together
Page 23
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
with their corresponding physical addresses (endpoint references) just as well their belonging to an
existing federation (VO).
The SIR provides a Web Service interface which allows the users to deal with the data store. The store
can be directly accessed by calling different Web Service actions which among other things allow the
manipulation of the stored data.
Typically, every participant of a Virtual Organization (VO) should run its own SIR to guarantee
transparency of services, resources, and applications.
Page 24
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
5 Tools
To reduce the risks involved with establishing, joining and operating a VO, an approach is needed
for analysing and managing legal risks which takes into account both technical and non-technical
aspects. Risk analysis is an elaborate and prolific process which involves many different types of
documentation from different sources, such as UML models, tables with analysis data, and natural
language descriptions of the target of analysis. All this information needs to be organised and
accessible. In addition, it is important to maintain consistency between all the information elements
to prevent errors, and we also wish to be able to reuse elements from previous analyses where
appropriate to avoid starting from scratch every time. Computerised support for documentation,
maintenance and reuse of analysis results is thus of high importance.
Legal Risk Analysis tool
One of the goals of TrustCoM WP9 has been to develop methods and languages to facilitate legal
risk analysis. In parallel, WP34 has worked on the development of computerised support tools.
These results have been based on the existing CORAS model-based security risk analysis method,
the CORAS risk modelling language and the CORAS Tool.
The CORAS framework for model-based risk analysis consists of among other things a method, a
graphical modelling language, and a computerised tool. Based on experiences from using the
3
CORAS Tool in a number of risk analyses of security, trust and legal issues throughout the
TrustCoM project, several improvements have been made to the tool in order to better support legal
risk analysis.
Legal risk analysis seeks to identify risks related to the collaboration within a VO, affecting either the
common business goal or the assets of the participants. Since a detailed risk analysis is costly and
time-consuming, it will typically only be economically efficient to use it as a preparatory step in the
definition of contractual frameworks and templates, for example in the context of establishing an
4
enterprise network (EN) .
The CORAS Tool
5
The CORAS Tool is a Java-based risk analysis tool which is publicly available as open source . The
client-server architecture of the tool enables multiple risk analysts to collaborate on the risk analysis
projects. The risk analyst uses the CORAS client application to create new analysis projects,
document and edit risk analysis results in tables and diagrams, generate analysis reports, and
manage and reuse experiences from previous analyses. Information can be imported from various
modelling and risk analysis tools used by the analyst. The tool also contains a built in diagram editor
for the CORAS graphical language. Help is provided to the user in the form of integrated online
versions of the CORAS method and user guides. A screenshot of the CORAS client application is
shown in Figure 4.
3
Vraalsen, F., den Braber, F., Lund, M. S., Stølen, K. (2005). The CORAS Tool for Security Risk
Analysis. In Proceedings of the 3rd International Conference on Trust Management (iTrust ‟05).
Paris, France: Springer LNCS 3477, pp. 402-405.
4
Mahler, T., Vraalsen, F. (2006). Legal Risk Management for an E-Learning Web Services
Collaboration. The First International Conference on Legal, Security and Privacy Issues in IT (LSPI).
Hamburg, Germany.
5
http://coras.sourceforge.net/
Page 25
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 4 The CORAS Tool
There are two databases or repositories in the CORAS Tool. The analysis repository stores results
from the ongoing and completed security analyses, while the experience repository contains
reusable results from previous analyses in the form of UML-models, checklists, procedures and
more. By facilitating reuse, the tool helps the user avoid starting from scratch for each new analysis.
All information in the repositories is versioned. The repositories are implemented on top of the open6
source XML database eXist .
Companies have existing investments in licenses and training for a wide variety of UML modelling
tools and security analysis tools. It is therefore important to provide flexible support for integration
with external tools. Standardised XML formats are utilised for data integration, such as XMI for the
interchange of UML models.
Information is extracted from the models, tables and so on into an internal risk analysis data model
which is used for various purposes, such as consistency checking. Consistency rules are defined
7
using the CLiX language. The internal model is also used to assist the user in various tasks, such
as providing content suggestions when filling in tables. Figure 5 shows an overview of the CORAS
tool architecture.
6
Meier, W. (2002). eXist: An Open Source Native XML Database. In Web, Web-Services, and
Database Systems. Erfurt, Germany: Springer LNCS 2593.
7
Constraint Language in XML, Systemwire, http://www.clixml.org/ (visited February 2005)
Page 26
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Tool
user
CORAS tool
External tool
Tool
integrator
CASE
tool
Riskanalysis
tool
CORAS
Tool
GUI
User
interface
CORAS XML,
XMI, IDMEF, ...
CORAS integration API
Integration
interface
Tool
developer
Analysis
repository
Reuse
Experience
repository
Documentation assistance
Consistency checking
Internal data model
Figure 5 CORAS Tool Architecture
Improvements to the CORAS Tool
As mentioned above, numerous improvements have been made to the CORAS Tool during
TrustCoM. Some are specific to legal risk analysis, while others are of a more general nature. As an
example of the latter, the user typically needs to enter a lot of data into various tables. To assist the
user, support for copy & paste between the CORAS Tool and existing documents in third-party
applications such as Microsoft Word and Excel has been enhanced.
The graphical CORAS language has undergone a number of changes to improve expressiveness
and clarity, as detailed in D17 Appendix A. Icons have been added to represent specific legal
threats, vulnerabilities and treatments, e.g. as shown in Figure 6. The integrated modelling facilities
in the CORAS Tool have been updated to reflect this.
Page 27
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
ReduceLikelihood
Specify jurisdiction and
choice of law in contract
Content providers
reluctant to join EN
ReduceLikelihood
Legal uncertainty due to
different copyright laws for
different VO partners
Content made available
to the public
Public educational
institution
§52a UrhG in German law
permits distribution of content
for tuition and research
Figure 6 Legal threat, vulnerability and treatment
8
Information in CORAS is organised according to viewpoints, as defined by RM-ODP . A „legal‟
viewpoint has been added to the existing more technical viewpoints in RM-ODP, facilitating
annotating and retrieving information of a legal nature.
Checklists of legal risks have been defined, as detailed in D17 Appendix A. These checklists have
been made available to the users of the CORAS Tool as an experience package, as shown in
Figure 4. The updated CORAS method in D17 Appendix A is also made available through the builtin online help system of the CORAS Tool.
8
ISO/IEC 10746: (1995): Basic reference model for open distributed processing.
Page 28
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6 Appendix A – Components installation and user
guides, samples
Virtual Organization Management Toolkit (SAP)
Installation Guide
6.1.1.1
6.1.1.1.1
Package Contents
Source Directories
The most important project is, of course, the VO Management Toolkit itself. The source directories
for this project are "src" and "test". Most classes are in the package com.sap.toolkit.console
respectively its subpackages. The toolkit is structured according to the Model-View-Control pattern
so the corresponding classes are in the subpackages "model", "view", and "action". Furthermore,
there are subpackages for the web services the toolkit offers ("webservices"; each web service has
an additional subpackage), for the installation of the toolkit ("install"), for the Policy Generation
Component ("pgc") as well as a general utility package ("util").
The toolkit is divided in three different editions (host, initiator, and member) with three different
responsibilities. Several packages contain corresponding subpackages including only the edition
specific classes. There is no direct communication between these editions respectively there is no
data exchange between the classes of one edition to classes of another edition. The only way for
communication is using the web services a toolkit offers. Currently, if a host edition is installed also
the initiator and the member edition will be installed. So all three editions can be accessed by the
same URL. Nevertheless, these editions are completely separated as described above.
There are a few very important classes among the whole toolkit. The class Globalconfiguration
(package util) consists of global configuration data. It retrieves the data out of configuration files. The
class URLHelper (package util) gives support for constructing certain URLs out of several data
items. The class ServiceEndpoints (package util.webservices) contains constants for the web
service names so that this class can be used in conjunction with the URLHelper class to construct
calls to web services. The package util.language consists of the message bundles for the toolkit.
Therewith new languages or just new message items can be added to the toolkit user interface (UI).
Furthermore, every edition has its own central model class (in the corresponding subpackage of the
package model). This class is responsible for execution of most of the toolkit's functionality by
reading the current state from and writing the new state to the database. At last, the class Installer
(package install) can be used for installing the toolkit.
6.1.1.1.2
Build Directory
Page 29
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The class files resulting from the compilation are in the "jsp" directory. This directory contains not
only the class files but also some other files needed for the GUI of the toolkit. It is a kind of toolkit
template in such a manner that this directory will be copied to the installation target directory during
the installation procedure.
6.1.1.1.3
Directory "3rdparty"
The "3rdparty" directory consists of all additional external tools which are needed for running the
toolkit. This comprises a web server (tomcat), a database (MySQL), a web service engine (axis), a
BPEL engine (AciveBPEL) as well as some other minor tools. These tools will be automatically
installed during the first installation of the toolkit.
6.1.1.1.4
Directory "conf"
The "conf" directory consists of configuration data for the 3rd party tools which is needed during the
installation and initialization of these tools. A part of these files are directly used while others act as
templates that are customized during the installation.
6.1.1.1.5
Directory "doc"
The "doc" directory contains documentation for the toolkit such as the source code documentation,
the system test cases or the user guides.
6.1.1.1.6
Directory "editionInitialisation"
The "editionInitialisation" directory consists of ant scripts which are used for triggering the
initialisation of 3rd party tools. The subdirectory "webservices" consists of scripts which are
responsible for building and deploying the web services. The scripts correspond to the edition which
has to be installed. They trigger the installation by delegating the work to other ant scripts in the
"webservices" directory (of the project, not of the "editionInitialisation directory") which are
responsible for only one single service. Since the host edition currently contains also all other
editions all corresponding scripts have to be executed to set up the web services for the host edition
properly. By manually execution of one of these scripts the corresponding web servcies are installed
anew for the last installed toolkit instance.
Apart from the edition specific web services there are also two scripts which deal with deployment of
the Policy Deployment Point (PDP) as well as the example business processes.
Most scripts mentioned above delegate some of the work to the wsdlMacro.xml file which defines
ant macros for proper deployment of the web services. Usually, the main macro "wsdl-base" just
deploys the web service at the main axis or the toolkit instance's axis. But if the commented ant
tasks are commented in again the web service will be generated completely new prior deployment.
This comprises the generation of the wsdl file, the stubs, the deployment classes as well as the
compilation and copying of all relevant files to the current toolkit installation directory. This can be
Page 30
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
used to adapt the code, for example, when a web service interface has changed or a new service
has been added. It can also be used to change the wsdl encoding from "RPC/encoded" to
"document/literal".
6.1.1.1.7
Directory "lib"
The "lib" directory contains several libraries needed for compiling the toolkit. Some are also copied
to the toolkit destination directory during installation.
6.1.1.1.8
Directory "properties"
The "properties" directory consists of property files needed for the installation of the toolkit and its
3rd party tools. During installation a further file "initialise.properties" is created which contains data
needed for initialisation of the toolkit.
6.1.1.1.9
Directory "webservices"
This directory contains the ant scripts for building and deploying the web services. Each script is
responsible for only one specific web service. The scripts are separated according to the editions the
web services belong. This means that the subdirectories each contain the scripts for all web services
belonging to the corresponding edition. Some scripts may be in several subdirectories to indicate
that several editions need this service.
Apart from the edition subdirectories they may also be some other directories (such as "pdp")
containing certain files belonging to a web service which cannot be deployed in the standard way
(such as the services in the edition subdirectories).
6.1.1.1.10 Other Files
Apart from the files in the varios directories there are also some important files in the root directory
of the project. First, there are the two ant scripts "createBinaryPackage.xml" and
"createSourcePackage.xml". These scripts can be used to create source or binary packages of the
project which can be transferred to other computers. They contain only the necessary files.
Second, there is the file "runInstallation.bat". This file can be used to install a toolkit instance. All
needed information will be retrieved during installation.
Third, there is the "README" file containing installation instructions. It describes the whole
installation procedure.
Page 31
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Requirements
The following requirements are neccessary for installing and running the VO Management Toolkit
software:








Windows XP
Internet Explorer 6 or Mozilla Firefox minimum Version 1.0.3
JavaScript and Cookies enabled.
Java SDK Version 1.4.2.
System variable JAVA_HOME set correctly.
No other MySQL Server on Port 3306.
Port 8080 not blocked by other applications or firewall.
Existing network connection to all participating computers.
Installation Steps
1. Execute the class com.sap.toolkit.console.install.Installer in Eclipse or run the runInstallation.bat script
from the command line. Make sure that the JAVA_HOME environment variable is set to a valid JDK and
that the "java executable" plus "keytool" can be found in the path.
2. The installation settings are displayed. Default settings for the location of the toolkit application and the
3rd-party tools are shown and the user is asked whether he wants to change these settings. If this is the
first installation all 3rd-party tools should be installed. If this is a subsequent installation the path to the
existing 3rd-party tools must be set, otherwise they would be installed anew. If the user decides to
change one or more paths he has to type in "y".
a. The user is asked for each different path whether it should be changed. Changes can then be
made by defining a new path in the appearing window.
3. After defining the installation paths the user is asked for the location of a valid Java SDK (version 1.5 or
higher). It is essential that this is really a path to a Java SDK and not only to a JRE. If the path must be
changed the user can alter it by entering a new one in the appearing window (see also 2a).
4. After defining the essential installation settings the various 3rd-party tools are installed.
a. If the tomcat web server is installed for the first time the desired port where the web server
should listen must be entered at the command line. The default value is 8080.
b. A valid external IP address (or server name) where the tomcat web server runs must be entered
(without proceeding "http://") if the default value is not appropriate. This address is used during
the installation and as a default value for the toolkit configuration.
c. If the MySQL database is not already installed the user is asked to enter the port where the
database should listen. The default value is 3306.
d. If MySQL is already installed the installation program tries to determine the current port. If this
fails the user has to enter the current database port manually on the command line.
e. A valid external ip address (or server name) where the database runs must be entered (without
proceeding "http://") if the default value is not appropriate. This address is used during installation
and runtime.
f. If MySQL is already installed the root password must be entered. If MySQL was installed during a
proceeding installation procedure the root password is "" (= not set).
5. After installation of the 3rd-party tools the actual toolkit is installed. Therefore, the user has to specify
which edition to install by entering a "h" for a host edition, an "i" for an initiator edition or a "m" for a
member edition. The differences between the individual editions can be found in the corresponding user
manuals.
6. After copying of all required files the toolkit must be initialized and configured. Therefore, the tomcat web
server and the database must run. If they do not run currently they can be started by the installation
program. (Note: when they are started during the installation they will be stopped again after initialization)
7. After initialization the installation is complete. If the web server and the database were not started before
the installation they can now be started with a batch file in the toolkit directory (e.g.,
Page 32
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
C:\vom\edition_0\startAll.bat). After that the toolkit is available at an URL containing the external ip
address and port number of the current system as well as the application name (e.g.,
http://localhost:8080/edition_0).
Installation Process Description
Installation
is
(as
mentioned
above)
started
by
executing
the
java-class
com.sap.toolkit.console.install. The figure below illustrates the different classes that are called as a
result and the files that are copied with source and destination. First the required third party
components are installed and after that the edition folder is created and filled with data. The
information
about
source
and
destination
is
provided
by
the
class
com.sap.toolkit.console.install.util.FileManager that reads the settings in the install properties file
(vom.src/vom_toolkit/properties/install.properties).
Page 33
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Com.sap.toolkit.console.install
Installer.installThirdPartyComponents
install.thirdParty
TomcatManager().install();
tomcatBase=3rdparty\\tomcatNEU -> tomcatFolderDestination=c:\\vom\tomcat (*.* -R)
.prepareTomcat();
mysqlBase=3rdparty\\mysql-4.1.15-win32 -> tomcatFolderDestination=c:\\vom\tomcat + „\common\lib“ (mysqlcon.jar)
lib=lib -> tomcatFolderDestination=c:\\vom\tomcat + „\common\lib“ (xalan.jar)
axisBase=3rdparty\\axis-1.3 + „\lib\“ -> tomcatFolderDestination=c:\\vom\tomcat + „\common\lib“ (log4j.properties)
mailBase=3rdparty\\javamail -> tomcatFolderDestination=c:\\vom\tomcat + „\common\lib“ (mail.jar)
lib=lib -> tomcatFolderDestination=c:\\vom\tomcat + „\common\lib“ (soap.jar)
uddi4jBase=3rdparty\\uddi4j + „\lib\“ -> tomcatFolderDestination=c:\\vom\tomcat + „\common\lib“ (uddi4j.jar)
juddiConf=conf\\juddi -> tomcatFolderDestination=c:\\vom\tomcat + „\common\lib“ (activation.jar.jar)
webserverBaseURL=localhost
ActiveBpelManager().install();
activeBpelBase=3rdparty\\activeBpel -> c:\\vom\activeBpel (*.* -R)
activeBpelBase=3rdparty\\activeBpel + „\lib\“ -> tomcatFolderDestination=c:\\vom\tomcat + „\common\lib“ (*.jar)
activeBpelBase=3rdparty\\activeBpel + „\conf\“ -> tomcatFolderDestination=c:\\vom\tomcat + „\shared\classes“ (*.*)
activeBpelBase=3rdparty\\activeBpel + „\conf\“ -> tomcatFolderDestination=c:\\vom\tomcat + „\bpr“ (aeEngineConfig.xml)
activeBpelBase=3rdparty\\activeBpel + „\dist\“ -> tomcatFolderDestination=c:\\vom\tomcat + „\webapps“ (*.war)
activeBpelBase=3rdparty\\activeBpel + „\dist\“ -> tomcatFolderDestination=c:\\vom\tomcat + „\bpr“ (*.wsr)
. adaptConfigurationFile()
. installBpelExamples()
tomcatConf=conf\\tomcat + „\bpr\“ -> tomcatFolderDestination=C\:\\vom\\tomcat + „\bpr\“ (*.bpr)
AxisManager().install();
axisBase=3rdparty\\axis-1.3 -> axisDirectoryDestination=C\:\\vom\\axis (*.* -R)
. installAxisContext()
axisConf=conf\\axis + „\axis.xml“ -> tomcatFolderDestination=c:\\vom\tomcat + "conf/Catalina/localhost/“ (axis.xml)
Uddi4JManager().install();
uddi4jBase=3rdparty\\uddi4j -> uddi4JDestination=C\:\\vom\\uddi4j (*.* -R)
MySQLManager().install();
mysqlBase=3rdparty\\mysql-4.1.15-win32 -> mySqlDirectoryDestination=C\:\\vom\\mySQL (*.* -R)
JUDDIManager().install();
juddiBase=3rdparty\\juddi -> juddiDirectoryDestination=C\:\\vom\\juddi (*.* -R)
juddiConf=conf\\juddi -> juddiDirectoryDestination=C\:\\vom\\juddi + "/build/webapps/juddi/WEB-INF/classes" (log4j.properties)
juddiConf=conf\\juddi -> juddiDirectoryDestination=C\:\\vom\\juddi + "/build/webapps/juddi/WEB-INF/lib" (activation.jar)
. installJuddiContext()
juddiConf=conf\\juddi -> tomcatFolderDestination=c:\\vom\tomcat + "conf/Catalina/localhost/“ (juddi.xml)
JDBCManager().install();
jdbcBase=3rdparty\\jdbc -> jdbcDirectoryDestination=C\:\\vom\\jdbc (*.* -R)
ACPCallerManager().install();
acpcallerConf=conf\\acpcaller -> acpcallerConfigDirectory=C\:\\Temp (vo_config.txt)
Figure 7: Install process for third party components
Page 34
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
#Properties File
#Tue Apr 03 13:51:45 CEST 2007
activeBpelBase=3rdparty\\activeBpel
activeBpelDestination=F\:\\vom\\activeBpel
axisBase=3rdparty\\axis-1.3
axisConf=conf\\axis
axisDirectoryDestination=F\:\\vom\\axis
databaseBaseURL=127.0.0.1
databasePassword=pswd
databaseUser=agent
Figure 8: Excerpt from install.properties
DSEndpoint=http\://discovery\:8080/axis/services/
DS
The
installation
for
the
actual
chosen
edition
is
done
by
the
class
com.sap.toolkit.console.install.edition. Three different classes for host, initiator and member edition
exist currently although the complete installation process takes place in the superclass
EditorManager. The figure below illustrates the edition installation.
Page 35
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Com.sap.toolkit.console.install
installAndInitialiseEdition();
install.edition
VoHostManager
VoInitiatorManager
VoMemberManager
EditionManager.install();
Com.sap.toolkit.console.install.util.PropertyFileWriter
writeInitialiseEdition()
C:\vom.scr\vom_toolkit\properties\
-> C:\vom\edition_0\application\ (initialise.properties -> editionConfiguration.properties)
.createEditionFolder()
.installBatScripts()
/edition_X/
writeMySqlStart(); writeMySqlStop(); writeTomcatStart(); writeTomcatStop(); writeStartAll(); writeStopAll();
. installJSP()
C:\vom.scr\vom_toolkit\jsp\WEB-INF\lib
jsp=jsp -> \edition_0\application (*.* -R)
. installTomcatContext()
tomcatConf=conf\\tomcat -> C:\vom\tomcat\conf\Catalina\localhost (vom.xml -> edition_x.xml)
. createKeystore()
. installDefaultLibraries()
lib=lib -> \edition_0\application\WEB-INF\lib
cdl2bpel_add_libs.jar
FederationManager-ws-client.jar
junit.jar
mysql-connector-java-3.1.10-bin.jar
org.eclipse.emf.common_2.1.0.jar
org.eclipse.emf.ecore.xmi_2.1.0.jar
org.eclipse.emf.ecore_2.1.0.jar
xalan.jar
xercesImpl.jar
xml-apis.jar
activation.jar
axis.jar
axis-ant.jar
bpel_view.jar
commons-discovery-0.2.jar
commons-fileupload-1.0.jar
commons-logging-1.0.4.jar
ecs-1.4.2.jar
jaxrpc.jar
log4j-1.2.8.jar
mail.jar
multipartrequest.jar
saaj.jar
wsdl4j-1.5.1.jar
Figure 9: edition installation process
Initialization process description
After the installation has been completed several ant scripts are automatically executed to deploy
web services and make necessary changes in the SQL database. The figure below illustrates what
ant files are executed depending on which edition is installed.
Page 36
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Com.sap.toolkit.console.install
install ();
deployWebservices();
com.sap.toolkit.console.install.initialise.Webservices.deploy ();
\vom_toolkit\editionInitialisation\webservices
ant
deployHostWebservices();
deployInitiatorWebservices();
deployMemberWebservices();
buildWebservicesHost.xml
buildWebservicesInitiator.xml
buildWebservicesMember.xml
\vom_toolkit\webservices\host
\vom_toolkit\webservices\initiator
basic_communication_host.xml
configure_service.xml
gvoa_manager.xml
LifecycleManager.xml
membership_manager.xml
uddi_proxy_service.xml
deployOtherWebservices();
\vom_toolkit\webservices\member
basic_communication.xml
port_mapping.xml
vo_management_initiator.xml
acpcaller.xml
basic_communication_member.xml
bp_management_member.xml
BPELObserver.xml
BPManagmentService.xml
cdl2bpel.xml
cdlkb.xml
locator.xml
NotificationBroker.xml
port_mapping.xml
buildWebservicesOther.xml
\vom_toolkit\webservicesWithoutSource
ACPSubServices.xml
ACPVOManagerGroupOperations.xml
vom_toolkit\webservicesWithoutSource\ACP1SubServices -> edition_0\application\WEB-INF\classes\ACP1SubServices (*.* -R)
initialiseDatabase();
com.sap.toolkit.console.install.initialise.Database
\vom_toolkit\editionInitialisation\mySQL
ant
initHostDatabase()
initInitiatorDatabase()
initMemberDatabase()
initDatabaseHost.xml
initDatabaseInitiator.xml
initDatabaseMember.xml
initGvoaDatabase()
initDatabaseGvoa.xml
initialiseJuddi();
com.sap.toolkit.console.install.initialise.Juddi
\vom_toolkit\editionInitialisation\mySQL
initHostJuddi()
ant
fillJuddiForHost();
initInitiatorDatabase()
initMemberDatabase()
initJuddi()
\vom_toolkit\editionInitialisation/juddi/host
\vom_toolkit\editionInitialisation/juddi
fillJuddi.xml
initJuddi.xml
com.sap.toolkit.console.install.util.PropertyFileWriter.java
\edition_0\application\editionConfiguration.properties
PropertyFileWriter.write();
\edition_0\application\samples.properties
PropertyFileWriter.writeSamplesProp();
PropertyFileWriter.writeInstallProperties ();
\edition_0\application\install.properties
\edition_0\application\keywords.properties
if(FileManager.getEditionType()== FileManager.HOST_EDITION) {PropertyFileWriter.writeKeywordsProp();}
Figure 10: initialization process
User‟s Guide
6.1.1.2
Installation
6.1.1.3
Installation Procedure
Page 37
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
To run installation of the VO Toolkit there are two possibilities:


6.1.1.4
Run the file “runInstallation.bat” from the root directory of the source
Execute the class com.sap.toolkit.console.install.Installer in Eclipse
For more detailed instructions refer to the section above.
Registration of Editions
After the installation is completed the registration screen can be accessed by using a web browser
and going to the URL http://localhost:8080/edition_X/“ where X is the number of the edition and
“localhost:8080” is the address and port of the web server on which the edition runs.
When an edition is first called in the browser a registration page is displayed:
Figure 11: Registration of editions
Host URL holds the address for the connection to the “host-edition”. If the host is not installed on the
same computer (localhost) the IP-address and port of that computer should be entered.
Page 38
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Your URL is the address of the current edition. If you don‟t run all editions on one computer don‟t
enter “localhost” or “127.0.0.1” here but the IP-address or name under which the other editions can
access this one (for example 192.168.X.Y).
UDDI Name and Business Key are for identifying the business entities of the company in the
database. Example names and keys for test installations are:
63C80990-2AA7-11DA-8990E3A80B507732
63FC8710-2AA7-11DA-8710E527FD2C3484
6344CFD0-2AA7-11DA-8FD0C99816EC2A2C
63A1E3F0-2AA7-11DA-A3F0B62654DE9FF7
AvioSystems
edition_1
ConsEng
edition_2
HPC UK
edition_3
HPC Germany
edition_4
StoragePisa
(SP)
edition_5
edition_6
SuomiMetal
644D8D40-2AA7-11DA-8D40A1DBA4B5DCB0
646EF7F0-2AA7-11DA-B7F098837A9D68F0
Password for the Keystore is the password entered during the installation.
After entering all required information the edition can be registered. For the test scenario the
required editions and companies are listed above.
6.1.1.5
Service Registration
The services that each member can provide have to be registered to make the member available for
that role at the VO creation or member replacement. To register a service the tab “Service
Registration” from the member edition has to be selected. A dropdown selection shows all possible
services. For every member several services can be registered by selecting the service, entering the
endpoint and clicking “Register”. If the endpoint reference is left empty a default, local endpoint will
be applied.
To complete the demo scenario at least the following services should be registered:
- ConsEng: Client
- HPC UK, HPC Germany: NECPartner
- StoragePisa (SP): StorageProviderPartner
- SuomiMetal: Client, StorageProviderPartner
Page 39
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 12: Service Registration
Creation of a VO (Initiator Edition)
Please make sure you have installed and registered all necessary editions that should be included in
the new VO according to the instructions.
6.1.1.6
VO Identifying (VO Name)
The “initiator-edition” is responsible for creating a new Virtual Organization. It can be accessed by
browsing to http://localhost:8080/edition_1/“ in the demo installation (see installation manual).
Please note that the initiator also consists of a member edition. To create a new VO the initiator
edition has to be selected (on the top right corner of the screen). A name for the new VO (for
example “VO_WP34”) and an objective (“Demo”) has to be entered.
Figure 13: VO Identification
Proceed by clicking “next” on the bottom right.
6.1.1.7
Select Choreography (Load WSCDL)
After entering a VO name and clicking “next” the initiator edition proceeds to the tab “Load WSCDL”.
A business process choreography for the new VO is selected during this step. For more information
about the WSCDL and its impact refer to the CDL2BPEL FAQ and the WS3 WSCDL definition.
Page 40
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The currently available WSCDL documents are listed. By clicking on the magnifier symbol the CDL
document will be shown. To select a choreography click on the red check. The name of the selected
WSCDL document will be entered into the field “Collaboration Definition”. For our Demo we select
“CE testbed”.
Figure 14: Select choreography
Proceed by clicking “next” on the bottom right.
6.1.1.8
Choose Access Policies Templates (Policies)
After selection of a WSCDL for the new VO, access policies can be assigned to specified roles. On
9
the right side all currently available PLC documents are displayed. To assign a policy to a role the
role has to be selected from the dropdown-menu on the left. In our demo we want to assign the PLC
document “access-client” to the role client. We click on the magnifier next to the PLC “access-client”
on the right and select the role “Client” from the dropdown. The policy document is then displayed in
a XML-editor on the bottom.
To load access policies a PDP service must be available and configured in the properties-file
(edition_X\application\editionConfiguration.properties). If no such service is available PLC selection
should be skipped.
9
Roles are defined in the business proccess choreography (WSCDL).
Page 41
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 15: Choose VO policies
By clicking on “save” the PLC “access-client” is assigned to the role “client”. Assignments that have
been made are displayed at the bottom right, by clicking on the red cross they can be deleted and
assigned new.
In our demo scenario we do the following assignments:
access-client
for role Client
access-necpartner
for role NECPartner
access-storageproviderpartner
for role Storage
Proceed by clicking “next” on the bottom right.
6.1.1.9
Select ECA Policies Templates (ECAs)
Event Condition Action policies define special event-triggered actions, like a member replacement
after a SLA violation. They are selected by clicking on the magnifier symbol next to them. Every VO
can have several ECA policies. We select the ECA document “Demo” for our demo-VO. By clicking
“Save” the ECA “Demo” is added to the list at the bottom right.
Page 42
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
To load ECA policies a policy-server service must be available and configured in the properties-file
(edition_X\application\editionConfiguration.properties). If no such service is available ECA selection
should be skipped.
Figure 16: Select ECA policies
Proceed by clicking “next” on the bottom right.
6.1.1.10 Select SLAs
Service Level Agreements describe the quality of service (QoS) agreed upon between two
companies, for example response time or scope. The available SLAs are displayed on the right side
of the SLA. They can be selected similar to the ECA selection described above.
To load SLAs a SLA-Manager and SLA-Repository service must be available and configured in the
properties-file (edition_X\application\editionConfiguration.properties). If no such service is available
SLA selection should be skipped.
Page 43
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 17: Select SLAs
For the demo we select the “SLA-Filter” and adjust the ReputationThreshold (on the very bottom of
the XML-editor) from 0.5 to 0.1 and click on “Save”.
Proceed by clicking “Next”.
6.1.1.11 Create GVOA Context (General VO context)
Some general VO info can be entered before finally generating the Virtual Organization. For the
Demo we enter start date and end date like shown in the figure.
Page 44
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 18: Create GVOA context
By clicking “Generate” the VO Toolkit automatically proceeds to the “Role Overview” screen. The
formation phase is finished with that step.
6.1.1.12 Role Assignment (Role Overview)
All possible roles according to the WSCDL are shown and require a port mapping and member
selection. Port mapping will create local proxies for the member BPEL services to make them
independent from the BPEL implementation. We select ports 1111-1113 for demo purposes (see
figure).
Figure 19: Port mapping
To choose members for the available roles we click on the magnifier symbol for each role. After the
search has been started the potential Members are displayed.
6.1.1.13 Potential Member Overview
For the selected role (displayed under “Role Name:”) all members that have registered the service
for that role are displayed. One or more members can be selected to play that role in the new VO. A
Page 45
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
potential member can be selected by clicking the “Add >>” button next to it. The member will move
from the “Members found in UDDI” to “Potential Member”. After all desired members have been
moved to “Potential Members” invitations can be sent by clicking “Send Inventions”.
Figure 20: Potential Member Overview
For the demo scenario we send invitations for the following members and roles:
- Client: ConsEng, SuomiMetal
- NECPartner: HPC UK, HPC Germany
- Storage: StoragePisa (SP), SuomiMetal
6.1.1.14 Send Invitations
By clicking on “Send Invitations” for potential members a screen with a invitation message opens
(see figure below). The PLC documents belonging to that role are attached to the mail together with
the WSCDL definition for the Virtual Organization. Subject and text of the message can be changed.
After checking the message it can be send by clicking on the “Send” button on the bottom. After
sending invitations the Toolkit will return to the “Role overview screen”. Repeat the procedure for
every role until status of every role is “Members chosen”.
Page 46
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 21: Send invitation message
The initiator now has to wait for the members to accept or reject the sent invitations.
6.1.1.15 Process Invitations (Mailbox)
After invitations for a new VO have been sent to potential members they appear in the Mailbox of
these members. The mailbox can be accessed by clicking on the “Mailbox” tab in a member edition.
The messages in the inbox are displayed with the unread messages written in bold letters. By
clicking on one magnifier for the message it appears in the text field at the bottom (see figure).
Page 47
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 22: Invitations in mailbox
The message contains the text entered in the invitation screen and the SLA and WSCDL documents
as attachments (displayed on the left). The XML documents can be viewed by clicking the magnifier
to their right. To accept or reject the sent invitation we click on the buttons displayed in the message
body. In our demo-VO all invitations are accepted expect from member “SuomiMetal” who rejects
both invitations.
After all members have accepted (or rejected) their invitations the initiator can continue the forming
of the new VO.
6.1.1.16 Assign Members (Role overview)
With all members accepted their invitations the refreshed “Role overview” screen shows that there
are members found for each of the three roles.
Figure 23: Role overview after accepted invitations
Page 48
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The possible members can not be assigned by clicking “Assign Member” for each role.
6.1.1.17 Assign Member to Role
The member assignment is opened from the “Role overview”. For every role a list of all the sent
invitations is shown. A rejected invitation is marked by a red cross while for an accepted invitation a
“Member Priority” has to be entered.
Figure 24: Assign Members to Role
We select the following priorities for members of our VO_WP34:
- ConsEng 1
- HPC UK 1
- HPC Germany 2
- StoragePisa 1
By checking “Bypass SLA Negotiation” the corresponding service wont be called, we don‟t check
that box and call the SLA Negotiator.
A member is assigned by clicking “Assign member to role” and confirming on the popup. After a
successful assignment the “Member State” changes to “Assigned to role” and a green check is
displayed. The “Back” button at the bottom returns the user to the “Role overview” from where the
procedure can be repeated for every role.
The priority defines a order in which the members are chosen for the selected role. For the role
NECPartner we have two accepted invitations and the assignment of the member is defined by the
selected priorities. The less-preferred member goes into “Negotiating” state.
Page 49
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 25: Different priorities for members
After all members have been assigned the members can be connected by clicking “Connect
Members” in the “Role overview” screen.
Figure 26: All members have been assigned
6.1.1.18 Connect Notifiers
Notifier connections make sure that a message send by the initiator reaches every member of a VO.
A structure has to be selected to guarantee a message flow that includes every role. We connect
(see following figures):
- Initiator to Client
- Client to NecPartner
- NECpartner to StorageProviderPartner
Page 50
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 27: Connect Notifiers
Initiator
Client
NECPartner
StorageP.
Figure 28: Message flow in VO
After setting up the notifier connection the Virtual Organization can enter the operation-phase by
clicking on “Operate VO”.
VO Operation
After the Virtual Organization has been successfully created (see chapter “Creation of a VO”) steps
belonging to the operation phase can be performed.
6.1.1.19 Policy Deployment
Each member edition has to deploy a policy now. In the initiator edition under the tab “Operate” a list
of all roles and assigned members is displayed. The “Policy Deploy Status” indicates that the initiator
is waiting for the members to deploy their policies.
Page 51
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 29: Initiator waiting for policy deployment
In each assigned member‟s mailbox there is a notification that the VO has been started and a
request to deploy the policy. The suggested policy is attached to the message and can be viewed in
the message body. The policy selected during VO creation is deployed at any case without asking
for permission when “operate VO” is clicked, the policies generated by the PGC (policy generator) is
the one that is attached to the message. There are two deployment options:


“manual” : Manual deployment means that the VO Toolkit software doesn‟t bother about the deployment of
the policy. The suggested policy in the message is being discarded and the VO Toolkit from that moment on
assumes that the policy has been deployed through some other way.
“automatic” : By selecting automatic deployment the suggested and attached policy is being deployed to the
policy server.
To deploy access policies a policy service must be available and configured in the properties-file
(edition_X\application\editionConfiguration.properties). If no such service is available “manual”
deployment should be selected.
Page 52
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 30: Message in inbox for policy deployment
After all members deployed their policies the “Operate” tab in the initiator looks like this:
Figure 31: Initiator after all members deployed the policies
6.1.1.20 Show GVOA
The GVOA belonging to the VO can be viewed by clicking on “Show GVOA”. The GVOA Manager
(CCLRC) web service is called to do this and needs to be installed for full functionality.
Page 53
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
VO Evolution
During the operation of a VO for several reasons the change of the members may become required.
The reason for that can be for example a violation of a SLA.
6.1.1.21 Select Member
In the initiator edition in the “Operate” tab a list of all connected members can be seen. More
detailed information can be accessed by clicking on the magnifier symbol next to the member name.
For the VO_WP34 Demo we want to replace member “HPC UK”. We select that member.
Figure 32: Connected members in the initiator
6.1.1.22 Replace Member
For a selected member (clicking on magnifier symbol) the offered services are displayed in the
“Detailed Member Information” page. The function for member replacement can be accessed on that
page at the bottom. If “Force Member Replacement” checkbox is activated the member that is
supposed to be replaced is not asked for confirmation.
For this walkthrough we don‟t want do force member replacement and start the member
replacement process by clicking on the “Replace Member” button.
Page 54
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 33: Initiate Member Replacement for HPC UK
6.1.1.23 Confirm Replacement
If the “Force Member Replacement” checkbox has not been checked the member that is supposed
to be replaced gets a mail asking for confirmation. The inbox in the corresponding member edition
contains a “Replacement” message.
Page 55
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 34: Replacement message to confirm replacement
The Replacement message is selected by clicking on the magnifier symbol. The initiator waits for the
member to confirm the suggested replacement. By clicking on “Accept” the member sends an
approval to the initiator.
6.1.1.24 New Member after Replacement
After one member has successfully been replaced a new member for that role is required. If a
member for that role has already been invited with a lower priority than the member that has just
been replaced the VO Toolkit software automatically wants to hand that role over to the member
with lower priority.
In our example we choose two members for the role
Figure 35: Different priorities for members during VO creation
With having replaced HPC UK successfully now, HPC Germany gets an email with the request to
register its policy. The “Operate” tab in the initiator-edition shows the role NECPartner as waiting for
policy deployment
Page 56
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 36: Waiting for new deployment after replacement
The new member now has to deploy its policy like described in the section “Policy Deployment” in
the chapter “VO Operation”.
After the new member has deployed his policy the member replacement is completed and “Operate”
screen looks like this:
Figure 37: After successful replacement
Page 57
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Developer's Guide
6.1.1.25 Design of the VO Toolkit
The Virtual Organization Management Toolkit (VOM Toolkit) has the purpose of integrating the VO
Management subsystem components, providing tools to facilitate the creation, operation and
dissolution of VOs. As a result of the implementation proposal of the VOM Subsystem, the VOM
Toolkit contains the VO Management Services, the VOM Integration Platform and the VOM Console.
In fact, the VOM Toolkit is a Web-Based application, built over a SOA that combines several WS to
accomplish the task of managing one or more VOs.
6.1.1.26 Packages and Use Cases
The VOM Toolkit can be installed in three different editions: Host, Initiator and Member. They are
hierarchically built: the Host includes the Initiator and the Member; the Initiator includes the Member;
and the Member can only be a member. However, it‟s not possible to be more than one edition at
same time. The following figure is a representation of the VOM Toolkit installation structure.
Page 58
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 38: Package Overview of the VOM Toolkit Implementation
The figure below is composed of three Use Case Diagrams, depicting the three mentioned Editions:
Host, Initiator and Member. The Host edition is rather simple: it shows the active VOs and the list of
Services that are available for participating in a VO (this includes the ones that are already in a VO
plus the ones that are waiting for an invitation). The Member edition has the following functionalities:
register itself in a Host, configure some properties and send/receive e-mails (messages). The
messages constitute the main communication method between the VO Manager and the members.
The Initiator edition stands for the VO Manager role. The use cases are illustrated below:
Page 59
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 39: Use Case Diagrams for VOM Toolkit Editions
1.
2.
3.
4.
5.
6.
7.
Register: Register the initiator with the host
Show VOs:
show the VOs that are managed by this Initiator;
Send/Receive E-Mail: the main communication way of the Initiator;
Create VO:
create a new VO in the Host;
Add Member: the Initiator is responsible for inviting and adding the new members to the VO;
Remove Member: the Initiator can also remove a member from the VO;
Operate VO:
the VO is in operation when all the members are ready to play their roles in
order to accomplish the objective;
8. Terminate VO: when the objective is reached, the VO is terminated;
The implementation of the toolkit is WS-based, in the sense that the WS correspond to the basic
functionalities of the VO Management Subsystem, and also includes a MVC model for the user
interactions. The diagram in below summarizes the main packages of the toolkit.
Model-view-controller (MVC) is a software design pattern that separates an application‟s data model,
user interface, and control logic into three distinct components so that modifications to one
component can be made with minimal impact to the others.
Page 60
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 40: Package Overview
The toolkit also includes a MySQL database. Each edition has its own database that is managed by
the model classes, i.e. they implement the SQL statements to access/modify the tables, by
extending the superclass com.sap.toolkit.console.model.- GeneralModel. The following figure
provides an overview of the package. Note that in the diagram, the operations of the model classes
for the member, initiator and host were suppressed to fit in the page.
Page 61
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 41: Database Classes
The most important features of the VOM Toolkit are the bundled Web Services. Each edition has its
own WS that, in fact, defines the edition. The most relevant WS, to the present work, are:




MembershipManager: located in the Host edition, it is responsible for all the membership tasks, i.e. add,
remove, edit members, perform queries about membership status;
LifecycleManager: located in the Host edition, is responsible for the life-cycle management of the VO.
Includes tasks as create, operate and terminate VO;
VOManagementInitiator: located in the Initiator edition, it is responsible for managing the interactions
between the initiator and the VO members;
BasicCommunication: present in all editions, it is responsible for the communication management, i.e.
receiving/sending messages, showing attachments.
6.1.1.27 Database Design
Page 62
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
For each different edition (host, initiator and member) the Databases look differently. The Tables are
connected via foreign keys, in the figures illustrated by arrows. The three figures below show the
Tables in the SQL Database and their relations for each edition.
member
vo_id
role_id
role_name
port
bk
id
sla_id
member_business_card
<pk>
<pk>
id
businesskey
businesscard
<pk>
participant
id
<pk>
uddi_name
business_key
url
edition
pub_key
virtualorganisation
id
name
objective
initiator_id
state_id
<pk>
<mul>
owner
id
name
url
<pk>
Figure 42: Databases of the host edition
Page 63
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
plc
Id
vo_id
name
date
role_id
<pk>
<mul>
role
<mul>
id
name
vo_id
state_id
monitor_state_id
port
<pk>
incoming_messages
<mul>
Id
vo_id
role_id
type_id
sender_id
sender_name
sender_url
recipient_id
subject
text
is_new
deleted
date
<pk>
incoming_attachments
<mul>
Id
message_id
name
type
text
<pk>
<mul>
eca
virtualorganisation
Id
vo_id
name
data
<pk>
<mul>
outgoing_messages
id
name
objective
state_id
gvoa
wscdl_name
wscdl_data
gvoa_status
<pk>
Id
vo_id
role_id
type_id
sender_id
sender_name
sender_url
recipient_id
subject
text
is_new
deleted
date
sla
id
vo_id
name
date
<pk>
<mul>
general_vo_context
selected_member
configuration
owner_id
owner_businesskey
owner_name
owner_url
host_url
<pk>
member
notifications
member_id
state
role_id
<pk>
member_id
<pk>
member_state_id
prio
force_replace
policy_deploy_state
sla_id
Id
<pk>
vo_id
<mul>
GVOAstartDate
GVOAendDate
GVOAProduct
GVOATerritory
GVOADays
GVOADuration
GVOAArbitration_country
GVOAGoverning_law
GVOARenewal_period
GVOATermination_notice
GVOAExpulsion_notice
GVOADelay
GVOALiability_limit
GVOALiability_duration
GVOAConfidential_duration
GVOAExpertSelectionLimit
GVOAMajorityVoting
<pk>
Id
businesskey
uddi_name
url
<pk>
<pk>
outgoing_attachments
<mul>
Id
message_id
name
type
text
plc_templates
<pk>
<mul>
remote_plc_templates
id
name
date
<pk>
id
name
date
<pk>
wscdl_templates
id
name
date
<pk>
sla_templates
remote_sla_templates
id
name
date
<pk>
eca_templates
Id
name
data
<pk>
Figure 43: Databases of the initiator edition
Page 64
id
name
date
<pk>
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
incoming_messages
id
vo_id
role
isDeployed
Policy
PolicyId
Id
vo_id
role_id
type_id
sender_id
sender_name
sender_url
recipient_id
subject
text
is_new
deleted
date
virtualorganisation
vo_policy
id
name
objective
initiator_id
<pk>
<mul>
<pk>
<pk>
incoming_attachments
<mul>
Id
message_id
name
type
text
<pk>
<mul>
outgoing_messages
Id
vo_id
role_id
type_id
sender_id
sender_name
sender_url
recipient_id
subject
text
is_new
deleted
date
sla
id
vo_id
name
date
<pk>
<mul>
role
id
name
vo_id
state_id
monitor_state_id
port
<pk>
outgoing_attachments
<mul>
Id
message_id
name
type
text
<pk>
<mul>
configuration
policy
Id
vo_id
role
isDeployed
incomingPolicy
incomingPolicyId
outgoingPolicy
outgoingPolicyId
<pk>
<mul>
<pk>
<mul>
kb_patterns
INTERNAL_PATTERN_ID <pk>
PATTERN_ID
<mul>
FIRST_TAG_NAME
<mul>
CDL_PART
PURE_BPEL
kb_other_parts
INTERNAL_OTHER_ID
<pk>
INTERNAL_PATTERN_ID <mul>
BP_PART
VIEW_PART
PDD_PART
ROLE
owner_id
owner_businesskey
owner_name
owner_url
host_url
<pk>
administration
config_name
config_status
Figure 44: Databases of the member edition
6.1.1.28 The VO Management Web Services
6.1.1.28.1 LifecycleManager - LCM
The LifecycleManagerService (LCM) is a WS located in the Host Edition of the VOM Toolkit. The
LCM service manages the entire VO life-cycle. Here follows a description of the main methods (note
that all the database interactions refer to the Host database):
Query Operations:
 getPossibleMemberCandidates(): search in the UDDI registry for possible members to the business
process role;
 getLastNotification(): retrieve the last notification message from the notification system;
 getNofifiersChain(): retrieve the notifiers‟ chain. This chain is created during the formation phase.
Based on this chain, each notification system knows where to send notifications;
 queryStatus(): return the status of the current VO, i.e. in which phase theVO is;
Administrative Operations:

modifyVO Collaboration(): allow the modification of the collaboration for the current VO;
Page 65
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007

modifyVO Agreement(): allow the modification of the agreement for the current VO;
VO Life-Cycle Operations:



o
o
o
o
o
o
o
o
o
o




o
o

o
o
createVO(): with a VO-ID (the unique identifier) and the collaboration definition, create a new VO in
the database;
formVO(): after the VO is created, the formation phase is initialized with the definition of the GVOA;
operateVO(): the set up of the VO is complete and the VO is ready to enter operation phase. The
following actions must be taken during this method
execution:
update the VO state-ID in the database;
add the selected roles with the selected members to the database;
load the notifiers chain for the given members;
request the BPELObserverService of each member to start;
request the NotifierService of each member to subscribe;
create the port mappings for the members to connect during the business
process execution (invoke PortMappingService);
request the members to deploy their policies (invoke BasicCommunicationMemberService);
send a message to all the members signalizing that the VO has started (invoke
BasicCommunicationMemberService);
pauseVO(): request the BPManagementMemberService of each member to pause the business
process;
resumeVO(): request the BPManagementMemberService of each member to resume the business
process;
terminateVO(): request the termination of the business process execution on each member by
invoking the BPManagementMemberService;
dissolution(): the VO enters in the dissolution phase:
update the VO state-ID in the database;
request the PortMappingService of each member to remove the port mappings for the given VO;
removeVO(): after termination, the VO is removed:
remove the notifiers chain for the given VO;
remove the VO from the database;
6.1.1.29
Membership Manager – MM
The MembershipManagerService (MM) is located in the Host Edition of the toolkit. The MM is
responsible for the management of the VO membership. The MM provides a wide range of
functionalities including query and administrative operations, e.g. query members and roles, add,
remove and replace member. Here follows a description of the most relevant methods:
Query Operations:






getRoles(): return the list of business process roles to which the given member is assigned (in the
given VO);
getMember(): returns the correspondent BusinessEntity associated to the given business key and VO
identity;
getMembers(): return the list of members for a given VO;
getCurrentMember(): return the current member assigned to the given business process role in the
given VO;
isInVO(): verifies if a given member is in the given VO;
findMembers(): locate members in a VO according to a specified set of parameters defined in the
query;
VO Membership Operations:
Page 66
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007




addMember(): add a particular member with a specific set of roles to the VO;
removeMember(): remove the member from the VO;
assignRole(): assign a business process role to a member in a VO. Call the VOManagementInitiator
service to assign the member;
replaceMember(): replace the given member in the given VO. Call the VOManagementInitiator
service to assign the member;
6.1.1.30 VOManagementInitiator – VOMI
The VOManagementInitiator Web Service (VOMI) is located in the Initiator Edition of the VOM
Toolkit. As the Initiator Edition stands for the VO Manager role, this WS is definitely important in the
VO management.
With the MM, the VOMI is responsible for managing VOs. In the following description, relevant
methods are depicted. Note that the changes in database tables now refer to the Initiator database.






o
o
o
o
o

o
o
o
o
o
o

o
o
o


getWscdl(): retrieve the WSCDL data for a given VO;
getRoleMappings(): return the list of role mappings for a given VO, i.e. the role name and the
associated member‟s UDDI name;
policiesAreDeployed(): set the deployment status of a member. This method is invoked after the
member has deployed his policies;
getPoliciesInterop(): return the list of policies associated with a member playing a given role in a VO;
doneGVOAInterop(): signalize that the GVOA was successfully generated;
assignRole(): assign a member to a given role in the VO:
check the selected member table, and update the state-ID of the selected members (back to
negotiation);
update the selected member table with the new assigned member data;
update the status-ID of the new member in the member table;
update the correspondent role state-ID in the role table;
signalize to the member that he has been assigned to a business process role in the VO;
replaceMember(): replace a given member in a VO.
check if there‟s an available member for the replacement;
if the force flag is enabled call the forceReplacement() method;
if not, check for message;
if no message, then send a message to the member and wait;
if there‟s a message, read and check the response;
if the members has accepted, call the reallyReplace() method and replace the member;
reallyReplace(): replace the member (detailed description in the next section):
stop the services, i.e. stop the BPELObservers and undeploy the policies;
update the database tables;
call the assignRole() method for the new member;
forceReplacement(): send a message to the member that is going to be replaced notifying him about
it and replace him by calling the reallyReplace() method (note that there‟s no choice for the member);
handleReplacementResponseFromMember(): handle the replacement response from the member,
according to the replacement work-flow;
Use Case “Member Replacement”
The main contribution of the VOM Toolkit is its ability to handle highly dynamic, process driven VOs.
As mentioned, such VOs admit the membership replacement scenario, where one member playing a
Page 67
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
specific business process role is replaced by another member. During this operation, the VO might
be running a business process and in that case, the replacement has a great level of complexity.
The complexity derives from the fact that the state of the VO must be saved and then resumed, after
the replacement. This involves a sequence of steps that includes pausing the VO (the running
business process), proceed with the actual replacement, update the remaining members with data
about the new member, and finally resume the VO business process with the new members‟
configuration.
The membership replacement task mainly involves the following Web Services:
MembershipManager, LifecycleManager, VOManagementInitiator and the BasicCommunication.
The replacement action is conducted according to an algorithm that can be represented by an
activity diagram. The figure depicts this algorithm in an abstract view, contemplating the decisions
taken by the Initiator.
Figure 45: Member Replace Operation
Before describing the steps, it is important to make some considerations:



The algorithm process only one replacement per time;
The member that is going to be replaced has the option of accept of not the replacement;
The Initiator is able to set a configuration flag for each member that consists in a boolean value for a forced
replacement. When enabled, the member is replaced directly;
According to the algorithm, there are four walk-through possibilities for the replacement, with two
possible final states.
1
(a) Force flag: set to TRUE;
(b) Send Replacement MSG: send a message to the member that is going to be replaced, notifying
about the replacement;
Page 68
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
(c) Really Replace: perform the member replacement action;
2.
(a) Force flag: set to FALSE;
(b) Response: the member has not yet answered the message;
(c) Send a Replacement Request and wait for the response;
(d) New MSG: the member has answered. Run the algorithm again;
3.
(a) Force flag: set to FALSE;
(b) Response: the member has answered the message;
(c) Complained: the member did not complain. Send a notification message and replace the
member;
4.
(a) Force flag: set to FALSE;
(b) Response: the member has answered the message;
(c) Complained: the member complained. The Initiator will not replace the member. The VO stops
and enters in an unknown state;
Finally, the steps of a membership replacement, from a database perspective (Initiator), can be
summarized as follows:








check if there is a member available for the replacement, i.e. if exists at least one member with state-id (3) for
that role in that VO, in the selected member table;
check the force flag for the member that is going to be replaced;
check if the member has answered the Replacement Request. The messages are stored in the database;
update the Role table. The assignment of a new member is possible again;
update the state of the replaced member: state-id (6);
the Initiator requests the member to undeploy his policies: update the deployment status of the replaced
member;
assign the new member: set his state to (5) in the selected member table;
update the selected member table for that VO, now that the new member is officially in the VO;
Below there are sever UML diagrams for different scenarios for member replacement:
Page 69
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 46: Replace with Force Flag enabled
Figure 47: Replacement with Force Flag Disabled and No Response from Member
Page 70
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 48: Replacement with Force Flag Disabled and Member Complain
Page 71
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 49: Replacement with Force Flag Disabled and Member Accept
CDL2BPEL
CDL2BPEL is a tool for generating executable BPEL (Business Process Execution Language)
processes for individual, collaborating participants in a VO, where the ways in which the participants
interact are encoded using the WS-CDL (Choreography Definition Language). As a VO is formed in
response to a business objective that can not be addressed by just one partner alone, a swift
reaction to the emerging business need, fast partner consortium formation, and quick, automatic
adaptation of IT infrastructures are of essence. Thus, an automated solution deriving executable
business processes from a Choreography was desired, following a top-down approach which is
aligned with the VO formation and partner selection processes. Business application logic is hereby
encapsulated in service implementation. Therefore, a business process at one role can be seen as
the ordering structure around local web service invocations, also called orchestration. Orchestration
captures the local, role specific view on business processes, which orders the calls on available
services and guarantee a defined execution order. In contrast, the global view encompasses the
collaborative business process, which orders the interactions between the involved roles. The
overall goal of this tool is thus a conceptual mapping that shows how the transformation of a
choreography in a standard language to a set of orchestrations in another standard language can
take place. The mapping forms the basis for a prototypical implementation, showing the validity of
the developed concept. For a given choreography, the orchestrations generated by the prototype
then need to be deployed in execution engines and are thereafter executed whenever the need for
the collaboration arises. Deployment and execution are the requirements from the VO environment
and put a high burden on the semantic correctness and completeness of the orchestrations.
Page 72
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Membership
Management
Service
Member
Locator
Service
BP Repository
Details on
Execution
engine
Member
information
CDL2BPEL
Service
BPEL
WSDLs
PDD
BPEL, WSDLs,PDD
BPManagement
Service
CDL Patterns/
Replacement
CDL
Knowledge
Base Service
Executable Process (BPEL)
View (WSDL)
Partners‘ views (WSDL)
Deployment descriptor (PDD)
SQL queries/
responses
MySQL relational
Database system
Third-Party software
Active BPEL
Execution engine
Figure 50: CDL and BPEL relevant Services
The choreography offers a means by which the rules of participation within a collaboration can be
clearly defined and agreed to jointly. Each entity may then implement its portion of the choreography
as determined by the common or global view. A Choreography defines the sequence and conditions
under which multiple cooperating independent agents exchange messages in order to perform a
task to achieve a goal state.
In TrustCoM, a view based collaborative business process model is used, which follows the
established theoretical models, as well as the specifications of the WfMC. The needs for
confidentiality of entire processes or workflows of the respective partners and the integration of
multiple private workflows into a global view are identified as critical for successful operation of
virtual enterprises, extended enterprises and virtual organizations. On one hand, an organization
may not be willing to share detailed information about a complete business process, since the
information in it represents an asset to its owner. On the other hand, enough information has to be
provided to the coalition (or the VO in our context) in order to get a coherent and stable public
workflow. Their approach introduces a coalition model with three tiers: private processes, public
views of these processes, and a (global) public process. These three tiers correspond to the notions
of private business processes, the interfaces of these processes, and choreographies, respectively.
Applying the collaborative business process model to the VO environment, the collaborating
members are informed about the VO objective through the shared choreography. They can thus
infer the behavior that is expected from them during the VO operation phase which corresponds to
their public process. A partner is only required to expose the public process to the VO which serves
as the interface for the confidential private process. Following the Service Oriented Architecture
(SOA) paradigm, implemented modular pieces of application logic are assumed to be available as
services. Therefore, the private business process can be seen as a stateful wrapper around the
services, guaranteeing the defined order of calls to the services. Thus, it is also called orchestration,
providing a local, role specific view on a private/public process pair, in contrast to the choreography
which captures the global view on a collaboration among different roles. The problem thus is to find
a way to generate a set of executable, private processes and the
Page 73
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
public view on them from a choreography description of the overall collaborative process. Two subproblems addressed, which are of major importance for the achievement of the goal, are the
information gap between the levels of detail and the differences in the languages chosen for the
description.
In order to achieve an automated derivation of executable processes, the elements of a WSCDL
document are translated in a depth-first search through the XML tree. For each role in the
choreography, a process is derived. Each element in the source document is added only to the
processes of the roles for which it is relevant. If a part of the choreography cannot be translated, i.e.
it falls into one of the categories of the information gap, it is sent as a request to a Knowledge Base
(KB). In the KB, the private, local, or confidential details of a private process are placed. If there are
elements of a choreography which still cannot be translated, a list of these elements (and potentially
other errors) is returned. The figure below shows a graphical representation of the outcomes of the
BPEL derivation. Clearly, the orchestrations are far more detailed, and the local substitutes for the
high-level, private activities from the choreography are in place (the local service calls, which
depend on the environment). Also, the executable processes are concerned with initialization of the
processes, which always means incoming messages in BPEL, as well as gluing activities. The latter
include variable and message initialization, and apparent assignment statements. These runtime
requirements are not to hard to meet, and the details of how this can be done are omitted here. The
derivation of BPEL and WSDL from WS-CDL is achieved in a 5-step algorithm, which is outlined in a
later section. In short, the algorithm is an extended compiler, in that it reads a source document and
generates an object tree for it, performs validation and transformation on the tree, and serializes the
resulting object trees to a set of documents in the target languages. We call it ‟extended‟, because it
includes a dynamic part – the Knowledge Base - in addition to the static program code.
Figure 51: CDL2BPEL sequence
Page 74
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 52: Business Process execution
6.1.1.31 Web Services
BP Repository
The BP Repository offers design time storage and retrieval capabilities for collaboration definition
(CD) templates. CDs are retrieved by specifying a list of criteria outlining the business objective, the
VO is intended to meet. The BP repository is able to suggest CDs meeting the criteria by matching
the CDs meta-data description.
CDL++2BPEL Service
The CD contains the global, high-level description about how the VO will meet the business
objective. This description has to be realised at runtime by executable BP components, the
executable private processes and corresponding views.
The CDL++2BPEL Service addresses this gap by taking VO Members meeting the specified roles
as input from VO Management. The service then automatically derives at least process views for
each, or just one specific role. The service is also capable of deriving private processes as well, if no
private processes fitting the views are available in the VO member‟s domain, assigned to the
specific role. It is recommended that one instance of this service is offered in a VO, possibly by VO
Management falling in the category of Choreography services, but it is also possible to run one
service instance per VO member domain.
The Service performs its duty in three parsing stages:
1. Immediate mapping of activities and message exchanges to views and optionally BP activities
and exchanges.
Page 75
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
2. Identification of well known collaboration artefacts, e.g. Purchase Order, and generation of their
view activities (and corresponding private BP activities optionally), in general for more than one
role.
3. Handling of remaining activities and exchanges, in worst case by raising alerts and using
exception handlers from the GVOA.
Views and optionally private processes may be deployed automatically in the role specific VO
member domains, using the BPM service.
CD Knowledge Base
This service is closely tied to the CDL++2BPEL service and the same domain affiliation as well as
deployed service numbers are required. In the second parsing stage of the CDL++2BPEL service
(see the CDL++2BPEL component description above), well known CD artefacts are identified and
the CD Knowledge Repository Service is queried for view and optionally private process artefacts
which are then inserted in the generated role specific subjective views. Such a CD artefact usually
corresponds to a confidential part of the private process which may not be exposed to other entities,
not even to other VO members.
BPM Service
The BPM service provides deployment and runtime control for the BP engine, one in each VO
member domain. Views and private processes are deployed, suspended, stopped or tested by using
offered service interfaces. The BPM also subscribes to notification topics addressing the BP runtime,
e.g. addressing the control of BP instances.
If TSC Tasks need further or altered configurations, TSC Extension Roles can be assigned to a
deployed view/private process.
BP Engine
The BP engine finally enacts the deployed private process and offer the process view as the
externally visible behaviour to the outside. Usually, each VO member runs an engine in his/her own
domain. The BP engine, following the service oriented architecture paradigm, is lightweight,
implementing a process model with limited capabilities to work with workflow relevant data. The
engine rather orders service invocations from within private process tasks providing implemented
business logic.
A deployed process may be instantiated upon deployment, only once or in several instances flexibly
meeting the requirements imposed by the business objective. A process instance is started by
invoking the dedicated activity/method in the corresponding process view with initial start data. Note
that a process instance completion is not equivalent to the termination of the VO. In fact, many
instances of the CBP may be executed during the operation phase of a VO, but all instances should
be completed or terminated before the dissolution phase is started.
6.1.1.32 The Knowledge Base
The KB contains CDL patterns and their respective replacements in terms of BPEL activities as well
as optional WSDL elements and even deployment artifacts for all roles of interest. When queried,
the KB tries to find a pattern matching the WS-CDL part from the request. If such a pattern is found,
the respective BPEL and WSDL parts and the deployment information are retrieved. Since the
patterns can be generic in that they contain placeholders for variable or partner names, the KB then
Page 76
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
replaces these placeholders with the instances from the query. Subsequently, the results are
returned to the CDL2BPEL algorithm, which weaves them into the goal documents.
Figure 53: The Analysis-Storage choreography part
Page 77
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 54: The resulting BPEL processes, derived from the Analysis-Storage choreography part
above. (a) The process for the AnalysisPartner role. (b) The process for the StorageProvider role.
Using this technique encourages the reuse of both choreographies and patterns and introduces a
dynamic element into the derivation. The KB can be deployed and accessed solely locally at each
member of a VO, satisfying the confidentiality requirement that comes with optimized process parts
and internal implementation. The KB also enables a late bindinglike way to connect local services to
a process. In that sense, the Knowledge Base can be seen as the material filling up the information
gap.
6.1.1.33 The CDL2BPEL Algorithm
The results of this algorithm are a set of documents, namely for each cdl:roleType a private,
executable BPEL process and the public view on it as a WSDL definition.
Page 78
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The main step of the algorithm is the actual translation. Here, the translation rules are applied to
each element. Although some translations depend on the context, most rules only focus on the
current element and its attributes and children. These translations draw their validity from the fact
that the location of an activity defines when and if the activity is executed, both, in WS-CDL and in
WSBPEL: A structuring element contains activities, and these activities can themselves be
structuring or basic. An activity then most of the time describes what is done when this element is
reached, e.g., in a bpel:assign, the values copied to a variable do not depend on the question if the
assign operation is the child of a bpel:sequence or a bpel:flow. Therefore, many elements can be
translated by one rule, independent of their context. The important point is, that each activity‟s
translation relies on the validity of the translations of its parents. Thus, the challenge for the
algorithm is to place each output element at the right location in the output process. This is achieved
by the interplay of paying attention to the current parents in the choreography, and the depth-first
search manner of the translation.
6.1.1.34 Steps in the CDL2BPEL Algorithm
Figure 55: Steps in the CDL2BPEL algorithm
1. Read the choreography, create and initialize the corresponding objects
2. Correct variable and channel usage, the correct number of child elements with appropriate
attributes, etc.
3. a) Translate from CDL to BPEL and WSDL. Traverse the XML tree from the root choreography,
adding each activity to the BPEL process of involved roles (Structuring activities: all roles). Also
Page 79
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
extract WSDL files from interactions and tokens / token locators (Generate operations, port
types, message schemas, bpel:partner link types, bpel:properties).
b) If the current element cannot be translated directly, try a KnowledgeBase lookup
c) For activities or sets of activities which still cannot be transformed, make an error note
(Report all errors back after traversing the whole tree)
4. Validate and optimize the generated BPEL processes from the holistic perspective. E.g. remove
empty structuring activities (e.g. a sequence with one child)
5. Generate the BPEL and WSDL code from the objects OR return failure note
6.1.1.35 Integration With Other TrustCoM Services
There are several other components which are needed in the CDL2BPEL algorithm or thereafter.
The Figure shows them and the communication between the CDL2BPEL service and the other
components. In the shown VO, there are two members and a host. The host is the central
administrative instance in a VO, knowing about the members and state of the VO, and more. The
members are the participants in WS-CDL. Note, that there is no restriction on the number of
cdl:participants that a member may represent. Another way to think about it is that there are distinct
software packages, one for members, one for hosts, and one for initiators (which is a special kind of
member, but the distinction is not relevant here). Each package brings along several components
and, thus, features the software owner may use. The example in the figure shows only the relevant
components for the host and two members.
Figure 56: Setup of the relevant components in a VO, with communication from CDL2BPEL services
to other components.
In order to get deployable, executable processes, the shown services are used by CDL2BPEL. First,
the choreography is retrieved from the host‟s BP Repository. The BP Repositories are basically
databases with business process content and a TrustCoM-specific identity model for data
Page 80
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
addressing. When the choreography is present, the member‟s CDL2BPEL algorithm derives the
private processes for the roles the member plays by querying the local CDL-KB for private process
parts whenever necessary.
For the purpose of deployment, the deployment descriptor document and the WSDLs of the
partners‟ processes need to contain endpoint references, under which the processes of the partners
may be called. This is not necessary for all partners, only for the ones with which a process actually
will communicate. Here, the assumption is made that all partners use a known BPEL execution
engine. That means, that the way the engine makes deployed processes available is known, i.e., the
role name, namespace of the choreography, and the engine‟s type and endpoint reference are
sufficient information to construct the service name and the endpoint reference of the deployed
process. Say, the process for role A will communicate with the process of role B, then the latter two
pieces of information about the member playing role B are required for the deployment A‟s process.
Before writing out the generated documents, CDL2BPEL requests from Membership Management at
the host which member plays which role in the current VO and gets back their identities. With the
member identity, more details on the member are retrieved, again from the Membership
Management service. One of the details is the Main Endpoint Reference, the endpoint information
under which the Member Locator Service of the respective member can be called. From the Member
Locator Service, the type and endpoint reference of the BPEL engine in use can be requested.
Besides, role name and namespace are present in the choreography.
From the chain of queries and the information in the choreography, the endpoint reference of the
partners‟ processes can be constructed, even before they are actually deployed. Note, that this, too,
is a major benefit of constructing BPEL and WSDL from a choreography: Take the example where
the processes of roles A and B need to call each other. For A‟s deployment, the WSDL with the
binding information of B is required and needs to be transmitted from B to A. This WSDL is usually
generated by the execution engine after B‟s process is deployed. But the deployment of B‟s process
in turn needs the WSDL of A‟s deployed process. The presented approach thus makes the
transmission of the WSDLs unnecessary and solves the chicken-and-egg problem of the mutual
dependency elegantly.
After all information is retrieved, the output documents are written and stored at the local BP
Repository, which hands back an ID for each document. These IDs are sent to the VO management
suite, which called CDL2BPEL. With this information, the local BP Management service is invoked,
which retrieves the documents from the BP Repository, packages them in the engine-specific way
and deploys them to the execution engine. If this procedure is finished at all partners, the operation
phase of the VO is entered, and an instance of the collaborative process can be triggered each time
the need for it arises. The sequence of these calls explained above is visualized in the Figure below.
Page 81
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 57: Sequence of calls in the transition from the formation to the operation phase of a VO
The public views for the negotiation during the VO‟s formation phase are derived by the initiator‟s
CDL2BPEL service and only require its local BP Repository. Membership Management, Member
Locator Service, and the CDL Knowledge Base are not needed, because neither endpoint
information nor local knowledge is present in the public views.
Due to the fact that the installation of the services containing private knowledge is local, the
confidentiality requirements can be easily met by simply allowing outside access only to the Member
Locator Service. The CDL Knowledge Base and the BP Repository as well as the execution engine
should be only accessible by authorized users in the respective member‟s organization.
6.1.1.36 WS-CDL
One or many choreographies form a cdl:package. Exactly one of them is marked as the “root
choreography”, and thus is the starting point for a package. Having its roots in the Pi-calculus, a
choreography in CDL describes the control flow around basic activities through structuring activities.
A choreography can have variables, exception handlers, and finalisers, which define communication
and the like at the end of a choreography. Due to the point of view taken by CDL, there are only few
basic activities, with the interaction as the centre piece, since the focus of choreographies is to
describe the how and when of communication. All basic activities, conditional expressions, and
variables can be defined for only a subset (sometimes of size one) of the available roles.
In CDL, the concept used for referring to one of the parties is always the role type (or, in short, the
role). A party that wants to participate in a choreography can be required to play multiple roles by
specifying a cdl:participant subsuming these roles. Note that each role can belong to zero or one
participant. Also, a role can be defined to show more than one behaviour. Each behaviour can be
refined in a WSDL document, and, if it is not, has no deeper meaning for the details of the
Page 82
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
choreography. However, both, a WSDL and a CDL document, describe the behavioural interface of
entities, although a choreography includes far more information. Thus, our impression is that the
redundancy in providing an additional WSDL per role behaviour alongside with a choreography
yields no significant advantage. Note, that CDL has a closed-world assumption, meaning that
interactions are always bilateral between two roles specified in the choreography.
Example
<roleType name="AnalysisPartner">
<behavior name="Analyzer"/>
</roleType>
<roleType name="StoragePartner">
<behavior name="StorageProvider"/>
</roleType>
In the above code snippet from a WS-CDL package in Collaborative Engineering, two role types are
defined: the AnalysisPartner and the StoragePartner, each showing a single behaviour with no
assigned WSDL interface.
WS-CDL Activity Elements
Starting with the structuring ones, the list of activities is shown below.





sequence - Sequential order of activities.
parallel - Parallel execution of activities.
workUnit - As the most unusual structuring activity, the workUnit specifies conditions under
which an enclosed activity is executed or repeated. Its guard condition is similar to an if-condition
in standard programming languages, and can contain various XPath expressions or CDL
supplied functions. The guard can be evaluated either immediately or deferred (e.g., when a
variable becomes available) by setting the block attribute to true or false, respectively.
Furthermore, the repeat condition states if a workUnit is considered for execution again after
completion.
choice - Exclusive branching: at most one of the enclosed activities (which may itself be a
structuring activity) is to be performed. A cdl:choice is intended to contain workUnits as children,
with a guard condition. If there are non-workUnit children in a choice, the branching condition is
said to be non-observable or not relevant at the choreography.
interaction - Used for communication between two roles. In data exchanges the submitted
variables are specified. Timeout conditions can be defined directly in an interaction, as well as
assignments with reference to the data exchanges. If an interaction‟s “align” attribute is true,
transactionality for an interaction is enabled, in the sense that the interaction only shows effect if
the involved roles have the mutual understanding that the interaction completed successfully.
Example
<interaction name="getRawDataReq" operation="getRawDataOp"
channelVariable="chVarGet">
<participate relationshipType="AnalysisStorageRel"
fromRoleTypeRef="AnalysisPartner"
Page 83
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
toRoleTypeRef="StoragePartner"/>
<exchange name="exRawDataAddr" informationType="uriType"
action="request">
<send variable="cdl:getVariable('varRawDataAddr_Ana','','')"/>
<receive variable="cdl:getVariable('varRawDataAddr_Sto','','')"/>
</exchange>
</interaction>
This code example shows the information exchange between the AnalysisPartner (AP) and
StoragePartner (SP) from the first CDL code example. The Web service operation „getRawDataReq‟
at SP is called by AP. The information exchanged is the raw data‟s address, available in the variable
„varRawDataAddr_Ana‟ at the AP and stored in the variable „varRawDataAddr_Sto‟ at SP after the
transmission.




noAction - Explicit “no operation” for a specified role. The respective party must remain idle.
silentAction - Partner-internal action, whose details are of no interest to the choreography as a
whole. The comment, by default in natural language, specifies what a partner is assumed to do at
that instant, e.g., “analysis of aircraft antenna”.
assign - Variable value modification. Can be used to trigger exceptions.
perform - Execution of another choreography. With CDL‟s binding mechanism, variable values
from the outer choreography can be carried over to the inner choreography.
The link between WS-CDL and the Pi-calculus is strong, and also becomes apparent in the
availability of channels in CDL. There, channel variables are of a channel type, which allows the
definition of identity and reference tokens, restrictions on the channel usage, and the receiving role
at the end of a channel.
6.1.1.37 WS-CDL Example
This is the CDL “CE testbed” that is used for our demos and is fully functional for our test-cases,
meaning VO creation, evolution and dissolution and supports the CDL2BPEL starting business
processes.
<?xml version="1.0" encoding="UTF-8" ?>
<package
name="untitledModel"
author="unspecified
author"
version="1.0"
targetNamespace="http://unspecified.namespace"
xmlns:tns="http://unspecified.namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:cdl2bpelns="http://cdl2bpel.cecka.sap.com" xmlns:choreons="http://unspecified.namespace"
xmlns="http://www.w3.org/2005/10/cdl" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
C:\Documents
and
Settings\D048368\Desktop\CE
attributeFormDefault="qualified"
targetNamespace="http://unspecified.namespace">
#<xsd:schema
elementFormDefault="qualified"
tested.xml
<xsd:complexType name="stringAndIDType">
<xsd:sequence>
<xsd:element name="content" type="xsd:string" />
<xsd:element name="IDElem" type="tns:stringID" />
</xsd:sequence>
Page 84
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
</xsd:complexType>
<xsd:complexType name="uriAndIDType">
<xsd:sequence>
<xsd:element name="content" type="xsd:anyURI" />
<xsd:element name="IDElem" type="tns:stringID" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="stringID">
<xsd:sequence>
<xsd:element name="ID" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<informationType name="stringType" type="xsd:string">
<cdl2bpelns:map schemaType="tns:stringAndIDType" query="/choreons:content" />
</informationType>
<informationType name="stringIDType" type="tns:stringID" />
<informationType name="uriType" type="xsd:anyURI">
<cdl2bpelns:map schemaType="tns:uriAndIDType" query="/choreons:content" />
</informationType>
<informationType name="JobRequest" type="xsd:string">
<cdl2bpelns:map schemaType="tns:stringAndIDType" query="/choreons:content" />
</informationType>
<informationType name="JobCompleteConfirmation" type="xsd:string">
<cdl2bpelns:map schemaType="tns:stringAndIDType" query="/choreons:content" />
</informationType>
<informationType name="NewJobCompleteConfirmation" type="xsd:string">
<cdl2bpelns:map schemaType="tns:stringAndIDType" query="/choreons:content" />
</informationType>
<informationType name="PutDataRequest" type="xsd:string">
<cdl2bpelns:map schemaType="tns:stringAndIDType" query="/choreons:content" />
</informationType>
<informationType name="GetDataRequest" type="xsd:string">
<cdl2bpelns:map schemaType="tns:stringAndIDType" query="/choreons:content" />
</informationType>
<informationType name="GetDataResponse" type="xsd:string">
<cdl2bpelns:map schemaType="tns:stringAndIDType" query="/choreons:content" />
</informationType>
<informationType name="PutDataResponse" type="xsd:string">
<cdl2bpelns:map schemaType="tns:stringAndIDType" query="/choreons:content" />
</informationType>
Page 85
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
<token name="stringIDToken" informationType="stringIDType" />
<tokenLocator
tokenName="stringIDToken"
query="descendant::choreons:ID" />
<tokenLocator
tokenName="stringIDToken"
query="descendant::choreons:ID" />
<tokenLocator
tokenName="stringIDToken"
query="descendant::choreons:ID" />
informationType="stringType"
informationType="JobCompleteConfirmation"
informationType="NewJobCompleteConfirmation"
<tokenLocator
tokenName="stringIDToken"
query="descendant::choreons:ID" />
<tokenLocator
tokenName="stringIDToken"
query="descendant::choreons:ID" />
<tokenLocator
tokenName="stringIDToken"
query="descendant::choreons:ID" />
<tokenLocator
tokenName="stringIDToken"
query="descendant::choreons:ID" />
informationType="GetDataRequest"
informationType="JobRequest"
informationType="PutDataRequest"
informationType="GetDataResponse"
<tokenLocator tokenName="stringIDToken" informationType="uriType" query="descendant::choreons:ID"
/>
<roleType name="Client">
<behavior name="ClientInterface" />
</roleType>
<roleType name="NECPartner">
<behavior name="NEC" />
</roleType>
<roleType name="StorageProviderPartner">
<behavior name="StorageProvider" />
</roleType>
<relationshipType name="ClientNECRelationship">
<roleType typeRef="Client" />
<roleType typeRef="NECPartner" />
</relationshipType>
<relationshipType name="NECStorageRelationship">
<roleType typeRef="StorageProviderPartner" />
<roleType typeRef="NECPartner" />
</relationshipType>
<participantType name="ClientParticipant">
<roleType typeRef="Client" />
</participantType>
<participantType name="NEC">
<roleType typeRef="NECPartner" />
</participantType>
<participantType name="StorageProvider">
<roleType typeRef="StorageProviderPartner" />
</participantType>
<channelType name="PutDataChannel">
Page 86
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
<roleType typeRef="StorageProviderPartner" />
<reference>
<token name="ChannelToken" />
</reference>
</channelType>
<channelType name="GetDataChannel">
<roleType typeRef="StorageProviderPartner" />
<reference>
<token name="ChannelToken" />
</reference>
</channelType>
<channelType name="ResultsDataCompleteChannel">
<roleType typeRef="Client" />
<reference>
<token name="ChannelToken" />
</reference>
</channelType>
<channelType name="NewResultsDataCompleteChannel">
<roleType typeRef="NECPartner" />
<reference>
<token name="ChannelToken" />
</reference>
</channelType>
<channelType name="RequestJobChannel">
<roleType typeRef="NECPartner" />
<reference>
<token name="ChannelToken" />
</reference>
</channelType>
<channelType name="ReceiveDataChannel">
<roleType typeRef="NECPartner" />
<reference>
<token name="ChannelToken" />
</reference>
</channelType>
<choreography name="Scenario3Choreography" root="true">
<relationship type="ClientNECRelationship" />
<relationship type="NECStorageRelationship" />
<variableDefinitions>
<variable name="initVOChorVar" informationType="uriType" roleTypes="Client" />
<variable name="jobInfoV" informationType="JobRequest" />
Page 87
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
<variable name="getDataRequestV" informationType="GetDataRequest" />
<variable name="getDataResponseV" informationType="GetDataResponse" />
<variable name="putDataRequestV" informationType="PutDataRequest" />
<variable name="jobCompleteAckV" informationType="JobCompleteConfirmation" />
<variable name="chPutData" channelType="PutDataChannel" />
<variable name="chGetData" channelType="GetDataChannel" />
<variable name="chReqJob" channelType="RequestJobChannel" />
<variable name="chReceiveData" channelType="ReceiveDataChannel" />
<variable name="chResultsDataComplete" channelType="ResultsDataCompleteChannel" />
<variable name="NewchResultsDataComplete" channelType="NewResultsDataCompleteChannel" />
</variableDefinitions>
<sequence>
<assign roleType="Client">
<copy name="initial-assign">
<source variable="cdl:getVariable('initVOChorVar','','')" />
<target variable="cdl:getVariable('jobInfoV','','')" />
</copy>
</assign>
<interaction name="requestJob" channelVariable="chPutData" operation="requestJobOp">
<participate
relationshipType="ClientNECRelationship"
toRoleTypeRef="NECPartner" />
fromRoleTypeRef="Client"
<exchange name="dummyExchange" action="request" informationType="JobRequest">
<send variable="cdl:getVariable('jobInfoV','','')" />
<receive variable="cdl:getVariable('jobInfoV','','')" />
</exchange>
</interaction>
<interaction name="requestData" channelVariable="chReqJob" operation="requestDataOp">
<participate
relationshipType="NECStorageRelationship"
toRoleTypeRef="StorageProviderPartner" />
fromRoleTypeRef="NECPartner"
<exchange name="dummyExchange" action="request" informationType="GetDataRequest">
<send variable="cdl:getVariable('getDataRequestV','','')" />
<receive variable="cdl:getVariable('getDataRequestV','','')" />
</exchange>
</interaction>
<silentAction roleType="StorageProviderPartner" />
<interaction name="getData" channelVariable="chGetData" operation="getDataOp">
<participate relationshipType="NECStorageRelationship"
toRoleTypeRef="NECPartner" />
fromRoleTypeRef="StorageProviderPartner"
<exchange name="dummyExchange" action="request" informationType="GetDataResponse">
<send variable="cdl:getVariable('getDataResponseV','','')" />
<receive variable="cdl:getVariable('getDataResponseV','','')" />
</exchange>
Page 88
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
</interaction>
<silentAction roleType="NECPartner" />
<interaction name="putData" channelVariable="chPutData" operation="PutDataRequestOp">
<participate
relationshipType="NECStorageRelationship"
toRoleTypeRef="StorageProviderPartner" />
fromRoleTypeRef="NECPartner"
<exchange name="dummyExchange" action="request" informationType="PutDataRequest">
<send variable="cdl:getVariable('putDataRequestV','','')" />
<receive variable="cdl:getVariable('putDataRequestV','','')" />
</exchange>
</interaction>
<silentAction roleType="StorageProviderPartner" />
<interaction
name="NewjobCompleteAck"
operation="jobCompleteAckOp">
channelVariable="NewchResultsDataComplete"
<participate relationshipType="NECStorageRelationship"
toRoleTypeRef="NECPartner" />
fromRoleTypeRef="StorageProviderPartner"
<exchange name="dummyExchange" action="request" informationType="NewJobCompleteConfirmation">
<send variable="cdl:getVariable('NewjobCompleteAckV','','')" />
<receive variable="cdl:getVariable('NewjobCompleteAckV','','')" />
</exchange>
</interaction>
<interaction
name="sendJobComplete"
operation="sendJobCompleteOP">
channelVariable="chResultsDataComplete"
<participate
relationshipType="ClientNECRelationship"
toRoleTypeRef="Client" />
fromRoleTypeRef="NECPartner"
<exchange name="dummyExchange" action="request" informationType="JobCompleteConfirmation">
<send variable="cdl:getVariable('jobCompleteAckV','','')" />
<receive variable="cdl:getVariable('jobCompleteAckV','','')" />
</exchange>
</interaction>
</sequence>
</choreography>
</package>
6.1.1.38 Usage of CDL2BPEL in the Toolkit
During the creation of a VO a CDL (choreography) has to be selected that describes the
collaborative business interactions. Like explained in the sections above this CDL can – with the
help of the knowledge base – transferred into a BPEL process.
To do this there is a button “Start/Resume BP” in the “Operate” view in the Initiator. By clicking on
this button the business processes are started without further confirmation.
Page 89
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 58: "Operate" view in the Initiator. BP can be started from here.
After a BP has been started it can be monitored using the (in our case) ActiveBPEL engine HTML
front-end. The BPs are started on the BP engine on the Member-side machines. After a VO is
terminated or a Member is being replaced the dependant BPs are terminated and undeployed.
Page 90
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 59: ActiveBPEL active process deployed by CDL2BPEL
6.1.1.39 CDL2BPEL FAQ
Q: Where do I access CDL2BPEL binaries and/or source?
A: The main sources of Cdl2Bpel are in the packages com.sap.toolkit.console.cdl2bpel.*. Below are
these packages seperatly listed:
• com.sap.toolkit.console.cdl2bpel: Contains the main Cdl2Bpel logic and gets called from the
Cdl2Bpel Web Service.
• com.sap.toolkit.console.cdl2bpel.ws.bpm: Contains the Web Service classes for the Business
Process Management (BPManagemnet) Service which is provides the functionality for deploying the
created BPEL, PDD and WSDL files to the BPEL Engine (ActiveBpel) as a BPR file.
• com.sap.toolkit.console.cdl2bpel.ws.cdl2bpel: Contains the Web Service classes for the Cdl2Bpel
Service which provides the functionality of the Cdl2Bpel as a Web Service.
• com.sap.toolkit.console.cdl2bpel.ws.cdlkb: Contain all classes for the Cdl Knowledge-Base these
are the Web Service and the logic (implementation) classes.
Q: How do I install CDL2BPEL? Do I require additional software or
machines?
Page 91
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
A: The installation of the Cdl2Bpel and therefore all additional software is completely integrated into
the VOM Toolkit installation procedure. If the recent VOM Toolkit version is installed the Cdl2Bpel is
installed with it.
Note: A later installation of Cdl2Bpel is not recommended, because the Cdl2Bpel is embedded into
VOM Toolkit and hence the Cdl2Bpel version and VOM Toolkit version have to be fully compatible to
each other.
Q: What is the relationship between CDL2BPEL and the VO Toolkit? Can
CDL2BPEL be called from within the Toolkit?
A: Cdl2Bpel is embedded into the VO Toolkit and gets called during the VO Formation Phase of the
Toolkit. In this phase, Cdl2Bpel is converting the WSCDL document – which the members retrieve
from the initiator – into respective BPEL code (more precisely: converting into a BPR file, the
deployment format of the ActiveBpel Engine).
After converting the BPEL code gets deployed (over the BPManagement Service) to the BPEL
Engine.
Q: What are the necessary inputs for CDL2BPEL?
A: The main input is the WSCDL file which represents the collaborative business process. For
converting this WSCDL document, Cdl2Bpel needs additional information in the CDL
Knowledgebase (also see questions: What is the Knowledge Base (KB)? And What needs to be
specified in the KB before I can use CDL2BPEL?).
Q: Are there any conformance rules that my CDL document needs to
follow?
A: Currently there are three main rules which have to be followed:
• The following variable must be present in any CDL document in order to enable CDL2BPEL to
work correctly. Its content is transmitted with the initial call to the first BPEL process and, through its
role assignment, indicates which of the specified roleTypes is the first one to be invoked. With this
initial message, the execution of the BPEL processes is triggered.
<!−− Var iabl e that i s used f o r out s ide c a l l s to the chroreography
IMPORTANT: The r o l e f o r which i t i s s p e c i f i e d d e f i n e s the pr o c e s s
which i s s t a r t e d f i r s t ! HAS to be s p e c i f i e d at the roo t choreography ,
f o r CDL2BPEL to work −−>
<v a r i a b l e name=" initVOChorVar " informat ionType=" uriType " rol eType s=" Client "/>
Page 92
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
• Cdl2Bpel works only when there is exactly one root choreography specified, by setting the attribute
‟root‟ of the ‟choreography‟ tag to true. This is part of the current CDL specification.
<choreography name=" Scenario3Choreography " root=" true ">
• The CDL specification which is used in Cdl2Bpel is http://www.w3.org/2005/10/cdl, the version
currently recommended by the W3C (http://www.w3.org/TR/ws-cdl-10/). Hence, the input CDL
document has to be conform with this version.
If you observe problems whose cause seems mysterious to you, a comparison with the example
CDL documents and Knowledge Base contents may help.
Additional Update to the conformance rules:
1) Declare roleTypes and relationships in the order that they are used, namely the first interaction
among them. For example: if roleType A call roleType B and roleType B call roleType C , then the
sequence A,B and C in the RoleTypes definition should be guaranteed. The order of these
roletTypes in the XML document relates to the insertion of these elements into the database, when it
is parsed in toolkit.
Per roletype will one process be generated. And it is also
used as a bpel:role in a
bpel:partnerLinkType located in WSDL. Only the roles of the cdl:participant type that are relevant to
a certain partner need to be included via bpel:partnerLinks
in the respective bpel:partner element.
2) Ensure that all interactions have a name and that the operations are specified. Otherwise, there is
no way to map these to BPEL. The Invoke and Receive activities will be generated for each
cdl:exchange at the respective roles on the basis of the Interaction element in the CDL. In detail, If
the cdl:action is ”‟request”‟ , then add a bpel:invoke at the cdl:fromRole and a bpel:receive at the
cdl:toRole, if the cdl:action is ”‟respond”‟ switch the to- and from-roles. Also add the variables
needed.
3) Ensure that the informationTypes are well formed because they are translated to
xsd:complexType in the WSDL. That is, informationType cannot just be specified as a name, they
also need to have a type. Similarly, the operations should be specified with a name . Recall that
interactions are required in order to generate the WSDLs of partners and the partner links in the
BPEL.
.
4) In order to support the BPEL‟s properties and property aliases with correlation sets within the
BPEL Process. The Token and Token locators used for channel identity should be clearly defined.
Using an un-initialized correlation set causes a fault in BPEL, therefore a simple identifier may serve
as the content of the single one correlation set that is generated for each process. Token Locator is
translated into Property Alias
in the WSDL. And Token is translated into Correlation Set and Property. Correlation set references
at usage locations of the corresponding variables, the property is added to the WSDL.
Page 93
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Q: What options do I have when executing CDL2BPEL?
A: Currently there are no options which can be chosen by the initiator or member
through the GUI. For installation or development purposes, the Cdl2Bpel properties can be changed
in the cdl2bpel.properties file at $CATALINA.HOME/bin/cdl2bpel.properties. However, it is not
recommended to change the default values.
Q: What is the Knowledge Base (KB)?
A: The unobservable or private parts of a choreography, e.g., a silent action, are activities that are
only mentioned in the choreography. That is, for these parts the choreography states only what
needs to be done, but not how. A way to insert the actual implementations of these activities into the
private BPEL processes is required. This part is played by the Knowledge Base (KB).
The KB is a service as well, containing CDL patterns and their respective private counterparts. The
latter encompass BPEL activities as well as optional WSDL elements and deployment artifacts
(PDDs for ActiveBPEL) for all roles of interest. When queried with a CDL pattern, the KB tries to find
the matching private counterparts. If a matching pattern is found, the respective BPEL and WSDL
parts and the deployment information are retrieved and returned as the query results. Since the
patterns can be generic in that they contain placeholders for variable or partner names, the KB then
replaces these placeholders with the instances from the query, given a consistent mapping can be
found. Subsequently, the results are returned to the CDL2BPEL algorithm, which weaves them into
the goal documents. Using this mechanism, CDL‟s silent action and the like can be translated to
BPEL.
Q: What needs to be specified in the KB before I can use CDL2BPEL?
A: Since the KB is used for replacing certain CDL activities with their BPEL implementation, for all
the activities where this needs to be done, a KB entry needs to be specified before calling
CDL2BPEL. A KB entry consists of a CDL part (e.g., the silent action as it appears in the
choreography of interest) and its replacements, which are: BPEL activities, and, if application
services need to be called, PDD and WSDL information regarding these application services. The
BPEL activities will be weaved into the ouput BPEL process exactly as they are stated in the KB
entry, and at the point of the process which corresponds to the location of the silent action has been
in the choreography.
At this stage of the work, the KB content has to be stored via SQL, in the tables KB PATTERNS and
KB OTHER PARTS of the shema edition X vom member whereas ‟X‟ is a placeholder for the edition
number.
Q: KB entries, that sounds quite complicated. What does it look like?
A: Here is an example. At first: The CDL part of the entry, which shows a silent action. Whenever the
silent action with exactly this content shows up in a CDL document, it is replaced with the BPEL,
WSDL, and PDD parts of this entry, as shown
below.
Page 94
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
<CdlPart>
The longest
part of the
<d e s c r i p t i o n type=" documentation ">getRawDataFromDB
KB entry is
varRawDataAddr_Sto
typically its
varRawData_Sto
BPEL part,
i.e. the BPEL
</ d e s c r i p t i o n>
activities
</ s i l e n tAc t i o n>
which
are
bound
into
</CdlPart>
the
output
processes
as a replacement of the CDL part. Below, there are first variables, which are used in this BPEL
snippet, followed by a sequence of activities. In the sequence, the request‟s message variable is
initialized, the content is copied into it, and a private application service is invoked. Afterwards, the
content of the response is copied to one of the variables of the choreography. Note, that
namespaces need to be written out, abbreviation of namespaces is not possible yet.
<s i l e n tAc t i o n roleType=" StoragePartner ">
Page 95
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
In the WSDL part of the KB entry, the external WSDL document of the private application service is
referenced, which is invoked in the BPEL snippet above. This WSDL has to be accessible to
CDL2BPEL in the temporary output folder of CDL2BPEL, namely $CATALINA.HOME/temp/output/.
L
a
s
t
<ViewPart roleType=" StoragePartner " viewId=" WsdlIdSubPrivSto "
namespace=" http: // trustcom . cecka . sap . com / cdl2bpel / PrivStorage ">
</ViewPart>
but not least: The PDD part of the entry, which contains the EPR of the local service. (Note, that this
EPR is redundantly stated in the WSDL document above.
<PddPart roleType=" StoragePartner ">
Q
:
<wsa:EndpointRe fer ence xmlns : s=" http: // trustcom . cecka . sap . com / cdl2bpel /
H
o
w
<wsa:Addres s>http: // localhost:8080 / axis / services / PrivateStorageServicePort
d
o
</wsa:ServiceName>
PrivStorage " xmlns:wsa=" http: // schemas . xmlsoap . org /ws /2003/03/ addressing ">
</wsa:Addres s>
<wsa:ServiceName PortName=" PrivateStorageServicePort ">s:PrivateStorageService
</wsa:EndpointRe fe renc e>
</PddPart>
Q
k
Q: How do I know that CDL has been successful?
A: There are three points, where failure may be observed:
(a) The Tomcat Console on which the Cdl2Bpel Service is running should contain the output
CDL2BPEL: Conversion to BPEL successful!.
(b) The BpelAdmin GUI of the ActiveBpel Engine should contain the newly derived and deployed
BPEL processes under the menu item ‟Deployed Processes‟.
(c) Invoke a test run of the processes. This is the ultimate test, and before a successful test no
assumptions should be made about the correctness of the generated processes. Here, the question
of interoperability between processes and services is assessed, before there are only syntactic
checks for correctness. A test run can be triggered in the GUI, where test data has to be entered for
the initial message. The progress of the processes can be followed in the BpelAdmin console of
ActiveBPEL, menu item ‟Active Processes‟.
Q: Where can I obtain errors concerning an execution of CDL2BPEL?
A: Generally, all output of Cdl2Bpel is printed out on the Console of the Tomcat server on which Axis
and thus the Cdl2Bpel Service is running. The output contains information whether the Service was
successful or not.
Note: More detailed error messages are the Cdl2Bpel debug messages, which can be enabled by
setting the value of DisableDebugMessages to false in cdl2bpel.properties.
Page 96
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Q: Are the generated BPEL processes immediately executable? If not, what
are some of the reasons they may fail?
A: If the conversion and deployment of the new processes in the BPEL engine was successful, the
BPEL processes can be executed immediately. (There is a delay of up to 20 seconds after
deployment until the processes become available in the engine.) Reasons for failure can be:
• A not fully compatible CDL description.
• Missing or not perfectly fitting KB entries, which cause the processes to be
but faulty in their execution semantics.
syntactically correct,
• No connectivity to the other BPEL engines or application services.
Typically, the conversion of CDL2BPEL is quite stable, in the sense that
if it worked once, it is very likely to work always.
Q: Can the generated BPELs invoke services and processes on different machines without
additional configuration?
A: It depends. For all roles defined the WSCDL, the actual Endpoint References (EPRs) are
requested from the VO Toolkit databases. If the EPR in the VO Toolkit changes over time, the
deployed BPEL processes will not adapt automatically – they would have to be derived again from
the CDL.
For the application services at the members‟ sites, the case is similar: Their EPRs are defined in
both the KB entries and the there referenced WSDLs‟ binding information. If an application service
is moved (or, rather, the address to which a BPEL process sends a message for this service
changes), the KB and the WSDL document have to be updated accordingly, before calling
CDL2BPEL again. Note: Process instances cannot survive such an EPR change in the current
implementation.
Typical Tasks
In the following typical tasks and their general solutions are described.
6.1.1.40 Problem: A Web Service Interface Should be Changed.
Solution: A web service interface can be changed by changing the interface description in the
corresponding java file and by generating all stubs and supplementary files anew. This can be done
by changing the wsdlMacro.xml script (editionInitialisation/webservices) so that all commented
targets in the wsdl-base macro are commented in again. During the next execution of the script all
necessary files are updated. To execute the script either execute the web service build script (in the
corresponding subdirectory of the directory webservices) or install the complete toolkit (which also
updates all other web services). After update the wsdlMacro.xml can be reverted.
6.1.1.41 Problem: A new Web Service Should be Added.
Solution: To add a new web service add a new subpackage for the web service in the package
webservices. Create a new interface in this package with the desired methods. Now create a new
ant script for this web service in the directory webservices (respectively in one of its subdirectories).
Page 97
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
This can be done by copying an exisiting script and updating required information (especially check
the correct value for the "ws.xml" property: the correct subdirectory/edition must be entered here).
After this, change the wsdlMacro.xml file so that all stubs, etc. are generated (see 2.1.). Now
execute the newly created ant script for the new web service to create all necessary supplementary
files. After that, implement the desired behaviour in the generated implementation class and revert
back the wsdlMacro.xml file.
6.1.1.42 Problem: A new Global Configuration Item Should be accessible during Runtime.
Solution: Global configuration data is supplied by the class GlobalConfiguration (package util). This
class reads in the required data from the properties file editionConfiguration.properties in the
application directory of a toolkit installation. This file is written during the installation by the method
PropertyFileWriter.write() (package install.util). So, adding new global data can be achieved by
writing it to the properties file via this method. For this purpose, the class PropertyFileWriter can
access all information of the class Filemanager (package install.util) during the installation.
Therefore, this might be the right place for computing the necessary configuration data or for reading
it in from several installation specific configuration files.
6.1.1.43 Problem: A new Library must be copied during Installation.
Solution: The method EditionManager.installOtherLibraries() (package install.edition) is mainly
responsible for copying libraries. Usually the libraries are stored in the lib directory and copied during
installation to the toolkit's target directory.
6.1.1.44 Problem: A new 3rd Party Tool should be installed during Installation
Solution: For all 3rd party tools there is a subclass of the class ComponentManager (package
install.interfaces) in the package install.thirdParty. To add a new tool such a class must be created
and executed by the method Installer.installThirdPartyComponents() (package install). To get to
know the right source location of the new tool the class FileManager (package install.util) can be
used to retrieve the required data from configuration files (see also 2.4.).
6.1.1.45 Problem: A Model Class should load/store new Data in the Database
(respectively using the database connection pooling properly). Solution: Various methods in the
different model classes (package model) deal with retrieving/writing data from/to the database. In
general, it cannot be determined when a model instance will not be used anymore so holding a
database connection as an instance variable should be avoided. To enable using the model classes
without having to close them explicitely and, nevertheless, to avoid resource leaks because of
unused open connections a database connection pooling was introduced.
The use of a database connection pooling implicates some peculiarities for using the database. A
method accessing the database must explicitely create a connection at its beginning and it must
release the connection at its end. The database connection pooling ensures that there will not be a
high database load due to too many connection creations and the explicit release ensures that all
derived objects (statements, result sets) are also closed properly. Problem: New debug messages
should be generated.
Solution: If new debug messages should be generated by a certain toolkit part the various static
methods of the class Trace (package util) can be used. Every method requires a key identifying the
source of the message. Finally, debug messages are printed on the tomcat console if they are
activated in the method Controller.initializeTrace().
6.1.1.46 Problem: A new Web Site should be integrated
Solution: Apart from writing the web site (as a subclass of the class Module in package
view.modules) and setting links from other sites (with the "nextModule" HTTP parameter) a new site
must be registered in the class CoreController either in the method createHostModule(),
createInitiatorModule(), or in createMemberModule().
Page 98
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.47 Problem: UDDI and/or Database Tables should be prefilled
Solution: Several prefill activities are performed by script files, described in the section 1.2.5
“Initialization process description”. Those script files can be changed or new ones can be
created
and
called
for example
in
the
InitialiseDatabase()
method
under
com.sap.toolkit.console.install.
6.1.1.48 Problem: The Keywords of my UDDI Business Entities should be changed
Solution: The keywords are set in method initialKeywordsProperties() in the class
com.sap.toolkit.console.install.util.PropertyFilewriter and can be changed or enhanced there. If an
edition has already been installed the keywords can be changed without having to re-install by
editing the file edition_X\application\keywords.properties
6.1.1.49 Problem: New Business Entities and Business Cards should be added
Solution: Business Cards and Keys are stored in the Host SQL Database in the table
member_business_card.
They
are
initialized
with
the
file
vom_toolkit/conf/mysql/host_businesscard.ddl. Either that file can be changed or the new business
cards can be directly changed in the SQL databse.
Example
For setting up and operating the demonstrator scenario please refer to the section “User Guide”.
Notification subsystem
Installation Guide
6.1.1.50 Package Contents
Name
Type
Description
Notification Proxy
Service
Designed to be installed at each company net once. All
notifications are send through this proxy to hide internal
recipients‟ details. Only the proxy‟s EPR is known to the
outside world.
Notification Broker
Service
The notification broker maintains a list of all producers
(proxies) and all consumers (also proxies). Each
subscription/registration request is forwarded to the broker
which copies the request to all known producers/all known
subscribers to the new producer for creating new
subscriptions.
Resource
Manager
Service
Simple interface to list/destroy WSRF Resources created
by notification subsystem. Very useful for debugging or in
test environments.
Consumer Base
Service
Service
Dummy notification consumer, useful for testing and
development
Notification
Webtester
Website
Web pages giving access to the service instances and
their current status. Some create/change methods are
also accessible. Allows management of WSRF resource
created by the notification subsystem if Resource
Manager is installed.
Notification Tester
Application
Small application which allows testing of most notification
Page 99
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Name
Type
Description
functionalities as registering as producer, subscribing as
consumer, sending notifications, direct or brokered
subscriptions, subscription of external applications or web
services, etc.
Constraint: Topic namespace is could not be changed.
6.1.1.51 Requirements
Required software:
-
.Net 2.0
WSE 3.0
WSRF.NET 2.0 including Xindice DB or MSSQL DB)
IIS
Required Services (not necessarily on local machine):
- Service Instance Registry to store the endpoint reference of the notification broker.
6.1.1.52 Installation
Start installer. Select you desired components. You need at least one host with a notification proxy
and a host with a notification broker. All components can be installed on the same host.
User’s Guide
There are two different ways; users can interact with the notification subsystem, either using the
notification tester application or the web front-end (/TrustCoM/Notification/Webtester/Default.htm).
The application is capable doing all dynamic actions while the web front-end is more useful for initial
setup and shows more detailed information about the status of the WSRF-resources.
Basic setup
For nearly all actions the existence of a notification broker is essential.
Although most interactions could be executed via the notification tester, the s instantiation of the
broker can only be done via the webtester.
6.1.1.53 Instantiating the broker
At the “Broker” page of the web interface you can select some predefined broker locations or type in
one (The “Select” always only copies the listed entry to the second line as on the other pages).
“Instantiate” creates a new WSRF resource for a broker. In principal the broker is now ready for work
and the EPR is shown to you. Since all proxies try to reach the broker by retrieving the EPR from a
registry, you should register the broker immediately.
6.1.1.54 Registering the broker at the Registry
At the second step you can again select a registry location or type one in. Additionally you can
select the logical name to which the broker should be linked at the registry. By “register”ing the EPR
of the broker is added to the SIR (service instance registry) with the given logical name. The broker
is now fully operational.
Page 100
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Setting up a notification proxy
To be able sending and receiving notifications you additionally need a notification proxy. You can
decide how many proxies you want. In principal only one proxy is needed. Main purpose of the
notification subsystem was the possibility to hide the real producers/subscribers and instead place a
proxy at each company network border. So all notification passes this proxy and only this proxy‟s
address is known to the outside world. You can also decide to group similar services behind one
proxy or even one proxy per service.
6.1.1.55 Instantiating a proxy
Start the tester application. With this tester it is not possible to use an existing proxy; you have to
create a new one.
The first tab of the notification tester contains the setup parameters for a new notification proxy. If
you want to receive notifications you have to start the listener in the upper section. For convenience
if you want to execute several tester or other applications, you can chose the network port on which
you want to receive the notifications. Additionally you can choose an identifier for your application so
you can distinguish between different
testers‟
notifications.
The lower part of the first tab is for the
configuration. For instantiation you need to
select/type in the URL of the proxy factory
proxy. You can now click “instantiate” to
new WSRF resource for the proxy. The
the new proxy is shown at the bottom of
proxy‟s
and
the
create a
EPR
of
the tab.
If you only want to create a proxy and the
producing/consuming service is capable of
registering/subscribing you can also
create the
proxy via the web interface. Therefore go
to
the
“Proxy” page, select or specify the URL of
the proxy
and “instantiate” a new one. You can now
either
copy the shown EPR to your service or for easier
handling and omitting manual copy –
register
the EPR at the registry as you did for the
broker.
Only select or specify registry URL and
logical
name and “register” the proxy. Additionally
you have
to specify the logical name of the broker and configure the proxy. Without that, the proxy will not find
any broker and can‟t register subscribe anything.
6.1.1.56 Configure the proxy
In the current state the new proxy is in principle capable of forwarding notifications but since it
doesn‟t know anything about producers or consumers the proxy will not forward anything. Since the
notification broker manages the subscriptions, the proxy needs to know where he can find the
broker. For this you have to specify the URL of the service instance registry and the logical name
which stands for the broker. By pushing the “reconfigure” button the specified settings are stored in
the proxy resource. The “instantiate” button also configures the proxy with the given configuration.
The checkbox “retrieve topics” is only for your convenience. If enabled, the tester will retrieve topic
lists when you switch tabs to give you the currently subscribed/produced topics instead only a static
view.
Page 101
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Registering as notification producer
Switch to the “Registration” tab. You can see the
topic. If you have enable “retrieve topics” on the
configuration tab you will see all topics which are
the configured broker. They are marked as three
types:
pre(defined): topics which are used in the
scenarios and are therefore added for simpler
list
of
known at
different
usage
reg(istered): topics where at least one producing
registered for
proxy is
sub(scribed): topics for which consuming proxies
known to the broker
are
6.1.1.57 Specify topic
For subscribing the tester to a topic, you can select
a topic or
specify is below the list. As this tester isn‟t capable of the whole notification functionality, you can‟t
choose the topic namespace. All used topics are in the namespace “http://wsrf.notification.de” but
topics with other namespaces are also listed.
Pushing “register source” will register this tester as producer of the given topic at the broker. The
status field at the bottom will show it if is succeeded.
Subscribing as notification consumer
Switch to the “subscription” tab. This tab is divided into three sub tabs on the left.
- Full subscription: This is the combination of direct and brokered subscription. It included the
subscription of the application (or external EPR) to the proxy and the subscription of the proxy to all
producing proxies.
- Direct subscription: This sub tab executes only the
subscription of this application (or external EPR) to
the notification proxy. It can be used to subscribe
several EPRs to the same (prior on the
configuration tab created proxy). Note: For
receiving notification there must be at least one
EPR (this application or external) subscribed to the
given proxy.
- Brokered subscription: This sub tab enables you to
add only the subscription between the proxies
without subscribing any application or service.
Normally only the full subscription is needed,
sometime also direct subscription if you want more
than one
service/application to be subscribed manually to
the same
proxy. The brokered subscription tab is only
needed
for testing of the proxies itself or to add a missing
subscription for debugging.
Since the “full subscription” tab is the most
You can see the list of topics. As on the registration tab the same types of topics are marked:
pre(defined), reg(istered) and sub(scribed).
6.1.1.58 Specify topic
You can see the list of topics. As on the registration tab the same types of topics are marked:
pre(defined), reg(istered) and sub(scribed). As on the tab before you can either select or specify a
topic, the topic namespace is not changeable.
Page 102
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.59 Specify consumer EPR
For full and direct subscription you have different types of consumer you can subscribe:
The tester application itself: If “subscribe this application” is enabled and you have additionally
started the listener on the “configuration” tab, the tester can be subscribed and will receive
notification to the specified topic.
WSRF web services or applications: By deactivating the “subscribe this application” checkbox you
can specify an external EPR with the “specify button”. In the uprising form you have to select
“WSRF” on the left. On the right side you have to specify the URL/EPR of the component you want
to be subscribed. If any notification is
received, the notify method is invoked at the
specified
target. Push “OK”.
Generic web service: Deactivating the
“subscribe this application” you can specify
service with the “specify” button. You have
“generic web service” on the left and specify
of the web service on the right. Push “OK”.
the web
to select
the URL
With the “subscribe” Button you will
subscribe the specified application/ service
specified way to the proxy. The status bar informs you if the subscription is successful.
in
the
Sending notifications
Switch to the “Sending” tab. You can see the same
retrieved from the broker as on the previous tabs. If
have deactivated the retrieval, you will only see the
predefined topics.
listing
you
6.1.1.60 Compose message
Select or specify the topic you want and insert the
message you want to be send. “Raise event” will
notification with the given message to all subscribed
consumers.
send the
List received notifications
Switch to the “Receiving” tab. The list of received
notifications will be updated whenever a new
message arrives. Select a message to see the
message content. With each message a message
pop up. If you assume to receive lots of message
disable the popup below the message box.
Detailed view of a proxy/broker resource/overview over all
resources
For debugging purpose or to verify the successful
is useful to look at the notification resources in detail.
we have designed some web pages which show
all resource properties. If you want to view the
resource‟s details you need the EPR of the resource
box will
you can
setup it
For this
nearly
Page 103
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.61 Notification Broker
Switch to the “broker” page of the web interface. In the “Verification” section specify the EPR of the
broker you want to be shown and click “read”. The web interface will list all proxies
registered/subscribed at this broker and the corresponding topics.
6.1.1.62 Notification Proxy
Switch to the “proxy” page of the web interface. In the “Verification” section specify the EPR of the
proxy you want to be shown and click “read”. The web interface will list all at this proxy subscribed
consumers and the corresponding topics. Since with the registration as producer at a proxy only the
topic is saved and not the service EPR (the proxy doesn‟t need it for reception) the proxy does only
know for which topics a producer exist(ed) and nothing more. These topics are also listed.
6.1.1.63 Service Instance Registry
Switch to the “ServiceInstanceRegistry” page of the web interface. Specifying the URL you can
“read” the content of the registry. On this page only static logical names are retrieved from the
registry to avoid too many irrelevant entries in the listing.
Additionally you can register arbitrary URL/EPR with a logical name at the registry in the bottom
section
6.1.1.64 Manage resources
If you want to have a look at all existing resources of a type, switch to the “ResourceManager” page
of the web interface. You either have to specify the URL and instantiate a new resourcemanager or
select a registry/logical name and load the EPR of an existing resource manager. If you have
created a new one you can register it at the registry for easy access the next time without memorize
the EPR.
Select the type of resource you want to look at:
- Subscription Manager: Each subscription request is represented by one subscription manager
resources containing the proxy and the consuming application/service. Additionally all links between
the proxies (to connect each producer with each consumer are also represented by subscription
managers.
If you select “Subscription Manager” the result list contains the WSRF document ID, the EPRs of the
subscription resource/producer/consumer, the creation time and the topic.
- Notification Proxy: All in the database Existing proxies will be displayed with WSRF document ID,
proxy resource EPR, and the proxy‟s settings, the registry URL and the logical name of the used
broker.
- Notification Broker: All in the database stored brokers will be shown with WSRF document Id and
broker EPR.
- Resource Manager: The same as above. This is only useful for erasing old no more used resource
managers.
Additionally you have the possibility to erase some (separated by space) or all resources of the
given type in two different ways:
Destroy resource: This is the WSRF way. The resource is invoked with the destroy method.
Delete document: this deleted the database entry on SQL level.
Main difference especially when deleting lots of resources is the execution time. The deletion on
SQL level is much faster but it skips the eventually existing destroy functionality (create log entries,
write backup, inform client …). In the notification implementation there are no additional destroy
actions than deleting the resource that could be skipped.
Page 104
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Developer's Guide
6.1.1.65 Notification Proxy
The notification proxy is the only service you other services need to interact with during normal
operations. Only for setup they can use the ProxyFactory and for debugging and testing you can
also use some broker functionalities.
Important! You have to distinguish internal and external topics. Due to the WSRF.NET
implementation a message is forwarded to every consumer who is subscribed to a topic and doesn‟t
omit the forwarding instance. So for proxy functionalities it was necessary to map the topic whenever
a proxy receives a notification by the notify method (this method is part of WSRF.NET). Otherwise
the message will be copied endless. The proxy implementation adds a “_internal” to each message‟s
topic when receiving. So the sending proxy doesn‟t do anything to the message since it receives the
message via the forwardNotification method, but the receiving proxy does change the topic. Every
consumer has to subscribe to the external topic (in other words request messages with the external
topic) but listen to internal topics.
6.1.1.66 Interface
configure
/// <summary>
/// set up the proxy to use the url as a service instance registry from which to
retrieve the broker's epr with the given name
/// </summary>
/// <param name="ServiceInstanceRegistryURL"></param>
/// <param name="NotificationBrokerName"></param>
/// <returns>True if all goes well, false if the broker could not be
retrieved</returns>
public XmlElement configure(string ServiceInstanceRegistryURL, string
NotificationBrokerName)
registerProducer
/// <summary>
/// register a producer, only forwarding request to broker broker decides what
to do by createDirectSusbcription note, this is only relevant for external
notifications to enable managed subscriptions otherwise ANY component can
raise ANY notification
/// </summary>
/// <param name="topic"></param>
/// <returns>(true if successful)</returns>
public bool registerProducer(XmlQualifiedName topic) // note, type not relevant
createSubscription
/// <summary>
Page 105
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
/// This method provides the full subscription support, i.e. with invocation of
this method, the specified component is subscribed as an "internal" consumer
(to the "_internal" topic) and the proxy is automatically triggered to
subscribe VO wide to the "external" topic (as specified) using the broker.
/// </summary>
/// <remarks>
/// Note: a valid Notification Broker must be accessible in order to perform
this operation. Note also that "internal" topics are automatically mapped to
"<i>topic.Name</i>_internal".
/// </remarks>
/// <param name="topic">the topic to subscribe to</param>
/// <param name="consumer">the EPR of the consuming component</param>
/// <param name="type">the type of consumer ("WS", "APP", "WSRF")</param>
/// <returns>true, if no error occurs</returns>
public bool createSubscription(XmlQualifiedName topic, XmlElement consumer,
string type)
createDirectsubscription
/// <summary>
/// Subscribes a component to this proxy with the specified topic, i.e. if the
proxy is triggered to forward a notification the subscribed component is
invoked. Generally, this is used to subscribe components <i>behind</i> the
proxy to the latter, respectively to subscribe proxies to proxies.
/// </summary>
/// <remarks>
/// Note: This operation does not require a broker. Internal and external topics
need to be distinguished (by default by adding "_internal" to the first
ones. Also note that subscribing type "WSRF" is similar to calling the WSNotification specified "suscribe".
/// </remarks>
/// <param name="topic">the topic to subscribe to</param>
/// <param name="consumer">the Endpoint Reference of the subscribing
componet</param>
/// <param name="type">"WS", "APP" or "WSRF"</param>
/// <returns>The EPR of the subscription or null if failed. If the subscription
already exists, the respective EPR is returned and the component <b>not</b>
subscribed again.</returns>
public XmlElement createDirectSubscription(XmlQualifiedName topic, XmlElement
consumer, string type)
createBrokeredSubscription
/// <summary>
Page 106
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
/// Registers this instance of the proxy as a <i>consumer</i> of the specified
topic at the Notification Broker, thus triggering subscription. This means
that this proxy subscribes to all(!) producers of the respective topic and
all changes in producers are automatically updated.
/// </summary>
/// <param name="topic">the topic to subscribe to as XmlQualifiedName</param>
/// <returns>true, if no error occurs</returns>
public bool createBrokeredSubscription(XmlQualifiedName topic)
forwardNotification
/// <summary>
/// Forward a xml document (msg) as a notification of a specific topic
(topicdesc) to ALL subscribers of this specific topic. This method is invoked
by the event producer to send a notification.
/// </summary>
/// <param name="topicdesc">the topic as XmlQualifiedName
(namespace:topic)</param>
/// <param name="msg">the notification message as xml document.</param>
/// <returns>true if no error occurs</returns>
public bool forwardNotification(XmlQualifiedName topicdesc, XmlElement msg)
getTopics
/// <summary>
/// retrieve a list of all topics registered at the proxy
/// </summary>
/// <returns>the serialised list of topics</returns>
// <Topics>
//
<TopicSpace namespace="topicnamespace1">
//
<Topic>topic1</Topic>
//
<Topic>topic2</Topic>
//
...
//
</TopicSpace>
//
...
// </Topics>
public XmlElement getTopics()
querylog
/// <summary>
Page 107
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
/// returns the logged actions as an xml document
/// </summary>
/// <returns>an XmlElement representing the complete log</returns>
public XmlElement querylog()
6.1.1.67 Example
This example contains:
-
Creation of a new proxy
Configure it to use a predefined broker
Register the tester as producer to the new proxy
Subscribe the tester as consumer the new proxy and start a listener
Sending a message to the new proxy
Receiving the message
Subscribing an external web service
NotificationProxy is the Reference to the proxy‟s interface, proxy is the instance.
//Instantiate proxy through WSRF Interface
string url_Proxy = "<the proxy’s location>";
GCGResourceFactoryBinding proxy = new GCGResourceFactoryBinding(url_Proxy);
Create creationparams = new Create();
CreateResponse response = proxy.Create(creationparams);
// workaround for local computername issue (if the proxy is local, the response
adress will be localhost obviously is not reachable from outside)
response.ResourceEndpoint.Address.Value = url_Proxy;
EndpointReferenceType epr_Proxy = response.ResourceEndpoint;
// prepare configuration
NotificationProxy.configure configure = new NotificationProxy.configure();
configure.ServiceInstanceRegistryURL = "<the SIR location>";
configure.NotificationBrokerName = "<the logical Broker Name>";
// execute configuration
XmlElement configured = proxy.configure(configure).configured;
// register as producer to the proxy
NotificationProxy.registerProducer registrationrequest = new
NotificationProxy.registerProducer();
XmlQualifiedName topic = new XmlQualifiedName("<topic>", "<topic namespace>" );
registrationrequest.topic = topic;
bool response = proxy.registerProducer(registrationrequest).registered;
// start listener
// remember: listen to “_internal” topic
Page 108
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
AsynchronousNotificationListener listener = new
AsynchronousNotificationListener(Convert.ToInt32(("<port>"));
// listen to _internal topic
// incoming notification is forwarded to the “notifycallback” method
XmlQualifiedName internaltopic = new XmlQualifiedName( topic.Name+"_internal",
topic.Namespace );
TopicExpression substopic =
WellknownDialects.SIMPLE.createExpression(internaltopic);
substopic.addHandler(new TopicExpressionListener(notifyCallback));
listener.registerExpression(substopic);
// subscribe to proxy
EndpointReferenceType eprConsumer = new EndpointReferenceType();
NotificationProxy.createSubscription subscriptionrequest = new
NotificationProxy.createSubscription();
subscriptionrequest.consumer = WSUtilities.Serialize(eprConsumer);
subscriptionrequest.topic = topic;
subscriptionrequest.type = "WSRF";
response = proxy.createSubscription(subscriptionrequest).subscribed;
// sending notification
NotificationProxy.forwardNotification notification = new
NotificationProxy.forwardNotification();
notification.topicdesc = topic;
XmlElement xmlmsg = msg.CreateElement("Message", "http://docs.oasisopen.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd" );
xmlmsg.InnerXml = "message content";
notification.msg = xmlmsg;
response = proxy.forwardNotification(notification).notified
// receiving notification
private ArrayList eventLog;
private void notifyCallback( Topic topic, NotificationMessageHolderType message
)
{
LoggedEvent notification = new LoggedEvent();
notification.eventTime = DateTime.Now;
notification.eventTopic = new XmlQualifiedName(topic.TopicName,
topic.TopicSpace);
notification.eventSource = message.ProducerReference;
notification.eventMessage = message.Message;
eventLog.Add( notification );
Page 109
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
}
//subscribe a web service to the proxy.
// Connection to the proxy
NotificationProxy.NotificationProxyServiceWse proxy = new
NotificationProxy.NotificationProxyServiceWse();
EndpointReferenceType epr_Proxy = WSUtilities.toEPR("<stringEPR>");
// The following line is not necessary it is only necesarry when target is
not WSRF
// proxy.Url = <URL>
// The following line is essential. The URL of the service is set and
additionally the resourceID
// is transfered in the correct way not in the URL
WSUtilities.setEPR(proxy, epr_Proxy);
NotificationProxy.createSubscription subscriptionrequest = new
NotificationProxy.createSubscription();
// EPR setting
EndpointReferenceType eprConsumer = WSUtilities.toEPR(<EPR>);
subscriptionrequest.consumer = WSUtilities.Serialize(eprConsumer);
subscriptionrequest.type = "WS";
// subscription request with topic "SLA_violation"
topic = new XmlQualifiedName("<topic name>", "<topic namespace>");
subscriptionrequest.topic = topic;
bool response = proxy.createSubscription(subscriptionrequest).subscribed;
6.1.1.68 Notification Proxy Factory
There are two different ways creating a proxy. Additional to the factory you can directly create proxy
resources. Both ways are explained in the example section.
6.1.1.68.1 Interface
/// <summary>
/// instantiate the notification proxy and return the epr
/// </summary>
/// <param name="proxyURL"></param>
/// <param name="serviceInstanceRegistryURL"></param>
/// <param name="brokerName"></param>
/// <returns>the serialised epr of the instance (null if failed)</returns>
public EndpointReferenceType Instantiate( string proxyURL, string
serviceInstanceRegistryURL, string brokerName )
Page 110
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.68.2 Example
The first an easier way to create a new proxy is to use the notification proxy factory.
cb_notificationproxy_factoryurl and cb_notificationproxy_url are ComboBoxes,
tb_Registry_BrokerName is a TextBox.
private UVa.GCG.WSRF.Common.WS.Addressing.EndpointReferenceType
EPR2ADR(NotificationProxyFactory.EndpointReferenceType epr)
{
return new UVa.GCG.WSRF.Common.WS.Addressing.EndpointReferenceType( new
UVa.GCG.WSRF.Common.WS.Addressing.AttributedURI(null, epr.Address.Value), new
UVa.GCG.WSRF.Common.WS.Addressing.ReferencePropertiesType(epr.ReferenceProper
ties.Any), null, null, null, null);
}
private void bt_notificationproxy_instantiate_Click(object sender,
System.EventArgs e)
{
// create stubs
proxy_notificationproxy = new
NotificationProxy_Tester.NotificationProxy.NotificationProxyServiceWse();
proxy_notificationproxy.Url = cb_notificationproxy_url.Text;
proxy_notificationproxyfactory = new
NotificationProxy_Tester.NotificationProxyFactory.NotificationProxyFactoryWse
();
proxy_notificationproxyfactory.Url = cb_notificationproxy_factoryurl.Text;
// contact the factory
epr_notificationproxy = EPR2ADR( proxy_notificationproxyfactory.Instantiate(
cb_notificationproxy_url.Text, cb_Registry_URL.Text,
tb_Registry_BrokerName.Text ) );
The second way to create new instances is to directly use the WSRF interface for resource creation.
Ddl_ProxyUrl is a DropDownList, tb_initProxyEpr and tb_SIRUrl are TextBoxes. The code
snippets are part or the notification web interface.
private EndpointReferenceType createEPR(string serviceURL)
{
GCGResourceFactoryBinding proxy = new GCGResourceFactoryBinding(serviceURL);
Create creationparams = new Create();
CreateResponse response = proxy.Create(creationparams);
// workaround for local computername issue
response.ResourceEndpoint.Address.Value = serviceURL;
return response.ResourceEndpoint;
Page 111
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
}
protected void bt_instantiate_Click(object sender, System.EventArgs e)
{
string url_Proxy;
url_Proxy = ddl_ProxyUrl.SelectedValue;
EndpointReferenceType epr_Proxy = createEPR(url_Proxy);
tb_initProxyEpr.Text = WSUtilities.toString(epr_Proxy);
}
protected void bt_configure_Click(object sender, System.EventArgs e)
{
// link to Proxy EPR
Proxy.NotificationProxyServiceWse proxy = new
Proxy.NotificationProxyServiceWse();
EndpointReferenceType epr_Proxy = WSUtilities.toEPR(tb_initProxyEpr.Text);
WSUtilities.setEPR(proxy, epr_Proxy);
// prepare configuration
Proxy.configure configure = new Proxy.configure();
//determine SIR Url from ddl and tb
string url_SIR;
url_SIR = ddl_SIRUrl.SelectedValue;
configure.ServiceInstanceRegistryURL = url_SIR;
// SIR Url found
configure.NotificationBrokerName = tb_BrokerName.Text;
// execute configuration
XmlElement configured = proxy.configure(configure).configured;
}
6.1.1.69 Notification Broker
6.1.1.69.1 Interface
The brokers interface is normally only used by the proxies.
For debugging/testing you can use the given methods. Other methods are available for more
convenient test environments (i.e. list subscriptions at the broker). These methods must not be used
for normal applications since in real environments the broker will not be accessible in other ways
than the needed methods for the proxies.
registerProducer
Page 112
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
/// <summary>
/// register an epr as a producer of "topic"
/// if the topic does not yet exist, it will be added to the topic list
/// if the topic does exist, the epr will only be added, if the epr has not been
registered yet
/// </summary>
/// <param name="topic"></param>
/// <param name="epr"></param>
/// <returns>True, when added or already existing. False , if not existing due
unknown reason</returns>
public bool registerProducer(XmlQualifiedName topic, XmlElement producer)
subscribe
/// <summary>
/// subscribe a notifiation proxy to a specific topic
/// -> put into list of subscribers and forward request to all producing proxies
/// </summary>
/// <param name="topic"></param>
/// <param name="consumer">epr of the cosuming proxy</param>
/// <returns>true if successful, otherwise false (also if already
existent)</returns>
public bool subscribe(XmlQualifiedName topic, XmlElement consumer)
implicitly WSRF (this is proxy->proxy subscription)
// type
getConsumers
/// <summary>
/// retrieve a list of all subscribers to one topic
/// if the topic-string is left empty, the entire list is returned
/// the structure is corresponding with the internal list
/// </summary>
/// <param name="topic"></param>
/// <returns>list of subscriptions</returns>
public XmlElement getConsumers(XmlQualifiedName topic)
getProducers
/// <summary>
Page 113
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
/// retrieve a list of all producers of one topic
/// if the topic-string is left empty, the entire list is returned
/// the structure is according to the internal list:
/// </summary>
/// <param name="topic"></param>
/// <returns>list of productions</returns>
public XmlElement getProducers(XmlQualifiedName topic)
getTopics
/// <summary>
/// get all corresponding topics with the specified type
/// Subscription: all topics where an subscription ist available
/// Production: all topics with an known producer
/// All: all known topics
/// </summary>
/// <param name="topic"></param>
/// <returns>an array of topics</returns>
public XmlQualifiedName[] getTopics(String type)
6.1.1.69.2 Example
registerProducer
Parts of the proxy‟s code. url_registry and str_BrokerName are both string and part of the
proxy resource.
private XmlElement getSIREntry(string entryID)
{
ServiceInstanceRegistry_Java.SIRServiceWse proxy_registry = new
ServiceInstanceRegistry_Java.SIRServiceWse();
proxy_registry.Url = url_Registry;
return
WSUtilities.Serialize(WSUtilities.toEPR(proxy_registry.getServiceEpr(entryID)
));
}
public bool registerProducer(XmlQualifiedName topic) // note, type not relevant
{
if ((topic == null) || (url_Registry == "") || (str_BrokerName == "")) {
return false; }
// no configuration
Page 114
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
// 1) retrieve the broker from the registry
EndpointReferenceType epr_broker =
(EndpointReferenceType)WSUtilities.Deserialize(getSIREntry(str_BrokerName),
typeof(EndpointReferenceType));
if (epr_broker == null) { return false; }
// no broker
// 2) create a reference to the broker
NotificationBroker.NotificationBrokerServiceWse proxy_broker = new
NotificationBroker.NotificationBrokerServiceWse();
proxy_broker.Url = epr_broker.Address.Value;
WSUtilities.setEPR(proxy_broker, epr_broker);
// 3) register as producer
NotificationBroker.registerProducer regprod = new
NotificationBroker.registerProducer();
// workaround for local computername-issue
EndpointReferenceType tmpepr = ServiceBase.EPR;
regprod.producer = WSUtilities.Serialize(tmpepr);
regprod.topic = topic;
bool response = proxy_broker.registerProducer(regprod).registered;
return response;
}
getproducers
At the broker web interface, tb_BrokerEpr is a textbox for the brokers EPR. The script retrieves all
productions and afterwards lists them in a webpage. (not included in the listing)
//connection to the broker
Broker.NotificationBrokerServiceWse broker = new
Broker.NotificationBrokerServiceWse();
EndpointReferenceType epr_Broker = WSUtilities.toEPR(tb_BrokerEpr.Text);
WSUtilities.setEPR(broker, epr_Broker);
// get producers
Broker.getProducers getproducers = new Broker.getProducers();
getproducers.topic = new XmlQualifiedName("", "");
//all topics
XmlElement registeredP = broker.getProducers(getproducers).producers;
XmlSerializer xserP = new XmlSerializer(typeof(RegisteredProducers));
Page 115
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
XmlSerializerNamespaces xns = new XmlSerializerNamespaces();
xns.Add("", "");//"www.hlrs.de/notificationproxy" );
XmlNodeReader xreaderP = new XmlNodeReader(registeredP);
RegisteredProducers prods = (RegisteredProducers)xserP.Deserialize(xreaderP);
/*
<RegisteredProducers>
<Production>
<Topic>
topicname
</Topic>
<Producer>
eprProducer
</Producer>
</Production>
...
</RegisteredConsumers>
*/
[XmlRoot("Production")]
public class Production
{
[XmlElement("Topic")]
public XmlQualifiedName topic;
[XmlElement("Producer")]
public EndpointReferenceType eprProducer;
}
[XmlRoot("RegisteredProducers")]
public class RegisteredProducers
{
[XmlElement("Production")]
public Production[] productions;
}
Page 116
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Reputation Service
Installation Guide
The reputation service can be installed on either a Windows or Linux machine. You will need to have
the following components before you install the reputation service.
6.1.1.70 The Reputation Service Release Package
The reputation service release package can be downloaded from
https://svn.infsec.ethz.ch/trustcom/PartnerInternal/UoK/pub/Reputation Service/Reputation
Service.zip
6.1.1.71 Package Contents
There are three folders in this package, i.e. installation, javadoc and source.
Name
Type
Description
installation
directory
This directory contains two sub-directories i.e.
“reputation service source” and “reputation
service demonstration GUI”.
javadoc
directory
This directory contains the entire java doc of the
reputation service.
source
directory
This directory contains two sub-directories i.e.
client and reputation, which include all of the
client Java source code and the reputation
service Java source code.
reputation service source
/reputationInstallationGuide.doc
WS word
This document
reputation service
source/README.doc
WS word
This is the specification of the reputation service
interface.
reputation service source
/ReputationService.wsdl
XML file
This is the wsdl of the reputation service.
reputation service source /lib
directory
This is the sub-directories, which includes all
needed libraries for the reputation service.
reputation service source /stub
directory
This is the directory, which includes all of the
stubs to access the reputation service.
reputation service source
/example
directory
This directory includes some example Java
sources
reputation service source
/classes
directory
This is the directory for containing all needed
Java classes.
reputation service source
/deploy
directory
This is the directory for containing example files
to deploy web services.
reputation service demonstration
GUI/ ReputationClient.zip
Zip file
This is the zip file for a reputation service
demonstration, which also includes the tools for
initialising and removing the reputation database.
reputation service demonstration
Text file
This is the instructions about how to run the
Page 117
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Name
Type
GUI/ README.txt
Description
reputation service demonstration.
client
directory
This sub-directory includes all of the Java files,
which implements some example clients.
reputation
directory
This sub-directory includes all of the Java files,
which implements the reputation service and the
database management service.
Requirements
The following systems should be installed and working prior to installing the reputation service.
A Tomcat application server (version 4.x is recommended by the Apache Axis group). See
http://tomcat.apache.org/
Web Services Axis. See http://ws.apache.org/axis/
MySQL database server. See http://dev.mysql.com/downloads/mysql/5.0.html
Java Runtime Environment - required for running Tomcat. See http://java.sun.com/
Installation
In order to install the reputation service, users have to follow the steps below. Optionally, the
database management service can be installed by carrying out an extra deployment step.
6.1.1.72 <Step #1 Make sure that the Tomcat Application server is installed and working correctly >
Please refer to the Tomcat manual at http://jakarta.apache.org/tomcat/ . Assume that you
have installed Tomcat in the directory $TOMCAT on your computer.
Start the Tomcat server by the command: “$TOMCAT/bin/startup.sh”. In Windows, a Tomcat server can be
started by clicking its icon. We assume the default port for Tomcat is 8080. Open your webbrowser and go to
the URL http://localhost:8080 . You should see the welcome page of the Tomcat server. If not, refer to the
Tomcat manual and check the firewall on your computer system.
6.1.1.73 <Step #2 Make sure that the MySQL server is installed and working correctly >
Start the MySQL server by the command: “/etc/init.d/mysqld start”. In Windows, a MySQL server can be
started via the control panel (Administrative Tools, Services).
6.1.1.74 <Step #3 Install Axis on Tomcat >
Download a package of Apache Axis from http://ws.apache.org/axis/, version 1.4, and unwrap the package
into a new directory, say </home/installation/axis>.
Copy the directory </home/ installation /axis/webapps/axis> along with all its contents into the
<$TOMCAT/webapps> directory. Now you will have a new directory in Tomcat: <$TOMCAT/webapps/axis>.
Restart Tomcat. The Tomcat server can be shut down by the command “$TOMCAT/bin/shutdown.sh”. In
Windows, the Tomcat can be shut down by closing its console.
Page 118
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Navigate to the start page of the webapp, http://localhost:8080/axis/. You should now see an Apache-Axis
start page. You can find more details about Axis installation instructions in your axis installation directory
</home/ installation /axis/docs>.
6.1.1.75 <Step #4 Copy files to Tomcat >
Copy the directories ke, org and reputation in the installation/reputation service source/classes into
$TOMCAT/webapps/axis/WEB-INF/classes and copy all of the jar files in installation/reputation service
source/lib into the directory $TOMCAT/webapps/axis/WEB-INF/lib.
6.1.1.76 <Step #5 Edit the database configuration file >
DbProperties is a text file, which specifies properties of the installed MySQL database. This file is in
the directory of $TOMCAT/webapps/axis/WEB-INF/classes/ke.files
dbDriverName
= com.mysql.jdbc.Driver
dbDriverPrefix
= jdbc:mysql:
dbURL
= //localhost:3306/trustCom
dbUserName
= root
dbPassWd
= password
maxActive
= 300
maxIdle
= 30
maxWait
= 5000
testOnBorrow
= true
testOnReturn
= false
timeBetweenEvictionRunsMillis
= 300000
minEvictableIdleTimeMillis
= 28800000
testWhileIdle
= false
numTestsPerEvictionRun
=3
The database can be installed on a different machine from the reputation service. If so dbURL
should point to that machine. The port may have a different value if wished.
The database has to be created by hand with the MySQL command:
#mysql –ppassword (Here, it is assumed the password of the root account is password. Note that
there is no space between –p and the password itself.)
mysql> CREATE DATABASE trustCom
Make sure the database is accessible to a remote user, who logs into the account specified by
dbUserName with the password specified by dbPassWd. You may need to modify the user table in
the database mysql to enable a remote access to the database i.e. adding a record into the table
with Host=%, User=root, Password is the same as in the above configuration. All of the permissions
are set to Y.
Page 119
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.77 <Step #6 Deploy web services on Tomcat and Axis >
Make sure the Tomcat server is up.
Run the following commands to set the Axis environment variables in your computer.
set AXIS_HOME=/home/installation/axis
set AXIS_LIB=$AXIS_HOME/lib
set AXISCLASSPATH=$AXIS_LIB/axis.jar:$AXIS_LIB/axis-ant.jar:$AXIS_LIB/commonsdiscovery-0.2.jar:$AXIS_LIB/commons-logging1.0.4.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/saaj.jar:$AXIS_LIB/log4j1.2.8.jar:$AXIS_LIB/wsdl4j-1.5.1.jar
export AXIS_HOME; export AXIS_LIB; export AXISCLASSPATH
In Windows, the environment variables should be set as follows:
AXIS_HOME=c:\home\installation\axis
AXIS_LIB=%AXIS_HOME%\lib
AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\axisant.jar;%AXIS_LIB%\commons-discovery-0.2.jar;%AXIS_LIB%\commons-logging1.0.4.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;%AXIS_LIB%\log4j1.2.8.jar;%AXIS_LIB%\wsdl4j-1.5.1.jar
Please note the actual file names may differ from the above file names according to different versions of Axis.
For example, commons-discovery.jar may be commons-discovery-0.2.jar in AXIS version 1.2.1.
In the deployment directory where the file deploy.wsdd is located, run the following command:
java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient deploy.wsdd
In Windows, the command is:
java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient deploy.wsdd
This command will deploy the reputation service into the Axis SOAP server.
In order to deploy the database management service, you have to deploy this service by using the
deployDatabase.wsdd.
Now restart Tomcat to activate the web service server. In order to check the reputation service, type:
http://localhost:8080/axis/services/ReputationService?wsdl
to a web browser, you should see the wsdl of this service.
(Similarly, you may see the database management service‟s
http://localhost:8080/axis/services/DatabaseManagementService?wsdl.)
wsdl
by
typing:
Page 120
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
In order to remove the service from the server, you should go to the deployment directory, and type
in the following command:
java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient undeploy.wsdd
Note that which web service is actually removed is specified by the service parameter in
the undeploy.wsdd file.
6.1.1.78 <Step #7 Initialise the Database >
Unzip the ReputationClient.zip into any directory and type in the command
java -jar initialise.jar <URL>
where <URL> is the address of the database management service. E.g.
beta.cs.kent.ac.uk:9080/axis/services/DatabaseManagementService
http://issrg-
This command will create all needed database tables for the reputation service and initialise them.
The structure of these tables are defined by database schemas. This operation will ensure the
reputation service contains no entity but it is ready to receive an “addActor”, “addActorExisting”,
“rate” or “getReputation” request.
If you want to remove all of the existing entities in the reputation service, then type in the command
java -jar drop.jar <URL>
This web service operation will remove all of the database tables for this reputation service so that
users are able to use the initialise method to create and initialise new tables.
User‟s Guide
The reputation service is running when the Tomcat server is up. Users need their own clients to
invoke this service. The following bit of Java code presents a way to invoke a method of the service.
Assuming the service is located at
http://issrg-beta.cs.kent.ac.uk:9080/axis/services/ReputationService
String endpoint = "http://issrg-beta.cs.kent.ac.uk:9080/axis/services/ReputationService";
Service service = new Service();
Call
call
= (Call) service.createCall();
call.setTargetEndpointAddress(new java.net.URL(endpoint) );
call.setOperationName(new QName("http://soapinterop.org/", <method>) );
String ret = (String) call.invoke(new Object[]{ <arg1,arg2,…,argn>} );
where <method> is a string, which indicates which method (e.g. “getReputation”) is invoked; and
<arg1, arg2, …, argN> are the parameters of the invoked method.
Page 121
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.79 Get reputation score
The method getReputation(String rateeID) is used to get the reputation score of an entity, which is
identified by rateeID. This method returns a string, which consists of the reputation score and the
number of reputation scores given to the entity. For example, “0.8743*5” represents the reputation
score of an entity is 0.8743 and the entities has been rated 5 times.
This method will throw an exception if the entity identified by rateeID does not exist.
6.1.1.80 Rate an entity
The method rate(String raterID, String rateeID, Float rating, String transactionID) is used to give a
rating to a ratee with the value rating. The ratee is identified by rateeID and the rater is identified by
raterID. transactionID can be any string value, which currently is not being used (in future it may be
used to identify the transaction that is being rated).
The returned string from this method is a status, for example, “X rates Y with 0.4”. An exception will
be thrown if the rater and/or ratee do not exist, or the rating value is not between 0 and 1, or raterID
is identical to rateeID.
6.1.1.81 Add a new or existing entity
The method addActor(String nickName, String entityID) is used to add a new entity into the
reputation service. This entity is identified by entityID. nickName can be any string, which is currently
ignored. The new entity that is added is given a reputation score of 0.5 and the number of scores
given to the entity is 0.
After an entity is added into the reputation service, it can be rated by other entities or it can rate
another entity. The returned string from the method is a status, such as “<nickName> (<entityID>) is
added”. This method throws an exception if entityID is null or the entity already exists.
If users want to add a entity with an existing reputation, then the method addActorExisting(String
nickName, String entityID, Float rs, Integer c) should be called, where rs is a reputation score and c
denotes the number of scores already given to the entity. This method throws an exception if
entityID is null, the entity already exists, the reputation score is invalid (i.e. not in the range 0 to 1), or
the number of scores is less than 0. The new entity added will have rs as its reputation score and c
as the number of scores given to the entity.
Developer's Guide
6.1.1.82 Extension method
Although we recommend ignoring this method, addTransaction(String entityID1, String entityID2,
String transactionID) can be used to add a transaction, identified by transactionID, between two
entities, identified by entityID1 and entityID2 respectively.
By maintaining transactions between entities, it would be possible in the future for raters to be only
allowed to rate other entities for which there is a transaction between them. Developers would then
need to put some additional restrictions on the ability to rate an entity by editing the internal method
isAllowedToRate, which checks if this rating is allowed. This internal method is defined as
private boolean isAllowedToRate(String raterID,String rateeID),
which is called inside the rate method. It returns true when the rater (identified by raterID) is allowed
to rate the ratee (identified by rateeID). Otherwise, an exception is thrown so that the rate method
would not carry out this rating.
Page 122
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.83 API Documentation
The Java doc and source code of the reputation service (including the database management
service) and example clients are included in the reputation service‟s release package. They are also
available in:
https://svn.infsec.ethz.ch/trustcom/PartnerInternal/UoK/pub/Reputation Service
6.1.1.84 Example Client
Unzip the installation/reputation service demonstration GUI/ReputationClient.zip into any directory,
in which the sub-directory ReputationClient will be created. Then go to the ReputationClient directory
and type in the command
java -jar reputation2.0.jar <URL> where <URL> is the address of the reputation service. E.g.
http://issrg-beta.cs.kent.ac.uk:9080/axis/services/ReputationService
This standalone client assumes JAVA_HOME is set. It uses java from there. Note that all of the
entities involved in this demonstration are identified by LDAP DNs. Therefore, only LDAP DNs are
allowed to be typed in for entityIDs via the demonstration user interface.
Secure Audit Web Service
Installation Guide
The SAWS Installation package can be downloaded from the PERMIS project web site at the
University of Kent i.e. http://sec.cs.kent.ac.uk/permis/downloads/Level1/SAWS.shtml
6.1.1.85 Package Contents
The installation package includes the following files.
Name
Type
Description
saws.jar
jar file
The library for the SAWS server and SAWS
Viewing Tool.
iaik_jce.jar soap.jar
jar files
Dependent Java libraries from third parties.
saws.xml
XML
The SAWS server configuration file.
sawsDeploy.wsdd
wsdd
The SAWS web service deployment definition
file.
saws.wsdl
wsdl
The SAWS web service interface description
file.
tomcat.keystore
Tomcat
keystore
This is used for the Tomcat SSL configuration.
Its password is “changeit”.
sawsClient.keystore
client
keystore
A demo SAWS client keystore, which is used
for the SSL configuration. Its password is
“changeit”.
axis.jar
servlet-2_3-fcs-classfiles.jar
log4j.jar
Page 123
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Name
Type
Description
rootca.key
signing key
This is a demo Root CA signing key in PEM
format. Before you get your own Root CA, you
can use this Root CA for testing purposes. Its
password is “rootca123”.
rootca.crt
public key
certificate
The self-signed public key certificate for the
Root CA.
vt.p12
p12 key file
The SAWS Viewing Tool (VT) p12 key file,
which is used for VT to read SAWS log files. Its
password is “changeit”.
vt.crt
public key
certificate
The VT public key certificate, which is exported
from the VT key file vt.p12.
sawssoapClientDemo.java
Java file
A sample SAWS web service client Java
application. This demo shows you how to
invoke the SAWS web service in Java.
sawsAPITest.java
Java file
A sample SAWS API application. This shows
you how to read and write SAWS logs from
within a Java application.
6.1.1.86 Requirements
The following systems should be installed and working prior to installing SAWS.
A Tomcat application server (version 4.x or 5.x, but only version 4.x is recommended by the Apache
Axis group. In this demonstration, we use version 4.x).
Java Runtime Environment is required to run the Tomcat. The version of JRE you need is 1.4. JRE
is available from http://java.sun.com/
Note:
1. In Windows, there could probably be more Java installations on your computer, but we assume
that the same Java installation is used by both Tomcat and SAWS throughout the SAWS installation
and initialization. When you install Tomcat, make sure Tomcat chooses JRE 1.4. When you invoke
Java in this user guide, please include the whole path to java.exe, for example
c:\j2sdk1.4.2_10\jre\bin\java.exe, this can make sure that the same Java installation is used by
SAWS. Please do not rely on the system environment variable PATH in your system to invoke Java
and omit the Java home path, as this may not work correctly when the PATH configuration for Java
is not necessarily consistent with the Windows registry configurations for Java.
2. When SAWS works on top of Tomcat for the web service interface, to start up
Tomcat, please double-click %TOMCAT%\bin\startup.bat (for Windows) or
$TOMCAT/bin/startup.sh (for Linux) in a file explorer, or run startup.bat or
startup.sh in the folder <%TOMCAT%\bin\> or <$TOMCAT/bin/> in a command console window. If
you start up Tomcat in other ways such as from the Tomcat
Windows application menu, SAWS may not work correctly along with AXIS. To shut down SAWS
along with Tomcat, you need to click the cross button of the
Tomcat window to close the Tomcat window along with SAWS.
6.1.1.87 Installation of SAWS
To complete the SAWS Installation, you just follow those steps as the below.
Page 124
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.87.1 <Step #1 Install Tomcat>
Make sure that the Tomcat Application server is installed and working correctly.
Please refer to the Tomcat manual at http://jakarta.apache.org/tomcat/.
Assume that you have installed Tomcat on the directory $TOMCAT on your computer.
Start Tomcat by the command: “$TOMCAT/bin/startup.sh”. We assume the default ports for Tomcat
is 8080 (without ssl) and 8443 (with ssl). Open your web browser and go to the http://localhost:8080
URL. You should see the welcome page of Tomcat. If not, refer to the Tomcat manual and check the
firewall on your computer system.
6.1.1.87.2 <Step #2 Copy files>
Extract the files included in the installation
</home/sawsTestingPack/releasePack>.
package
zip
into
some
place,
says
Copy the two files tomcat.keystore and rootca.crt from the above directory into the directory
<$TOMCAT/conf>.
Copy the file iaik_jce.jar from the directory
</home/sawsTestingPack/releasePack> into the directory
<$JAVA_HOME/jre/lib/ext>.
Please note that on the Windows platform the directory file path has a different format such as
c:\home\sawsTestingPack\releasePack.
6.1.1.87.3 <Step #3 Edit java.security for Java environment>
Edit the file $JAVA_HOME/jre/lib/security/java.security, add a line after other
“security.provider” configurations: security.provider.6=iaik.security.provider.IAIK, in which the
number “6” may differ in your system.
6.1.1.87.4 <Step #4 Configure SSL for Tomcat >
Open the Tomcat configuration file <$TOMCAT/conf/server.xml> in an editor.
Locate the configuration section for SSL connection, edit it as follows.
<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8443" minProcessors="5" maxProcessors="75"
enableLookups="true"
Page 125
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
acceptCount="10" debug="5" scheme="https" secure="true"
useURIValidationHack="false" disableUploadTimeout="true">
<Factory
className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
clientAuth="true" protocol="TLS"
keystoreFile="$TOMCAT/conf/tomcat.keystore"
keystorePass="changeit"/>
</Connector>
Three changes are needed for this configuration file.
(1) Change the attribute "clientAuth" to “true” -- this will tell Tomcat to require mutual authentication
between Tomcat and Tomcat clients.
(2) Change the attribute "keystoreFile" to the path and file name of the Java keystore file
<tomcat.keystore> which is copied to your computer. Please use the actual directory path in your
system to replace the word $TOMCAT in the configurations.
(3) Change the attribute "keystorePass" to “changeit”, which is the default password for the Java
keystore <tomcat.keystore>.
Note: Please make sure that the comment brackets <!-- and --> around the above configuration
section are removed, so that the SSL configuration can be active.
6.1.1.87.5 <Step #5 Add rootca.crt into the Java trusted CA certificate store >
To enable mutual authentication between Tomcat and its clients, now you need to add the
demonstration root CA certificate home/sawsTestingPack/releasePack
/rootca.crt into the Java runtime trusted root CA certificate store. Run the following command in your
computer:
keytool -import -alias rootca -trustcacerts -file
/home/sawsTestingPack/releasePack/rootca.crt -keystore
$JAVA_HOME/jre/lib/security/cacerts
You are required to input the password for the keystore: changeit. Here we assume your Java 1.4 is
installed at the directory <$JAVA_HOME>.
6.1.1.87.6 <Step #6 Install the Apache Axis on Tomcat >
Download a package of Apache Axis from http://ws.apache.org/axis/, version 1.4, unwrap the
package into a new directory, say </home/sawsTestingPack/axis>;
Page 126
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Copy the directory </home/sawsTestingPack/axis/webapps/axis> along with all its contents into the
<$TOMCAT/webapps>, now you will have a new directory in
Tomcat: <$TOMCAT/webapps/axis>;
Restart Tomcat. If during Tomcat startup you get a “LogConfigurationException”, then you need to
remove the file $TOMCAT/webapps/axis/WEB-INF/lib/commons-logging-1.0.4.jar, then restart
Tomcat again.
Navigate to the start page of the webapp, http://localhost:8080/axis/. You should now see an
Apache-Axis start page. If you do not, then check the above two steps.
You can find more details about Axis installation instructions in your axis installation directory
</home/sawsTestingPack/axis/docs>.
Tips:
When starting up Tomcat, if you got an error:
org.apache.commons.logging.LogConfigurationException: Invalid class loader hierarchy. You have
more than one version of 'org.apache.commons.logging.Log' visible, which is not allowed. If so,
please find and remove the file
$TOMCAT/webapps/axis/WEB-INF/lib/commons-logging-1.0.4.jar, as Tomcat has already provided
such a class in its library.
6.1.1.87.7 <Step #7 Edit the configuration file saws.xml and copy it to Tomcat >
The default configuration file /home/sawsTestingPack/releasePack/saws.xml
contains the following contents:
<SAWSParameters>
<SAWSBasic
encryptionKeystoreLocation="/home/sawsTestingPack/encryption.keystore"
numberOfEncPasswordShares = "3"
logFileRoot="/home/sawsTestingPack/log/"
heartbeatInterval ="3000"
signRecordNumber="50000"
SAWSInterface = "webservice"
logEncryption = "yes"
vtPKC="/home/sawsTestingPack/releasePack/vt.crt"
rootCA="/home/sawsTestingPack/releasePack/rootca.crt"
debugLevel = "5"
/>
Page 127
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
<TPMAdvanced
signingKeystoreLocation="/home/sawsTestingPack/signing.keystore"
numberOfPasswordShares = "3"
trustedLocation="/home/sawsTestingPack/TCBLocation.dat"
12
hashAlg = "SHA-256"
/>
<UserInfo
userID="3"
userPKC="/home/sawsTestingPack/user1.crt"
userDN="cn=issrg,o=kent,c=uk" />
<UserInfo
userID="4"
userPKC="/home/sawsTestingPack/user2.crt"
userDN ="cn=cs,o=kent,c=uk" />
<CallbackHandler class="issrg.SAWS.callback.SAWSGUICallbackHandler" />
</SAWSParameters>
You need to edit this configuration file to fit your needs:
In the <SAWSBasic> section:
(1) encryptionKeystoreLocation should point to an encryption keystore location in your machine. This
encryption keystore will be generated by the SAWS nitialization process later, which will be used to
securely store some secrets in the log files.
(2) numberOfEncPasswordShares refers to how many shares the password to this encryption
keystore has. If its value is 3, then SAWS will subsequently require 3 SAWS administrators to input
a password share respectively to form the final password to the encryption keystore.
(3) logFileRoot refers to the log file root for holding SAWS log files.
(4) heartbeatInterval refers to the interval at which the heart beat records are generated by the
SAWS server. Its unit is milliseconds.
(5) signRecordNumber is the maximum number of log records a log file will hold.
When the number of log records in a log file reaches this number, the SAWS server will close this
log file, sign it, and then start a new log file.
(6) SAWSInterface is the client interface for this SAWS deployment. It should be
Page 128
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
“webservice” in this user guide. For web service interface, SAWS will try to read the client SSL
certificate and its DN in the certificate, only those DN‟s which are defined in the <DN2UserID>
section (see below) will be authorized to access SAWS. But SAWS can also work with an API
interface, in which case the value for this parameter should be “api”, and of course no authorization
is performed
(7) logEncryption indicates whether the logs are encrypted by a secret key. When its value is “yes”,
then log records will be encrypted by a secret key. When its value is “no”, then all log records will be
stored in the log files in the clear. The vtPKC and userPKC will be used to encrypt this secret key
(see below) and store it in the logs.
(8) vtPKC refers to the SAWS Viewing Tool (VT) public key certificate file. The VT PKC will only be
used if SAWS is configured to encrypt audit records. When confidentiality of audit records is needed
(i.e. logEncryption is set to “yes”), SAWS will generate a secret key that will be used to encrypt the
audit records in the log files. In this case the VT public key will be used to encrypt the secret key and
then store it in the log files. So later the SAWS Viewing Tool can use its private key to decrypt this
secret key and therefore decrypt the confidential log records.
(9) rootCA refers to the Root CA certificate which will be used to validate the signing key pair PKC
issued by the Root CA. The Root CA will issue the PKC for the SAWS signing key pair. We provide
a Root CA signing key in the SAWS package for testing purposes. If you do not have a Root CA and
this parameter - rootCA - is missing, then SAWS will work in testing mode to use the SAWS selfsigned PKC as its Root CA PKC.
(10) debugLevel indicates the different level of debug output information by SAWS. Its value is from
0 to 5. When its value is 0, then no debug information is output by SAWS. When its value is 5, then
most debug information is output by SAWS. SAWS outputs the debug information in the file
<running directory>/logs/SAWS_debug.log, by using Log4j API. In case of Tomcat, the “running
directory” is the “$TOMCAT/bin” directory.
In the < TPMAdvanced> section:
(11) signingKeystoreLocation should point to the signing keystore location in your system. This
signing keystore will be generated by SAWS later which will be used to sign the log files.
(12) numberOfPasswordShares refers to how many shares the password to this signing keystore
has. If its value is 3, then SAWS will subsequently require 3 SAWS administrators to input a
password share respectively to form the final password to the signing keystore.
(13) trustedLocation refers to a file in a trusted location. This file will be securely generated by
SAWS and used to contain some secure SAWS system information.
(14) hashAlg refers to the hash algorithm name to be used by SAWS. The supported algorithm
names are: SHA-1, MD5, SHA-256, SHA-384 and SHA-512. This information is recorded in the log
files, so the log file reader can retrieve it to read the files and check the hash value.
In the <UserInfo> section:
Page 129
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
(15) The <userID> field should be a simple integer, normally starting from 1. Each SAWS client must
be allocated a different integer. This integer will be added to each audit record that is given to SAWS
by the client.
(16) The <userDN> field should contain the distinguished name of a SAWS client (obtained from its
public key certificate). SAWS will use this value to map into the corresponding userID field.
(17) The <userEncryption> parameter is an optional parameter that is used to point to the user‟s
public key certificate. This will only be used when SAWS is configured to encrypt log records. In this
case SAWS will encrypt the secret key using the public key of the user, and then store it in the log
files (in the same way as it does above with the vtPKC (Viewing Tool PKC). So later the user can
use its private key to decrypt this secret key and therefore read the confidential log records.
NOTE. The <UserInfo> section can be repeated as many times as required (typically there will be
one entry for every SAWS client). If you are in the Windows system, then the directory path names
in
the
configurations
should
conform
to
Windows
conventions,
such
as
c:\home\sawsTestingPack\log\.
In the <CallbackHandler> section:
(18) The <class> attribute represents the Java class that implements a callback handler for SAWS.
This handler defines the way SAWS must interact with the user for (showing error, warning and
information messages, asking for information like password or certificate data, etc.). SAWS provides
3 callback handlers in the current version:
“issrg.SAWS.callback.SAWSGUICallbackHandler”,
“issrg.SAWS..callback.SAWSCmdPromptCallbackHandler” ,
“issrg.SAWS.calback.SAWSFileCallbackHandler”.
The first one interacts with the user by graphical components; the second one uses command line
(console) and the last one reads/writes information from/to an input/output file. If no callback handler
is specified in the configuration file (saws.xml), the command line one will be used by default. If
SAWSFileCallbackHandler is used, two more attributes must be specified in the
CallbackHandler section: <inputfile> (to indicate the file with the inputs for SAWS execution) and
<outputfile> (to set the file to where SAWS will write the output information). An example is shown
bellow:
<CallbackHandler class="issrg.SAWS.callback.SAWSFileCallbackHandler"
inputFile="/home/sawsTestingPack/FileCallbackHandlerInput.txt"
outputFile="/home/sawsTestingPack/FileCallbackHandleroutput.txt"/>
The format for the input file can be found in the Developer‟s Guide.
Page 130
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
After editing has finished, you can copy saws.xml to the directory <$TOMCAT/bin>.
6.1.1.87.8 <Step #8 Change the SAWSInterface attribute in saws.xml >
After copying saws.xml to the directory <$TOMCAT/bin>, now you can edit
saws.xml in </home/sawsTestingPack/releasePack> again to change the
SAWSInterface attribute to the value "api". This is for SAWS first time initialization in the API mode.
Therefore at this point you will have two copies of saws.xml in your system, with the only difference
being in the SAWSInterface attribute in the configurations -- one is "api" and one is "webservice".
6.1.1.87.9 <Step #9 Copy SAWS libraries to Tomcat>
Copy saws.jar and soap.jar in </home/sawsTestingPack/releasePack> into the directory
<$TOMCAT/webapps/axis/WEB-INF/lib >.
6.1.1.87.10 <Step #10 Deploy SAWS on Tomcat and Axis>
Start up Tomcat.
Run the following commands to set the Axis environment variables in your computer.
set AXIS_HOME=/home/sawsTestingPack/axis
set AXIS_LIB=$AXIS_HOME/lib
set AXISCLASSPATH=$AXIS_LIB/axis.jar:$AXIS_LIB/axis-ant.jar:$AXIS_LIB/co
mmons-discovery-0.2.jar:$AXIS_LIB/commons-logging-1.0.4.jar:$AXIS_LIB/ja
xrpc.jar:$AXIS_LIB/saaj.jar:$AXIS_LIB/log4j-1.2.8.jar:$AXIS_LIB/wsdl4j-1.5.1.jar
export AXIS_HOME; export AXIS_LIB; export AXISCLASSPATH
In the Windows System, the environment variables should be:
AXIS_HOME=c:\home\sawsTestingPack\axis
AXIS_LIB=%AXIS_HOME%\lib
AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\axis-ant.jar;%AXIS_LI
B%\commons-discovery-0.2.jar;%AXIS_LIB%\commons-logging-1.0.4.jar;%A
XIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;%AXIS_LIB%\log4j-1.2.8.jar;%AXI
S_LIB%\wsdl4j-1.5.1.jar
To set these environment variables, you need to go to Start -> Control Panel in
Windows, then select the item System, then click the button Environment Variables --in the popup
window, you can input the variables.
Page 131
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Please note the actual file names may differ from the above file names according to different
versions of AXIS. For example, commons-discovery.jar may be commons-discovery-0.2.jar in AXIS
version 1.2.1. You can find more details about Axis installation instructions in your axis installation
directory </home/sawsTestingPack/axis/docs>.
In the SAWS installation directory </home/sawsTestingPack/releasePack > where the file
sawsDeploy.wsdd is located, run the following command:
$JAVA_HOME/bin/java -cp $AXISCLASSPATH
org.apache.axis.client.AdminClient sawsDeploy.wsdd
In Windows System, the command is:
%JAVA_HOME%\bin\java -cp %AXISCLASSPATH%
org.apache.axis.client.AdminClient sawsDeploy.wsdd
Please use the actual Java home path in your system to replace the variable JAVA_HOME in the
commands above. This command will deploy the SAWS server into the Axis SOAP server.
Now restart Tomcat to activate the SAWS web service server
6.1.1.88 Installation of JSATS
6.1.1.88.1 <Step #1 Copy files>
After you copy saws.jar, iaik_jce.jar,soap.jar, servlet-2_3-fcs-classfiles.jar and axis.jar into the
directory <$JAVA_HOME/jre/lib/ext>.
6.1.1.88.2 <Step #2 Edit the JSATS configuration file>
In the directory </home/sawsTestingPack/releasePack >, you may need to edit the JSATS
configuration file saws.xml so that SAWSInterface = "api".
User‟s Guide
6.1.1.89 <Initialisation>
Now users need to initialize SAWS for the first time.
6.1.1.89.1 Generate the encryption keystore
Page 132
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
In the directory </home/sawsTestingPack/releasePack >, run the following command:
$JAVA_HOME/bin/java -cp soap.jar:saws.jar:log4j.jar issrg.SAWS.SAWSServer
In Windows, the command is:
%JAVA_HOME%\bin\java -cp soap.jar;saws.jar;log4j.jar issrg.SAWS.SAWSServer
You will see the following screen:
SAWS is now working in the command line mode. Please select one of the following
options:
Option 1: Create an encryption keystore
Option 2: Create a signing keystore
Option 3: Import the rootCA specified in the SAWS configuration file into the signing keystore. This is
required by keytool to be able to later import the PKC issued by this rootCA into the signing
keystore.
Option 4: Output a PKC request file from the signing keystore
Option 5: Input the PKC issued by the rootCA into the signing keystore
Option 6: List all the entries in the signing keystore
Option 7: Export the Signing PKC from the signing keystore
Option 9: Diagnosis mode: SAWS will create a new log file and check old log files, then close the
new log file. This is for diagnosis purposes.
Please input your choice (1, 2, 3, 4, 5, 6, 7 or 9) or any other input to stop:
For the first time running, you need to input “1” for option 1, and then press the return key.
The first SAWS administrator will be prompted to input data for the certificate in
the encryption keystore and his password share. Please note that the pop-up windows may be
behind (i.e. hidden by) your current command window in your system, in case that you are using the
graphical callback handler.
Subsequently, another (N – 1) SAWS administrators are required to input their
password shares into the password input windows separately – N is the number
present on the field “numberOfEncPasswordShares” in the configuration file
Page 133
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
(saws.xml). Then the SAWS server will generate the encryption keystore and give the following
results on the screen:
/home/sawsTestingPack/encryption.keystore has been created successfully.
6.1.1.89.2 Generate the signing keystore
In the directory </home/sawsTestingPack/releasePack >, run the following command:
$JAVA_HOME/bin/java -cp soap.jar:saws.jar:log4j.jar issrg.SAWS.SAWSServer
This time you need to select option 2 by inputting number “2”. SAWS administrators are required to
input the data for the certificate to be created on signing keystore and their password shares
separately. Please note that the password for the signing keystore can be different from the
encryption keystore.
Then SAWS will generate the signing keystore and display the following result on the screen:
/home/sawsTestingPack/signing.keystore has been created successfully.
If you can have a Root CA to provide a public key certificate service for you, then proceed with the
following steps; otherwise, you can ignore the following (1.3.1.3), (1.3.1.4), (1.3.1.5) for testing
purposes.
6.1.1.89.3
Output a public key certificate request file from the signing
keystore
In the directory </home/sawsTestingPack/releasePack >, run the following command:
$JAVAHOME/bin/java -cp soap.jar:saws.jar:log4j.jar issrg.SAWS.SAWSServer
By selecting option 4, after inputting the password shares to the signing keystore, a SAWS signing
key pair PKC request file will be generated, and the following message will be displayed on the
screen. The SAWS signing keypair PKC request file sawsRequest.csr has been created
successfully in the current directory. Please pass it to a RootCA for issuing a PKC.
6.1.1.89.4 Import the Root CA public key certificate into the signing keystore
Now you need to import the Root CA public key certificate into the signing keystore. In the directory
</home/sawsTestingPack/releasePack >, run the following command:
$JAVA_HOME/bin/java -cp soap.jar:saws.jar:log4j.jar issrg.SAWS.SAWSServer
Page 134
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
By selecting option 3, after inputting the password shares to the signing keystore, the RootCA
specified in the configuration file saws.xml (i.e.
rootCA="/home/sawsServer/rootca.crt") will be imported into the signing keystore.
6.1.1.89.5 Import the signing public key certificate into the signing keystore
Suppose you have got the signing key pair public key certificate saws.crt from the
Root CA. Copy it to </home/sawsTestingPack/releasePack >. In the directory
</home/sawsTestingPack/releasePack >, run the following command:
$JAVAHOME/bin/java -cp soap.jar:saws.jar:log4j.jar issrg.SAWS.SAWSServer
By selecting option 5, after inputting the password shares to the signing keystore, you will be
asked to input the public key certificate file “saws.crt”, and then the SAWS signing key pair
PKC will be imported into the signing keystore.
6.1.1.89.6 Export the Signing PKC from the signing keystore
In the directory </home/sawsTestingPack/releasePack >, run the following command:
$JAVA_HOME/bin/java -cp soap.jar:saws.jar:log4j.jar issrg.SAWS.SAWSServer
By selecting option 7, after inputting the password shares to the signing keystore, you will see the
following prompt message on the screen:
The SAWS Signing PKC file sawsSigningPKC.crt in the current directory has been exported
successfully.
For those who do not have a Certificate Authority (CA) sign the certificate request generated on
(1.2.1.3) above, the sawsSigningPKC.crt certificate can be used as the root CA certificate and
signing certificate as well, since it is self-signed. To use the exported certificate as root CA, the field
rootCA
on
the
configuration
file
saws.xml
must
be
set
as
rootCA="/home/sawsServer/sawsSigningPKC.crt" (change the path for the certificate file used on
your environment), then execute (1.3.1.4). For those who have executed (5), the exported certificate
will be the same one imported on that step.
6.1.1.89.7 Display all entries in the signing keystore
To make sure all the entries are correctly imported into the signing keystore, you can list all entries
in the signing keystore by using option 6.
In the directory </home/sawsTestingPack/releasePack >, run the following command:
Page 135
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
$JAVA_HOME/bin/java -cp soap.jar:saws.jar:log4j.jar issrg.SAWS.SAWSServer
By selecting option 6, after inputting the password shares to the signing keystore, you will see the
contents of the signing keystore.
6.1.1.89.8 Diagnose the SAWS log files
To diagnose the SAWS log files, you can use the SAWS diagnostic mode.
In the directory </home/sawsTestingPack/releasePack >, run the following command:
$JAVA_HOME/bin/java -cp soap.jar:saws.jar:log4j.jar issrg.SAWS.SAWSServer
By selecting option 9, after inputting the password shares to the signing keystore in the pop-up
windows, SAWS will try to check the existing log files.
You can choose to ignore the old log files, check the log files one by one, or check all the log
files. If any error is found by SAWS, detailed information about the error will be displayed on
the screen. If the error can be corrected, e.g. the error was caused by a computer crash and the
log file is only incomplete rather than corrupted, SAWS will try to complete the log file by
signing it, but you will still have full control over the diagnosis process as what it should do.
6.1.1.90 SAWS startup
The following steps will assume that “issrg.SAWS.callback.SAWSGUICallbackHandler” is set as the
callback handler in the configuration file saws.xml. Now restart Tomcat to load the SAWS server into
the Axis SOAP application server. The SAWS server will be working as a standard SOAP service on
this machine. To make sure that SAWS is correctly installed in Tomcat, you need to go through the
example section to test it.
When the first SAWS client call arrives, the SAWS server will be activated by the
AXIS server, then the SAWS administrators will be prompted to input their password shares in the
password input windows. If you didn‟t perform Step (1.3.1.3), (1.3.1.4), (1.3.1.5) in the above, then
you will see the follow message.
Page 136
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
You can simply choose Option 2 to continue for testing purposes.
Then for the first-time running, the following window will display:
Choose option 1: “Create Trusted Location”, then you will see the following confirmation window:
After you click “OK” in this window, the SAWS server will start to record log messages from SAWS
clients into its log file. If it is not the first time you have started SAWS, SAWS will find old log files
and display the following message:
You can choose to ignore the old log files, check the log files one by one, or check all the log files.
After all the initialization process is finished, SAWS will ask you to continue or stop. If you choose to
continue, then SAWS will be able to record client log records.
Page 137
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.91 The SAWS Viewing Tool
You can use the SAWS Viewing Tool to view the log files recorded by the SAWS server. In the
directory </home/sawsTestingPack/releasePack >, run the following command:
$JAVA_HOME/bin/java -cp saws.jar:log4j.jar issrg.SAWS.sawsVT
The main interface of the SAWS VT will be displayed as follows.
After selecting a log file by clicking the “Choose Log File …” button, then click the
“Check log” button, you will be prompted to input the password for the VT p12 key file vt.p12.
After you input the password “changeit” for this VT p12 file, the digital signature checking results for
this log file will be displayed in the window.
Page 138
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
If a log file is corrupted, then the SAWS VT will display an error message e.g. “This log file is not
valid”. Then you need to use the SAWS Diagnosis
Mode – Option 9 of the SAWS command line working mode, to further diagnose this log file
.
All the log files generated by SAWS are chained backward to the previous log files. You can also
choose the “Check Log Chain” option to check all the log files chained by this log file. You can also
choose the “View Certificate From Log” to view the public key certificate of the SAWS server that
created this log file.
In the help menu, you can choose “About” and “Help” submenus to see the following two windows.
Page 139
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.92 The use of JSATS
6.1.1.92.1
Initialise JSATS
You can initialize JSATS for the first time for your Java application by exactly the same steps as
listed in the section User‟s guide.
Developer's Guide
6.1.1.93 Invoke SAWS
Any application can access SAWS as a SOAP server via a standard web service interface. The
WSDL file for the SAWS web service interface is /home/sawsTestingPack/releasePack /saws.wsdl.
In order to find out how to invoke a standard web service on the Internet, please refer to
http://www.webservices.org. We also provide a sample Java SAWS client application
/home/sawsTestingPack/releasePack /sawsSOAPClient.java in the SAWS package for your
reference.
6.1.1.94 Invoke JSATS
The following code shows how to invoke SAWS in your Java application, how to read log records
from and write log records to the SAWS secure audit trial. Note that
saws.xml must be in your Java application current directory.
import issrg.SAWS.*;
….
SAWSServer sw = new SAWSServer(1);
//Now the SAWS server has been initialized. Then you can read all the old log //records in the SAWS
audit trail as follows:
Vector v = null;
while ( (v = sw.sawsReadOneLogFile()) != null) {
Page 140
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
// here is an example to show how to read all log records from the secure audit //trail.
int size = v.size();
for (int i = 0; i<size; ++i) {
RecordBlock rb = (RecordBlock)v.get(i);
byte userID = rb.getUserID();
byte[] userRecord = rb.getRecord();
//You can do something with the client log message here
}
}
//Note the RecordBlock rb is a log record, which contains a client binary record //and the
corresponding user ID. All the reading and verifying work are all done //internally by the
SAWSServer sw.
//Now you can start recording test records as follows.
sw.sawsStart();
// here you can record more log records as needed.
RecordStatus rs = sw.sendLogRecord("This is a test.".getBytes());
//The RecordStatus object contains the status of the operation
//(0 for Success or -1 for Fail); and the sequence number of the record
//(if success) or the error code (if fail).
sw.closeLog();
6.1.1.95 API Documentation
The
Java
Doc
of
SAWS
can
be
https://svn.infsec.ethz.ch/trustcom/PartnerInternal/UoK/pub/SAWS/javadoc
found
at
6.1.1.96 Example
To make sure SAWS is correctly installed in your system, you can go through the following
acceptance tests here.
Page 141
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.97 SAWS API test
To copy the SAWS Java files in your system.
To make sure SAWSInterface = "api" is in saws.xml.
To initialise SAWS for the first time. (Please note for testing purposes, you can ignore Step (3), (4)
and (5) at the moment.)
In the directory </home/sawsTestingPack/releasePack>, compile sawsAPITest.java first, then run
the following command:
$JAVA_HOME/bin/java -cp .:$AXISCLASSPATH:soap.jar:saws.jar:log4j.jar
sawsAPITest
In Windows, the command is:
%JAVA_HOME%\bin\java -cp .;%AXISCLASSPATH%;soap.jar;saws.jar;log4j.jar
sawsAPITest
By inputting the passwords for the SAWS encryption keystore and signing keystore, log files will be
verified, and log record contents will be displayed on screen, then a sample test log record will be
generated and a new log file will be created. Repeat Step 4 for several times. If you can read the log
record contents as “This is a test” on the screen correctly, then you can be sure that SAWS has
been correctly installed on your machine. To control the debug information output on the screen, you
can set debugLevel = "0" to "5" in saws.xml.
6.1.1.98 SAWS Web service test
To follow the Installation steps for the SAWS server on your computer.
To make sure the UserInfo section in saws.xml be
<UserInfo
userID="3"
userDN="cn=soap, ou=cs, o=kent, l=can, st=eng, c=uk" />
To make sure saws.jar, soap.jar, servlet-2_3-fcs-classfiles.jar and axis.jar
are NOT in the directory <$JAVA_HOME/jre/lib/ext>.
To initialise SAWS on your machine.
In /home/sawsTestingPack/releasePack/soapClientDemo.properties, if your path name is set
differently from this cookbook, then you need to modify the following two lines in the properties file to
refer to the correct path:
truststore = /home/sawsTestingPack/releasePack /soapclient.keystore
keystore = /home/sawsTestingPack/releasePack /soapclient.keystore
Page 142
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
In Windows, the properties would be:
truststore = c:\home\sawsTestingPack\releasePack\soapclient.keystore
keystore = c:\home\sawsTestingPack\ releasePack\soapclient.keystore
Then run sawssoapClientDemo:
$JAVA_HOME/bin/java -classpath .:$AXISCLASSPATH:soap.jar
sawssoapClientDemo
In Windows, the command is:
%JAVA_HOME%\bin\java -classpath .;%AXISCLASSPATH%;soap.jar
sawssoapClientDemo
A sample log record will thus be sent to the SAWS server deployed by you above.
6.1.1.99 Input file used by SAWSFileCallbackHandler
Here we present an example of the input file used by the callback handler
SAWSFileCallbackHandler. Lines that begin with „#‟ represent comments in the file to help
understanding the inputs. The key words that preceed the chosen values are case sensitive and
MUST be the same as shown bellow.
#Error when initializing the specified callback handler.
#[1] continue using the default callback handler; [2] stop
CallbackHandlerError=2
#The specified Public Key Certificate could not be found. The corresponding private
#key will not be able to read log files if they are encrypted.
#[1] continue; [2] stop
MissingPKCFile=2
#The Public Key could not be read from the certificate. The corresponding private
#key will not be able to read log files if they are encrypted.
#[1] continue; [2] stop
ReadingPKWarning=2
#Confirm first time SAWS initialized
#[1] ok; [2] no-abort
FirstTimeInitialization=1
#SAWS has finished the initialization process. Start recording logs?
#[1] yes; [2] no
Page 143
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
StartRecordingLogs=1
#The specified trusted location could not be found.
#[1] Create; [2] Stop; [3] Rebuild
TrustedLocationNotFound=1
#Data in trusted location is corrupted.
#[1] Stop; [2] Rebuild
TrustedLocationDataCorruption=1
#The current verifying log could not be found.
#[1] stop; [2] continue
MissingCurrentVerifyingLogFile=1
#SAWS identified an existing log file. Do you want to check it?
#[1] No; [2] check it; [3] check all
CheckExistingLogFile=3
#The last sequence number is different from the one stored in the trusted location.
#[1] Stop; [2] Continue after Tampering; [3] Continue after crash
SequenceNumberDifferentFromTCB=1
# The accumulated hash is different from the one stored in the trusted location.
#[1] Stop; [2] Continue after Tampering; [3] Continue after crash
AccHashDifferentFromTCB=1
#An error was found in the log file that could not be recovered.
#[1] Stop; [2] Continue after Tampering; [3] Continue after crash
CannotRecoverLogFile=1
#Error when reading log file.
#[1] Stop; [2] Recover; [3] Ignore
ReadingLogFileError=2
#When attempting to create the encryption keystore SAWS identified an existing one.
#[1] Create new; [2] Stop
ExistingEncKeystore=1
#When attempting to create the signing keystore SAWS identified an existing one.
#[1] Create new; [2] Stop
ExistingSigKeystore=1
#Input the path for the SAWS PKC file
SAWSPKCFileName=sawsSigningPKC.crt
#Password for the admin 1 of 3 of the encryption keystore
encryptionPassword1of3=test
#Password for the admin 2 of 3 of the encryption keystore
encryptionPassword2of3=test
#Password for the admin 3 of 3 of the encryption keystore
Page 144
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
encryptionPassword3of3=test
#Password for the admin 1 of 3 of the signing keystore
signingPassword1of3=test
#Password for the admin 2 of 3 of the signing keystore
signingPassword2of3=test
#Password for the admin 3 of 3 of the signing keystore
signingPassword3of3=test
#Data about the encryption certificate
#Validity date in the format DDMMYYYY
EncCertValidity=01042008
#Common Name
EncCertCN=Encryption Certificate
#Organizational Unit Name
EncCertOU=ISSRG
#Organization Name
EncCertO=UKC
#Locality
EncCertL=Canterbury
#State or Province
EncCertS=Kent
#Two-letters Country code
EncCertC=UK
#Encryption Algorithm (Only RSA is supported)
EncCertAlgorithm=RSA
#Key size: 1024, 2048, 3072, 4096
EncCertKeySize=1024
#Data about the signing certificate
#Validity date in the format DDMMYYYY
SigCertValidity=01042008
#Common Name
SigCertCN=Signing Certificate
#Organizational Unit Name
SigCertOU=ISSRG
#Organization Name
SigCertO=UKC
#Locality
SigCertL=Canterbury
#State or Province
Page 145
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
SigCertS=Kent
#Two-letters Country code
SigCertC=UK
#Signing Algorithm (RSA and DSA are supported)
SigCertAlgorithm=DSA
#Key size: 512, 640, 768, 896, 1024
SigCertKeySize=512
Security Token Service (Microsoft)
Installation Guide
In the TrustCoM environment, we expect that every VO partner hosts an own STS. That STS is fully
owned and managed by that partner.
The STS ships in three installation packages:



STS Base Component (Server component)
TrustCoM STS Module (Server component)
STS Management Tools (Server and client tools)
On the STS machine, all three packages should be installed. In addition, the system administrator
should install the “STS Management Tools” on his own management machine.
6.1.1.100 Package Contents
Description of the elements of the package
Name
Type
Description
STS Base
Component
Windows MSI
Installer
The empty STS hosting environment, which needs to be
deployed to the machine that should run the STS.
TrustCoM STS
Module
Windows MSI
Installer
The TrustCoM specific modules that need to be installed
on the machine that runs the STS.
STS
Management
Tools
Windows MSI
Installer
Contains different utilities which are necessary to
configure and manage the STS. It is recommended to
install these tools both on the machine that has the “STS
Base Component”, as well as on a systems
administrator‟s machine.
These tools are included in the installer:




The “STS Configuration File Editor” which can be
used to configure an installed STS on the local
machine.
The “EMIC Certificate Inspector”, a tool which
helps displaying and configuring X.509
certificates and access control permissions on a
Windows machine.
A “business card creation application” for
creating business card files that convey
cryptographic information about a partner STS.
The “STS Management Client” in the application
to remotely connect to an STS‟s management
interface, and to administrate federations etc.
Page 146
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.101 Requirements and dependencies
6.1.1.101.1 Operating system
The STS can be installed under Microsoft Windows. It has been successfully tested under the
following versions of the operating system:



Microsoft Windows XP Professional (with IIS 5)
Microsoft Windows 2003 Server (with IIS 6)
Microsoft Windows Vista Business and Ultimate (with IIS 7)
The security token service is typically installed as an ASP.NET application and hosted inside IIS.
6.1.1.101.2 Additional packages
You must have the following components installed:



Microsoft Internet Information Server (IIS)
Microsoft .NET 2.0
Microsoft Web Service Enhancements 3.0
.NET 2.0 is available through Windows Update or at
http://www.microsoft.com/downloads/details.aspx?FamilyID=0856eacb-4362-4b0d-8eddaab15c5e04f5.
WSE 3.0 can be downloaded at http://msdn2.microsoft.com/en-us/webservices/aa740663.aspx.
You can find the documentation for WSE 3.0 here: http://msdn.microsoft.com/library/?url=/library/enus/wse3.0/html/6f194c77-6fe3-42a2-88ee-0599d4b4779c.asp?frame=true
6.1.1.101.3 IIS Installation under Windows Vista
Before installing the STS under Windows Vista, please make sure that the following IIS features are
installed:
Page 147
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.102 Cryptographic key requirements
In order to function properly, the STS needs cryptographic keys, in particular for protecting the
SOAP communication with the STS and for signing/decrypting security tokens. In the concrete
implementation, these cryptographic keys must be in the form of X.509 certificates.
Please note that the installer does not contain any test or dummy certificates. When you install the
STS, you need to make sure that you have own certificates. You may acquire certificates from a
public certification authority (CA), from your company-internal CA, or you may generate test
certificates with tools such as makecert.exe from the Windows SDK or OpenSSL / OpenCA.
6.1.1.102.1 Certificate Installation
6.1.1.102.1.1 External guidance
To understand how to install certificates, please refer to your operating system‟s documentation.
Documentation
for
Windows
XP
can
be
found
here:
http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/enus/sag_cmprocsimport.mspx
Page 148
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
To understand how access to certificates can be configured, please refer to the WSE 3.0
documentation
(“X.509
Certificate
Tool”):
http://msdn.microsoft.com/library/enus/wse3.0/html/8e53b7d4-608b-4d16-ad81-47b6a7d63b71.asp
6.1.1.102.1.2
Installation locations
X.509 certificates and the corresponding private key for the STS need to be installed under in the
certificate store with a store location of “Local Computer” and a store name “Personal”.
Typically, a certificate and the corresponding private key are stored in a PKCS#12 container, i.e., a
file with the extension .pfx or .p12.
When installing a PKCS#12 container, use the mmc.exe snapin to add the certificate to the store.




Start mmc.exe
Select the “Certificates” Snap-In
Select “Computer Account”
Import the PKCS#12 file
Page 149
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
WARNING: Please note that a “.cer” certificate files does not contain a private key, so when you
only import the certificate, the STS will not be able to decrypt requests or sign/issue tokens.
For
detailed
information,
you
may
also
look
in
the
Certificate
How
To:
(http://www.microsoft.com/technet/prodtechnol/windowsserver2003/library/serverhelp/fb037b9f8956-411c-a3e8-ce1dfe37da11.mspx).
6.1.1.102.2 Internal certificates
The STS needs X.509 certificates for two purposes: The first purpose is WS-Security protection of
the SOAP requests and responses when exchanging messages with gateway, policy enforcement
points and management clients.
We call this communications certificate internal certificate, because it is only used for
communications inside the corporate trust boundary; all involved components, i.e., STS, gateway,
PEPs and management clients, are operated by the same partner. This allows the use of certificates
which root CA may not be recognized outside the corporate boundary.
During the installation of the STS, the installer will ask which certificate to use for that protection.
For further information, please see “Implementing Message Layer Security with X.509 Certificates in
WSE 3.0”: http://msdn2.microsoft.com/en-us/library/aa480581.aspx
6.1.1.102.3 Public certificates
The second X.509 certificate purpose for the STS is the token issuance process (and maybe
validation) process. The actual token issuance process of the STS is implemented by the “STS
Business Logic Plugin” of the STS, i.e. the “STS Base Component” cannot issue or validate a
security token. Nevertheless, we wanted to provide a default key setting which could be used by
specific plugins, such as the TrustCoM STS Module. Therefore, during installation of the “STS Base
Component”, the installer will ask which certificate to use for that purpose.
We called that certificate the public certificate, because that token issuance certificate will be
exposed and shared with external partners, such as other VO members.
Page 150
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.103 Installation of the STS Base Component
To install the STS Base Component, execute the file
EMIC.SAFe.Installer.STSBaseComponent.msi
6.1.1.103.1 Publicly visible hostname of this machine
The first installation dialog will ask you for the “publicly visible hostname of this machine”. This is the
„official‟ fully-qualified hostname under which this machine is reachable.
The hostname value is stored as an application setting in the web.config file (in the stsUri value),
and is therefore available to all STS modules, and may be used at their discretion. For example, the
TrustCoM-specific token generation modules uses this hostname inside a saml:Assertion/@Issuer
attribute.
6.1.1.103.2 Virtual directory selection
The next installation dialog asks you about the virtual directory of the STS:
Page 151
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
This value will determine in which directory on the server‟s hard drive the STS will be installed, and
under which URL the endpoints will be exposed.
For example, selecting a hostname of “sts.corp.contoso.com” and a virtual directory of “/STS” will
make
the
X.509
WS-Trust
endpoint
of
the
STS
available
under
“http://sts.corp.contoso.com/STS/STSX509.ashx” and will result in an Issuer attribute in the SAML
assertions with a value of “http://sts.corp.contoso.com/STS/STS.ashx”.
6.1.1.103.3 Selecting the certificates
The next installation screen lets you select the certificates to be used (see the earlier sections about
public and internal certificates).
When you install the certificates on the machine before you install the STS, then you can directly
select the appropriate certificates.
Page 152
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
When you want to install the certificates after the STS base component, just click “Close” in the
configuration dialog, install the certificates, and re-start the selection dialog. The corresponding
application is in the STS‟s installation directory, so that you can launch it by hand:
C:\Inetpub\wwwroot\STS\InstallHelper\EMIC.SAFe.STS.ConfigurationUI.exe
The tool writes the values for the certificates into two different files: the STS WSE 3.0 policy file
named „wse3policyCache.config‟, and the STS‟s web.config file. The internal certificate name is
stored in the <serviceToken> sections of the wse3policyCache.config file for different policies, while
both the internal and the public certificate identifier are stored in the web.config file, see the attribute
values


/configuration/appSettings/add[
@key="STSOrganizationInternalSubjectDN"]/@value
/configuration/appSettings/add[
@key="STSExternalTokenSubjectDN"]/@value
6.1.1.103.4 Configuring the communications policies
As a WSE3-based component, the STS supports all WS-Security communications mechanisms
supported by WSE itself. For example, it can protect the SOAP messages WS-Security 1.0, WSSecurity 1.1, WS-SecureConversation, etc. You can select what parts to sign, whether soap:Body
elements should be encrypted, etc.
Our installer does not support changing the installation defaults. When you need to change the
communications policies of the STS, such as switching off encryption or similar things, please edit
the wse3policyCache.config file yourself.
More information on this file and the supported policy assertions can be found under “How to:
Secure a Web Service Using a Policy File”: http://msdn.microsoft.com/library/enus/wse3.0/html/61997a78-c671-4b6d-94cc-1172bad549d5.asp
In addition to that, please refer to the documentation of the respective components, such as the
TrustCoM gateway and TrustCoM policy enforcement points, about their capabilities and security
protocol support.
6.1.1.103.5 STS communications endpoints
The STS has two main web services interfaces, the WS-Trust interface and the management
interface. Clients can communicate with these interfaces using different communications protection
mechanisms. In the default installation, the STS exposes these endpoints:
Page 153
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007


WS-Trust
o STSX509.ashx – Company-internal client and STS using X.509 certificates
o STSKerberos.ashx – Company-internal client and STS using Kerberos
o STS.ashx – An expoint which may be exposed to parties outside the company. For example,
that may be used in scenarios where partners validate security tokens with the issuing STS.
This is not used in the TrustCoM framework.
Management interface
o ManagementX509.ashx – Client and STS using X.509 certificates
o ManagementKerberos.ashx – Client and STS using Kerberos
The implementing classes have hardcoded policy names that refer to each endpoint. To modify an
endpoint‟s communications policy, please refer to the following table:
Endpoint file
Policy name
STS.ashx
STSPolicyPublicEndpoint
STSX509.ashx
STSPolicyX509
STSKerberos.ashx
STSPolicyKerberos
ManagementX509.ashx
ManagementPolicyX509
ManagementKerberos.ashx
ManagementPolicyKerberos
6.1.1.103.6 STS security permission settings
The STS needs access to certain portions of the system. The STS must have read access to the
private keys that correspond to the public and the internal certificate (see section 6.1.1.105.2).
The STS stores the configuration in the file DB/db.xml. The access control list for the DB/ directory
needs to be configured so that the Windows account under which ASP.NET is executed has write
access to that directory.
6.1.1.103.7 Access control to the STS
After installing the STS, the web-services based management interface is protected with a simple
access
control
module.
You
can
configure
that
module
(in
the
assembly
EMIC.SAFe.STS.SimpleAuthorization.dll) with the web.config, in particular with the
/configuration/STSDatabaseConfiguration/ManagementServiceCoreAuthorization section:
<configuration>
<configSections … />
<STSDatabaseConfiguration>
<assemblies … />
<ManagementServiceCoreAuthorization
type="EMIC.SAFe.STS.SimpleAuthorization.SimpleManagementServiceCoreAuthorization,
EMIC.SAFe.STS.SimpleAuthorization, Version=1.1, Culture=neutral, PublicKeyToken=287df21774378f0b">
<SimpleManagementServiceCoreAuthorization xmlns="http://www.microsoft.com/emic/SAFe/Management"
xmlns:cfg="http://www.microsoft.com/emic/SAFe/#STSConfig">
<ManagementUsers>
<cfg:OrganizationInternalID
Page 154
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Type="http://www.w3.org/2000/09/xmldsig#X509SubjectName">CN=EMIC Client</cfg:OrganizationInternalID>
<cfg:OrganizationInternalID Type="http://docs.oasis-open.org/wss/oasis-wss-kerberos-tokenprofile-1.1#GSS_Kerberosv5_AP_REQ">DOMAIN\username</cfg:OrganizationInternalID>
</ManagementUsers>
<ITAdministrators>
<cfg:OrganizationInternalID
Type="http://www.w3.org/2000/09/xmldsig#X509SubjectName">CN=Systems
Administrator</cfg:OrganizationInternalID>
<cfg:OrganizationInternalID Type="http://docs.oasis-open.org/wss/oasis-wss-kerberos-tokenprofile-1.1#GSS_Kerberosv5_AP_REQ">DOMAIN\Admin</cfg:OrganizationInternalID>
</ITAdministrators>
</SimpleManagementServiceCoreAuthorization>
</ManagementServiceCoreAuthorization>
</STSDatabaseConfiguration>
...
</configuration>
In the default installation, the simple authorization module groups users into “management users”
and “IT administrators” (see example above). These are listed in the <ManagementUsers> and
<ITAdministrators> elements.
Each <cfg:OrganizationInternalID> element has a Type attribute of value Kerberos or X.509,
and the text child that names the user‟s ID.

A “management user” is a user who can create new “federations” in the STS. Each federation is
“owned” by the management user who created the federation. Each “owner” can manage „his‟
federations.

An “IT administrator” can see and inspect all federations in the STS.
In the TrustCoM setup, make sure that the certificate of the gateway is listed in the
<ManagementUsers> section.
6.1.1.104 Installation of the TrustCoM STS Module
To install the TrustCoM STS Module, run the EMIC.TrustCoM.STSModule.msi installer. Make sure
that the STS Base Component is already installed, before installing the TrustCoM STS module.
If the STS Base Component is missing, the following error message will appear:
Page 155
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The TrustCoM-specific module installer will not ask for an installation location. It will determine the
STS‟s existing location, copy the assemblies into the bin/ folder of the STS, and register the
assemblies in the web.config file:
Each .NET plug-in assembly that contains an extension such as a claim or a plug-in module for the
STS must be located in the STS‟s bin/ folder. In addition, it needs to be registered in the web.config
file
under
/configuration/STSDatabaseConfiguration
as
shown
above.
The
InstallHelper\EMIC.SAFe.STS.ConfigurationUI.exe application can be used to register plug-in
assemblies in a more convenient way.
6.1.1.105 Installation of the STS Management Tools
The
installer
for
the
“STS
Management
Tools”
is
contained
in
the
EMIC.SAFe.ManagementTools.msi file. There are no special things to consider during the
installation phase.
Page 156
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
These tools are included in the installer:




The “STS Configuration File Editor” which can be used to configure an installed STS on the local
machine.
The “EMIC Certificate Inspector”, a tool which helps displaying and configuring X.509 certificates and
access control permissions on a Windows machine.
A “business card creation application” for creating business card files that convey cryptographic
information about a partner STS.
The “STS Management Client” in the application to remotely connect to an STS‟s management
interface, and to administrate federations etc.
6.1.1.105.1 The “STS Configuration File Editor”
The “STS Configuration File Editor” is an application which opens an installed STS configuration and
allows you to easily configure the certificates to be used for token issuance (public cert) and
communications protection (internal cert), as well as the available plugins etc. The same tool is also
contained in each STS‟s installation in the InstallHelper/ folder.
6.1.1.105.2 The “Certificate Inspector”
The “Certificate Inspector” is a small utility which comes handy when inspecting what certificates are
installed on the local machine, and what the access control permissions on the private key are.
When you install X.509 certificates for the STS, the public key portion of the certificate is installed
machine-wide, so that all local processes may see these. The private key is stored in a file in the
local file system, and you need to set the access control for that key appropriately, so that the
ASP.NET worker process in IIS has read access to the private key.
Please note that the default local user account which executes the ASP.NET worker process is
different on the different IIS installations:
OS Version
Local user account ID
Page 157
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Windows XP Professional (IIS 5)
“ASPNET”
Windows 2003 Server (IIS 6)
“NETWORK SERVICE” (with space)
Windows Vista (IIS 7)
“NETWORKSERVICE”
space)
(without
You may use the “Certificate Inspector” to easily select certificates and open the corresponding
private key‟s file system properties (“View private key properties” button).
Another convenience mechanism is the “Crypto value search” field: When opening WSE3 soap
traces in a text editor, we often see that an encrypted key is addressed to or a signature is created
from an X.509 certificate where we only know the X509SubjectKeyIdentifier:
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier
ValueType="...#X509SubjectKeyIdentifier"
EncodingType="...#Base64Binary">
oRvItSyKEmdGsw7F5VTe/kXTe8Y=
</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</KeyInfo>
That value allows a quick search to find out which installed certificate belongs to that identifier:
Page 158
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
This application will soon
http://wcf.netfx3.com/files/.
be
also
available
as
a
WCF
community
sample
under
6.1.1.105.3 The “Business Card Creator”
The “Business Card Creator” lets you easily wrap an X.509 Certificate in a business card data
structure, i.e., the file format that we use in TrustCoM to wrap an X.509 certificate and a UDDI
business entity key in a single file:
Page 159
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.105.4 “STS Management Client”
The “STS Management Client” is the graphical management utility which allows an STS
Administrator to connect to the STS and administrate the component. We describe the functionality
of the STS Management Client in the “User‟s Guide” section.
After installation of the binaries, please edit the wse3policyCache.config file of the STS Management
Client and ensure that the policies refer to the actual key material that you use in your company‟s
deployment. In particular, make sure that the policy you use to connect to your STS uses the STS‟
internal certificate as <serviceToken>, and that the token is installed on the STS Administrator‟s
machine.
The easiest way to edit the file and create appropriate policy entries is to use the “Configuration
Tool”
from
the
“Microsoft
WSE
3.0”
program
group.
Open
the
EMIC.SAFe.STSManagement.ClientApp.exe.config in the “Configuration Tool”, and in the “Policy”
tab, you can add a policy that matches your deployment.
6.1.1.106 Frequently asked questions and common problems
Q:
What is the difference between the “Public certificates” and “Internal certificates”?
A:
The public one is used for token signing or decryption. The internal one is necessary for WS-Security
protection of organization-internal WS-Trust and STS Management communications
Q:
The STS responds very slow. It was fast when I used it in the beginning, but now it‟s getting slower
each time. Why is that?
A:
You may have tracing switched on. Look into your STS‟ web.config file whether the
/configuration/microsoft.web.services3/diagnostics/ trace/@enabled attribute is true. In
that case, the indicated log files grow with each request, and each new log message forces an
expensive XML parsing/serialization operation. You should switch off WSE3 message logging in the
operational phase of the STS.
Page 160
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Q:
Why does the STS not create log files? I turned on logging as described above.
A:
Make sure that the directory in which the log files would be created is writable for the local user
account executing the ASP.NET worker process.
Q:
Why do I get a SOAP fault message like “Unable to unwrap a symmetric key using the private key of
an X.509 certificate…” or “Error occurred while decoding OAEP padding”?
A:
Check that you actually installed the certificate AND the private key (both in a PKCS#12 container, i.e.,
a .p12 or .pfx file). When you only install a .cer file, you missed the private key portion.
Also check that the user account running ASP.NET has read access to the private key file
corresponding to the certificate. See section 6.1.1.105.2 on the certificate inspector tool how to grant
the appropriate read permissions.
Page 161
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
User‟s Guide
6.1.1.107 Management in the TrustCoM deployment
In the TrustCoM deployment, each VO partner has a gateway component and an STS. When the
VO Manager initiates the VO setup, the VO Manager sends setup messages to each VO partner‟s
gateway component. The gateway translates these VO setup calls into respective management
operations on the STS.
So in a typical TrustCoM setup, there is no immediate need to manage the STS directly using the
graphical management client. Nevertheless, this user guide explains how to use the graphical “STS
Management Client” to inspect the STS‟ configuration and how to modify it.
6.1.1.108 Management client GUI module configuration
The management client supports pluggable modules in a similar way as the STS does, i.e., for each
pluggable module which is installed on the STS and which you want to manage, the client needs a
corresponding UI module. For example, the “Manual partner list” module consists of these
components:




EMIC.SAFe.Providers.ManualPartnerList.dll – The STS Module which contains the business
functionality
EMIC.SAFe.Providers.ManualPartnerList.UI.dll – The corresponding GUI module which provides the
display functionality for the management client
EMIC.SAFe.Providers.ManualPartnerList.Proxy.dll – A proxy module which offers a .NET class to
conveniently communicate programmatically with the module
EMIC.SAFe.Providers.ManualPartnerList.Common.dll – Shared data types which are required both
by STS module and client proxy
So the STS needs these assemblies:


EMIC.SAFe.Providers.ManualPartnerList.dll
EMIC.SAFe.Providers.ManualPartnerList.Common.dll
Page 162
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The management client needs these assemblies:



EMIC.SAFe.Providers.ManualPartnerList.UI.dll
EMIC.SAFe.Providers.ManualPartnerList.Proxy.dll
EMIC.SAFe.Providers.ManualPartnerList.Common.dll
In addition, both the STS and the management client need the respective assemblies registered in
their configuration:
The STS has this configuration in its web.config file:
<configuration>
...
<STSDatabaseConfiguration>
...
<assemblies>
<add assembly="EMIC.SAFe.Providers.ManualPartnerList, ..." />
<add assembly="EMIC.SAFe.Providers.ManualPartnerList.Common, ..." />
</assemblies>
</STSDatabaseConfiguration>
...
</configuration>
The
STS
Management
client
has
EMIC.SAFe.STSManagement.ClientApp.exe.config file:
this
configuration
in
<configuration>
...
<STSDatabaseConfiguration>
...
<assemblies>
<add assembly="EMIC.SAFe.Providers.ManualPartnerList.UI.dll, ..." />
<add assembly="EMIC.SAFe.Providers.ManualPartnerList.Proxy.dll, ..." />
<add assembly="EMIC.SAFe.Providers.ManualPartnerList.Common, ..." />
</assemblies>
</STSDatabaseConfiguration>
...
</configuration>
Page 163
its
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.109 Connect to the STS
After starting the management client, click on the “Connect” button (
):
In the “Select Management Service” dialog, please enter the URL of the STS Management endpoint
you want to connect to and select the policy you want to use. See section 6.1.1.103.5 about the
possible endpoints, and see section 6.1.1.103.4 about how the policies need to look like.
After being connected to the STS, the client lists the federations that you have view permissions on.
Page 164
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.110 Creating a new federation
To create a new federation, click on the “New Federation” button ( ). In the federation creation
dialog, please select the following profile:





The “Federation Selector” type needs to be the FederationUuidSelector
The “STS Business Logic” needs to be the “SAFe STS business logic”
The “Partner Provider” is the “Manually-established partner list”
The “Client-claims Provider” is the “Claims for real users” provider
The “Service-access and claims-validation” provider needs to be the “TrustCoM claims validation”
provider
You can select the federation‟s friendly name arbitrarily.
The UUID needs to be equal to the virtual organization‟s identifier (VO-ID).
Page 165
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
In order to activate the federation, you need to tick the “Enabled” checkbox on the federation‟s
overview page and “Apply” the change.
6.1.1.111 STS modules
The following sections describe the different modules that we use in the TrustCoM configuration.
6.1.1.111.1 The “SAFe STS business logic” STS module
The “SAFe STS business logic” module (identified by a module namespace of
“http://www.microsoft.com/emic/SAFe/” and a local name of “SAFeSTS” issues and processes
SAML 1.1 assertions compliant to the TrustCoM token profile.
The module offers the following configuration choices:
Page 166
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007





Enabling “Embed Action in Token” makes sure that when a client requests a token, the client‟s
wsa:Action will be embedded in the security token. This means that the token can only be used for
invoking that particular action on the service. If that feature is disabled, the token can be re-used for
arbitrary actions.
Enabling “Require Action in Token” makes sure that each validated token has an embedded
wsa:Action, and that the token is used for the appropriate action.
Enabling “Embed Service EPR in Token” makes sure that when a client requests a token, the
service‟s address will be embedded in the security token. This means that the token can only be
used for invoking that particular service. If that feature is disabled, the token can be re-used for
invoking arbitrary services at the VO partner.
Enabling “Require Service EPR in Token” makes sure that each validated token has an embedded
wsa:Action, and that the token is used for the appropriate action.
The “Token Life Time” is the number in seconds on how long issued tokens will be valid. The value
“-1” denotes no expiry here.
6.1.1.112 The “Manually-established partner list” STS module
The “manually established partner list” is a partner provider in which all VO members are configured
individually.
In a first step, you need to upload your own business card, i.e. the business card under which the
other VO partners know you. You can upload your own business card by right-clicking on the red
area in the “Internal Partner (Required)” and selecting the “Add Partner” menu.
In the “Open” dialog, select the business card file you plan to use:
Page 167
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
In this example, the certificate with the name “CN=Security Token Service StoragePisa (SP) Storage, O=StoragePisa (SP) - Storage” would be used by the STS for issuing security tokens.
After defining your own business card, you can now add other VO partners to the lower “External
Partners” list:
In the example above, the VO consist of the VO partners: We ourselves are “Storage Pisa”, and
we‟re working together with “ConsEng – Plane Constructor” and “AvioSystems – Manager”.
Page 168
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.113 The “Claims for real users” STS module
The “Claims for real users” is a client claims provider in which every client or service which may
request security tokens must be listed individually.
To add an employee to a federation, i.e. to configure the STS so that this employee can request
security tokens for that virtual organization, you must create an entry for that employee by rightclicking in the blank area:
In the “Add User” dialog, please select the authentication mechanisms that the employee will use
(the STS module supports Kerberos, username/password and X.509), and provide the domain user
name (in case of Kerberos), or the certificate‟s subject name:
Now the user is added to the federation‟s configuration, but does not yet have any claims
associated.
Page 169
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Double-click on the user, right-click in the claims-area and select the “Add Claim” entry:
In TrustCoM, we use XACML-attributes as claims. These attributes have the following form:
<Attribute
AttributeId="http://www.eu-trustcom.com/XACML/Role"
DataType="http://www.w3.org/2001/XMLSchema#string"
xmlns="urn:oasis:names:tc:xacml:1.0:context">
<AttributeValue>Engineer</AttributeValue>
</Attribute>
You now paste that raw XML into the “Add Claim” dialog:
Page 170
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
After clicking the “OK” button, you see the new claim showing up in the user‟s claims:
6.1.1.114 The “TrustCoM pure claims validation” STS module
The “TrustCoM pure claims validation” is a service-access and token- and claims-validation provider
in which every service which is associated with the virtual organization must be listed individually.
To add an employee to a federation, i.e. to configure the STS so that this employee can request
security tokens for that virtual organization, you must create an entry for that employee by rightclicking in the blank area:
Page 171
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Then types in the service‟s URL, and select the certificate file that corresponds to the service‟s PEP.
After that step, the service‟s PEP shows up in the list.
Page 172
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Developer's Guide
6.1.1.115 STS Design overview
The STS has two interfaces: The WS-Trust interface and the management interface. The next
section describes the operational model of the STS during token issuance.
6.1.1.115.1 WS-Trust operations model
When a client requests token issuance or validation from the STS, the STS has to determine
whether a token can be issued or validated in the context of the client‟s request. In our model, the
STS database must contain a federation that matches the client‟s request. If the STS database does
not contain a matching federation, the STS sends a fault message back to the requestor.
Each federation in the STS database has an associated „federation selector‟. A federation selector is
a mechanism to map an RST message (or a management operation) to a federation. In a simple
case, the federation selector could contain a unique ID such as the <fed:FederationID> element.
After selecting the matching federation configuration, the STS instantiates the different required
modules for token creation or validation. The STS instantiates the „STS business logic‟ provider and
loads it with the respective configuration. In addition, the STS instantiates the three federationspecific provider modules, namely the „federation partner‟ provider, the „client-claims‟ provider and
the „service-access and claims-validation‟ provider. Each of these modules may have a federationspecific configuration, which is loaded into the module.
STS Database
....
Federation
Federation
Federation
Federation
selector
configure
Owner
configure
instantiate
instantiate
use
Partners
Token types,
life times,
etc
read
WS-Trust
Issue/Validate
STS
business
logic
use
use
membership
& constraints
Client
claims
Claims for
issuance
Service
access
ACLs and claims
mappings
After the STS has instantiated the different provider modules, the STS invokes the WS-Trust Issue
or Validate operation on the STS business logic provider.
For token issuance, the STS primarily relies two modules: The „federation-partner provider‟ and the
„client-claims provider‟. For token validation (or service-side access control decisions), the STS
relies on the „federation-partner provider‟ and the „service-access and claims-validation provider‟.
Page 173
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.115.2 Federation-partner provider
A „federation-partner provider‟ is a component that allows the STS to retrieve federation-membership
information about another organization. Such a provider can answer questions such as “Is Contoso
part of the federation?” or “What organizations are part of the federation”. The „federation-partner
provider‟ provides endpoint references from partner STSs, as well as the partner‟s STS‟s security
tokens.
In addition, a „federation-partner provider‟ may supply potential constraints about a federation
partner. Such a constraint could be a list of claim templates for a given partner. Such a „claim
template‟ is a mechanism to populate the value space for claims. A „claims template‟ enables
scenarios such as “In federation xyz, Contoso can issue „Role==Researcher‟ claims for their
employees, but we do not accept „Role==Financial Auditor‟ claims”. In SAFe, we call such
constraints „claims-issuer policy filter‟.
6.1.1.115.3 Client-claims provider
A „client-claims provider‟ provides a set of claims (for a given client) to the STS during the WS-Trust
token issuance process. Such a component can determine the set of claims using different
mechanisms. It may be based on AD group membership or it may contain a list of users and their
associated claims, etc. Such a „client-claims provider‟ component MAY respect the WS-Privacy
settings communicated by the client. Section 6.1.1.124 lists some example implementations.
6.1.1.115.4 Service-access and claims-validation provider
A „service-access and claims-validation provider‟ is a component that the STS (running as
authorization service) needs during the token validation process. Such a provider receives both the
cross-organizational security token from the requestor, as well as the details what service is invoked.
These service-details include the service‟s organization-internal security token, the service‟s EPR
and the SOAP wsa:Action value.
One example for such a „service-access and claims-validation‟ provider could specify „claimsrequirements policies‟ for different SOAP endpoints and actions. For example, it could specify that in
order to accept a security token a given endpoint/action, the token must contain a „Researcher‟ role
claim. Section 6.1.1.125 lists some example implementations.
6.1.1.116 Management model
In order to be able to manage a set of pluggable modules, we decided to split the STS management
interface into two parts: a set of „core‟ management methods and a single „Manage()‟ method which
dispatches management requests to dynamically selected modules.
Page 174
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The core management methods e.g. include operations for creating new federations from given
specifications, for temporarily disabling or enabling federations or inspecting the configuration of
existing federations. The provider management proxy method forwards provider-specific
management requests to the respective provider module. We implemented pluggable manageability
using the provider proxy method because each provider implementation has different management
operation. In our view, a provider module in the management client „talks‟ to the managed plugin in
the STS.
Page 175
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Core data structures
This section describes the main data structures we use all over the SAFe implementation.
6.1.1.117 Organization-internal IDs, Owners and Subjects
Each individual in an organization has an „organization-internal identity‟. Inside Microsoft‟s corporate
network, that would be the employee‟s alias or Kerberos ID. Alternatively, it could be an e-mail
address or the subject name of a certificate that is issued by a company-internal PKI. The
organization-internal ID is never exposed or shared with entities outside of the organization. We use
the organization-internal ID for two different purposes: The first one is to represent the owner of a
scoped federation, i.e., the responsible business person. The second purpose is the <Subject>
element in our real-users client claims provider (see section 6.1.1.124.1).
An organization-internal ID is serialized as follows:
<cfg:OrganizationInternalID
Type="http://www.w3.org/2000/09/xmldsig#X509SubjectName">
CN=Alice
</cfg:OrganizationInternalID>
6.1.1.118 FederationUUID
A „FederationUUID‟ is a unique identifier (the scope) for a scoped federation. A <FederationUUID>
element is similar to the <FederationID> element from the most-recent WS-Federation specification.
An example for a FederationUUID looks as follows:
(01) <FederationUUID xmlns="http://www.microsoft.com/emic/SAFe/">
(02)
324f9892-1e6d-8729-87cc-b87d90d4657e
(03) </FederationUUID>
The cross-organizational SAFe security tokens, as well as the SAFe-specific token issuance
requests, contain such a FederationUUID element. This means that (a) a requestor must specify as
part of the RST for what federation he wants a token to be issued and (b) the token can only be
used in the scope of that federation.
When embedding a FederationUUID into an RST, we put it into the following location (expressed as
XPath). Please see also the SAML/WS-Trust profile for SAFe:
wst:RequestSecurityToken/
wsp:AppliesTo/
wsa:EndpointReference/
wsa:ReferenceProperties/
emic:FederationUUID
The above location means that we treat the Federation(UU)ID as a part of the service call itself, i.e.,
we do not call the service, but we call the service in a particular scope.
6.1.1.119 Business cards
A „business card‟ is used as reference to a partner in a federation. It contains the following
information:
Page 176
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007

REQUIRED: The partner‟s STS‟s endpoint reference

REQUIRED: The partner‟s STS‟s security token (currently both for signing/issuing tokens, as well as
for encryption)

OPTIONAL: Additional information that can be used to refer to a given partner company, such as a
UDDI business entity key or the legal name of the company.
The following example shows a sample business card:
(01) <bc:BusinessCard
xmlns: bc="http://www.microsoft.com/emic/SAFe/#BusinessCard">
(02) <bc:SecurityTokenService>
(03)
(04)
<wsa:EndpointReference>
<wsa:Address>http://www.contoso.com/STS/STS.ashx</wsa:Address>
(05)
</wsa:EndpointReference>
(06)
<bc:SecurityTokens>
(07)
(08)
<wsse:BinarySecurityToken
ValueType="...-wss-x509-token-profile-1.0#X509v3"
EncodingType="...#Base64Binary">
MIIC5z...JV
</wsse:BinarySecurityToken>
</bc:SecurityTokens>
(09) </bc:SecurityTokenService>
(10) <bc:CompanyHomepage>http://www.contoso.com/</bc:CompanyHomepage>
(11) <uddi:businessKey xmlns:uddi="urn:uddi-org:api_v2">
(12)
00000000-1111-2222-3333-444444444444
(13) </uddi:businessKey>
(14) </bc:BusinessCard>
Lines (02-09) contain the required information about the partner‟s STS. The lines (03-05) contain the
STS‟ EPR, and lines (06-08) contain the STS‟ security token. This security token is used for multiple
purposes: When we validate tokens that have been issued by that STS, we can check the STS‟
signature with that token. When we issue tokens that will be validated by the given STS, we can
encrypt information inside the issued token for that STS.
Line (10) contains the URL of the company‟s homepage, and the lines (11-13) contain the UDDI
business entity key of the partner.
6.1.1.120 Federation partner identifiers
At the moment, our client/service interaction model is very similar to Kerberos. Therefore, a client
must indicate in the RST for what federation partner the requested token is intended. For example, a
client at Contoso that needs to access a service at Fabrikam would need to ask his STS: “Please
give me a token that I can use for service invocations at „Fabrikam‟.”
A „federation partner identifier‟ (FPI) is a reference to a partner‟s business cards. Such an FPI could
be retrieved from the service using WS-MEX, by asking the service: “Who is your owner?” The
service could then answer with the full business card of the company or just with an FPI.
The following examples shows different FPIs that may refer to the same business card:
Page 177
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
(01) <fpi:FederationPartnerIdentifier xmlns:fpi=
"http://www.microsoft.com/emic/SAFe/#FederationPartners">
(02)
(03)
<ds:X509Data>
<ds:X509SubjectName>
(04)
(05)
(06)
CN=CONTOSO Security Token Service
</ds:X509SubjectName>
</ds:X509Data>
(07) </fpi:FederationPartnerIdentifier>
In the above example, the FPI wraps the subject name of the STS‟ security token from the business
card. In the example given below, you can see the UDDI business entity key of the federation
partner.
(01) <fpi:FederationPartnerIdentifier>
(02)
(03)
(04)
<uddi:businessKey xmlns:uddi="urn:uddi-org:api_v2">
00000000-1111-2222-3333-444444444444
</uddi:businessKey>
(05) </fpi:FederationPartnerIdentifier>
We use FPIs both inside RST messages, as well as in ds:KeyInfo elements in token signatures. For
an RST, the client indicates the target service‟s owner organization by embedding one or more FPIs
in the following XPath location in the RST:
wst:RequestSecurityToken/
wsp:AppliesTo/
wsa:EndpointReference/
wsa:ReferenceProperties/
fpi:FederationPartnerIdentifier
In an XML-based security token, we use the FPI to refer to the token issuer in lines (14-25):
(01) <saml:Assertion Issuer="http://www.contoso.com/STS/STS.ashx" ...>
(02)
...
(03)
<ds:Signature>
(04)
...
(05)
<ds:KeyInfo>
(06)
(07)
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier
ValueType="#X509SubjectKeyIdentifier"
EncodingType="#Base64Binary">...</wsse:KeyIdentifier>
(08)
</wsse:SecurityTokenReference>
(09)
<wsse:SecurityTokenReference>
Page 178
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
(10)
(11)
(12)
<wsse:Embedded>
<wsse:BinarySecurityToken>...</wsse:BinarySecurityToken>
</wsse:Embedded>
(13)
</wsse:SecurityTokenReference>
(14)
<fpi:FederationPartnerIdentifier>
(15)
(16)
(17)
(18)
(19)
<ds:X509Data>
<ds:X509SubjectName>
CN=CONTOSO Security Token Service
</ds:X509SubjectName>
</ds:X509Data>
(20)
</fpi:FederationPartnerIdentifier>
(21)
<fpi:FederationPartnerIdentifier>
(22)
(23)
(24)
(25)
<uddi:businessKey>
00000000-1111-2222-3333-444444444444
</uddi:businessKey>
</fpi:FederationPartnerIdentifier>
(26)
</ds:KeyInfo>
(27)
</ds:Signature>
(28) </saml:Assertion>
6.1.1.121 Claims-issuer policy filters
One of the issues we had with setting up scoped federations was that we wanted to restrict the set
of claims that we accept from certain federation partners. For example, we wanted to constrain that
when our STS validates a token from Contoso, we only accept certain claims types, and for claims
only very specific values. A „claims-issuer policy filter‟ is a collection of claim templates that we use
to filter the issued claims from the given federation partner.
(01) <ClaimsIssuerPolicyFilter>
(02)
<Role xmlns="...">Researcher</Role>
(03)
<Role xmlns="...">Developer</Role>
(04)
<ShoeSize xmlns="..." />
(05) </ClaimsIssuerPolicyFilter>
The above example would (depending on the semantics of <Role> and <ShoeSize>) mean that we
accept arbitrary ShoeSize claims, as well as role claims that contain the given values. Basically,
applying a „claims-issuer policy filter‟ to a given claim is like checking whether a regular expression
matches an input text.
Provider implementations
This section provides a brief overview about the different provider implementations that we consider
relevant for our scenarios. The scenarios EMIC works on in the collaborative projects range from
simple to rather esoteric.
Page 179
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.122 Federation selector
A „federation selector‟ is a component that helps the STS to select the appropriate federation for a
given WS-Trust RST. Our STS database contains configuration for different federations. When the
STS receives a token issuance or validation request, it needs to determine what federation
configuration applies to the request.
public interface IFederationSelector : IXmlElement
{
Federation FindFederationInManagement(
STSDatabase database);
Federation FindFederationInSTSOperations(
RequestSecurityToken rst,
STSDatabase database);
}
„SearchByFederationUUID‟ federation selector
In the TrustCoM project (which is about trust and security in virtual organizations), we select the
respective scoped federation using a FederationUUID-based federation selector. The STS database
can store an arbitrary amount of federations that differ in the FederationUUID.
(06) <cfg:FederationSelector>
(07)
(08)
(09)
(10)
(11)
<FederationUuidSelector xmlns="...">
<FederationUUID xmlns="http://www.microsoft.com/emic/SAFe/">
00000000-1111-2222-3333-555555555555
</FederationUUID>
</FederationUuidSelector>
(12) </cfg:FederationSelector>
6.1.1.123 Federation-partner providers
As mentioned in section 6.1.1.115.2, a federation-partner provider allows retrieval of partner STS
endpoint references and security tokens. A federation-partner provider may be able to retrieve the
business cards of all federation partners (GetAllPartners()). It MUST be able to determine whether a
given partner is member of the federation (IsMember()). It MUST be able to retrieve a claims-issuer
policy filter (if there is one associated with that partner). A federation-partner provider also must be
able to retrieve our own token-issuance security token, i.e., the token that all other partners use to
validate security tokens we issue (GetSTSIssuanceToken()).
public interface IFederationPartnerProvider : IXmlElement
{
BusinessCard GetPartnerBusinessCard(
ICollection<FederationPartnerIdentifier> fpis);
ICollection<BusinessCard> GetAllPartners();
bool IsMember(BusinessCard businessCard);
ClaimsIssuerPolicyFilter GetClaimsIssuerPolicyFilter(
Page 180
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
BusinessCard businessCard);
SecurityToken GetSTSIssuanceToken();
}
We currently see two main classes of federation-partner providers: First a decentralized provider
where every partner knows all other partners, i.e., where each partner knows all other participants,
and second a provider with a central membership directory which keeps track of federation
membership.
6.1.1.123.1 Manually established partner lists
The term „manually established partner list‟ refers to a provider where each partner has a list of all
other federation partners, i.e., membership changes somehow need to be communicated to all
involved federation partners. The underlying scenario is that Bob creates a federation in his
company, and adds business cards of the partner companies to the federation‟s partner-provider. In
terms of the underlying business logic, there may be approval processes behind that procedure,
such as „Make sure that nobody can add Contoso.com as partner to a federation with Microsoft‟.
Other scenarios may include white lists of pre-approved partners etc.
The following example shows a federation-partner provider section where the manually-established
partner list includes our own business card (lines 03-07), as well as two other partners (lines 08-22).
For both partners, we have the respective business cards (lines 10 and 16), as well as their
respective claims-issuer policy filters (lines 11-13 and lines 17-20). In this particular example, we
only accept Role=”Financial auditor” claims from the first partner, and the roles dev and project mgr
from the second partner.
(13) <cfg:FederationPartnerProvider>
(14)
(15)
(16)
(17)
(18)
<ManuallyEstablishedPartnerList xmlns="...">
<OurOwnBusinessCard>
<cfg:Partner>
<bc:BusinessCard>...</bc:BusinessCard>
</cfg:Partner>
(19)
</OurOwnBusinessCard>
(20)
<OtherPartners>
(21)
<cfg:Partner>
(22)
<bc:BusinessCard>...</bc:BusinessCard>
(23)
<cfg:ClaimsIssuerPolicyFilter>
(24)
(25)
<Role xmlns="...">Financial auditor</Role>
</cfg:ClaimsIssuerPolicyFilter>
(26)
</cfg:Partner>
(27)
<cfg:Partner>
(28)
<bc:BusinessCard>...</bc:BusinessCard>
(29)
<cfg:ClaimsIssuerPolicyFilter>
(30)
<Role xmlns="...">Developer</Role>
(31)
<Role xmlns="...">Project Manager</Role>
(32)
</cfg:ClaimsIssuerPolicyFilter>
Page 181
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
(33)
</cfg:Partner>
(34)
</OtherPartners>
(35)
</ManuallyEstablishedPartnerList>
(36) </cfg:FederationPartnerProvider>
6.1.1.124 Client-claims provider
As mentioned in section 6.1.1.115.3, a client-claims provider retrieves the claims for a given client:
public interface IClientClaimsProvider : IXmlElement
{
ClaimsCollection GetClientClaims(
SecurityToken clientSecurityToken,
RequestSecurityToken rst);
}
Many models make sense in that area, such as assigning the same set of claims to all clients, doing
a SQL or Active Directory lookup, based on AD group membership, based on external context
services (as done in MOSQUITO), etc.
6.1.1.124.1 „Real users‟-provider
The only client-claims provider we describe in that document is the „real users‟ client claims provider,
which is a very simple manually configured mapping from a client identity to the corresponding set of
claims.
In the example given below, the client “CN=EMIC Client” (authenticating using his certificate) would
get two role claims (for employee and developer) into his token, whereas the client
“REDMOND\billg” (authenticating using Kerberos) would get two role claims (for employee and
manager) into his token.
(37) <cfg:ClientClaimsProvider>
(38)
(39)
(40)
(41)
(42)
(43)
<RealUsers xmlns="...">
<cfg:UserAndClaim>
<cfg:Subject>
<cfg:OrganizationInternalID Type="...#X509SubjectName">
CN=EMIC Client
</cfg:OrganizationInternalID>
(44)
</cfg:Subject>
(45)
<cfg:Claim>
(46)
<Role xmlns="...">Employee</Role>
(47)
<Role xmlns="...">Developer</Role>
(48)
</cfg:Claim>
(49)
</cfg:UserAndClaim>
(50)
<cfg:UserAndClaim>
(51)
(52)
<cfg:Subject>
<cfg:OrganizationInternalID Type="...#Kerberos">
Page 182
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
(53)
(54)
REDMOND\billg
</cfg:OrganizationInternalID>
(55)
</cfg:Subject>
(56)
<cfg:Claim>
(57)
<Role xmlns="...">Employee</Role>
(58)
<Role xmlns="...">Manager</Role>
(59)
(60)
(61)
</cfg:Claim>
</cfg:UserAndClaim>
</RealUsers>
(62) </cfg:ClientClaimsProvider>
6.1.1.125 Service-access and claims-validation providers
As mentioned in section 6.1.1.115.4, a „service-access and claims-validation provider‟ is a
component that the STS needs during the token validation process. It basically performs the
validation of a cross-organizational token that was used during the invocation of a particular service
endpoint. The provider gets as input the cross-organizational token, as well as the service‟s identity,
i.e., the service‟s security token, the service‟s address and the wsa:Action.
public interface IServiceAccessClaimsValidationProvider : IXmlElement
{
ValidationClaim ValidateClaimsForServiceAccess(
SecurityToken federationToken,
SecurityToken serviceToken,
Address address,
Action action);
}
The provider‟s internal functionality may vary from simple functionality such as pure token validation
up to a full-blown access control decision.
6.1.1.125.1 TrustCoM pure claims validation
In the TrustCoM project, partners do not want our STS to do access control decisions. They want to
have their PEP just using our STS for token validation (and returning the extracted and validated
claims back to the PEP), and then sending the validated claims to an XACML policy decision point to
do the actual access control decision. In order to support that model, we have implemented a simple
„service-access and claims-validation provider‟ for TrustCoM which does not contain access control
policies. This provider „just‟ returns the validated claims back to the PEP, without actually looking at
what service has been invoked:
STS
PDP
PEP
Service
Page 183
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
To configure that provider, the user only registers the services for the given VO in the STS, and
defines the service‟s security token. No actions etc are configured.
(63) <cfg:ServiceAccessClaimsValidationProvider>
(64) <TrustCoMPureClaimsValidation
xmlns="http://www.microsoft.com/EMIC/TrustCoM/ClaimsValidation">
(65)
<ServiceToken>
(66)
<wsa:Address>http://www.contoso.com/Service.asmx</wsa:Address>
(67)
<wsse:BinarySecurityToken
ValueType="...#X509v3"
EncodingType="...#Base64Binary"
>MIIB+TCCAWagAwIB....</wsse:BinarySecurityToken>
(68)
</ServiceToken>
(69) </TrustCoMPureClaimsValidation>
(70) </cfg:ServiceAccessClaimsValidationProvider>
Policy Decision Point Service
6.1.1.126 Installation Guide
This section covers the installation of the Policy Decision Point.
6.1.1.127 Package Contents
Name
Type
Description
Doc
Directory
Package
Javadocs.
Lib
Directory
JAR file dependencies.
Metadata
Directory
Additional files for configuration, deployment
and testing.
Src
Directory
Java sources for the PDP
Readme.txt
Text
Package guide
build.xml
Ant build
file
Main build file to compile and deploy the
PDP
documentation,
including
6.1.1.128 Requirements
The libraries the PDP is dependant on are provided by the package, in the Lib directory. For more
details on dependencies, see section 6.1.1.133 below.
Page 184
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Required software:




Java 1.5 SDK (http://java.sun.com).
Ant 1.6.5 (http://ant.apache.org).
Tomcat 5.5 (http://tomcat.apache.org).
Axis 1.2/1.4 (http://ws.apache.org/axis).
6.1.1.129 Installation
0. Install pre-requisites according to their respective installation instructions.
1. Set up the environment variables AXIS_HOME, AXIS_LIB, and AXIS_PORT in ant‟s build file
(build.xml) so they match your Axis installation. AXIS_HOME corresponds to Axis' install directory,
Axis JAR library directory corresponds to AXIS_LIB, and the TCP port Axis listens to corresponds to
AXIS_PORT. See section 6.1.1.130 below for more information on build options.
2. Open a command line console.
3. Assuming you have placed the contents of this package under the PDP-SICS directory, cd to the
PDP-SICS directory.
4. Build the PDP library and the documentation running:
ant
5. Make sure Axis is not running (use, for example, Tomcat's Web Application Manager). Install the
PDP library (and dependencies) in Axis running:
ant install
(you
may
need
administrator
rights
for
this
step.)
6. Start or re-start Axis
7. Deploy the PDP web service running:
ant deploy
8. You are done!
You can run a simple test of your installation following the instructions in section 6.1.1.132 below. If
you decide to install the PDP manually see section 6.1.1.131 below.
6.1.1.130 Build Options
The building and installing procedures assume Axis install directory is AXIS_HOME, Axis JAR library
directory is AXIS_LIB, and the TCP port Axis listens to is AXIS_PORT.
If these defaults do not match your Axis installation you must:
1. Edit the top lines of the build.xml file, or
2. run the 'ant' command with specific values for these properties. For example,
Page 185
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
ant -DAXIS_LIB=/myaxis/webapps/axis/WEB_INF
-DAXIS_PORT=1234
10
Common values for Linux installation of Axis are :
AXIS_HOME = /usr/share/tomcat5
AXIS_LIB
= ${AXIS_HOME}/webapps/axis/WEB_INF
AXIS_PORT = 8080
Common values for a Windows installation of Axis are:
AXIS_HOME = C:/Axis
AXIS_LIB
= %AXIS_HOME%/webapps/axis/WEB_INF
AXIS_PORT = 8080
6.1.1.131 Manual Installation
If you decide to install the SICS PDP manually:
1. You need to add
xml-security.jar,
sunxacml-fixed.jar,
and xacml-delegation.jar
from the Lib directory of this package to the Axis class path, since they are not there by default.
2. Deploy the service. You can find Axis deployment files (wsdd) to deploy and undeploy the PDP
service in the Metadata directory.
6.1.1.132 Testing
There is a unit test which you can use to test that a PDP is up and running
correctly. Run the test as follows:
ant test
or
ant -DAXIS_PORT=1234
in case you want to use a specific port. This procedure assumes your PDP web service URL is
http://localhost:${AXIS_PORT}/axis/services/TrustCoMPDP
which is the default when deploying to the local host with the automatic
installation. If you deployed your PDP with a different URL run:
10
Notice, however, that some Linux distributions install Tomcat to listen to port 8180 by default.
Check your Linux distribution documentation.
Page 186
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
ant -DPDP_URL=<your PDP url...> test
The test will exercise the functions of the PDP by loading and testing a couple of
simple policies. If it completes successfully, your console will show an output like:
OK (1 test)
(You can ignore any warnings from log4j.)
Please note that running the test will clear the contents of the PDP.
6.1.1.133 Dependencies
All dependencies can be found in the package‟s Lib directory. The following libraries are needed in
your class path to compile the code:
Library
Origin
axis.jar
jaxrpc.jar
Included in Axis
saaj.jar
commons-logging.jar
commons-discovery.jar
Apache commons
activation.jar
Sun's javabeans activation framework
xml-security.jar
Apache xml-security
sunxacml.jar
A fixed version of Sun‟s XACML 1.2 (see note below).
xacml-delegation.jar
SICS delegation extension to sunxacml 1.2
Junit.jar
jUnit testing framework
IMPORTANT NOTE: the sunxacml.jar file provided in this package fixes a bug in the original
11
SUN XACML code (v1.2). This bug prevented the use of namespace prefixes in XML .
11
For
example,
constructions
<xacml:Policy xmlns:xacml="urn:oasis:names:tc:xacml:1.0:policy" ...>.
Page 187
like
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
User‟s Guide
In order to set up the PDP, a user only needs to add one or more root XACML policies. There should
be no other direct user interaction with the PDP. Refer to the TrustCoM Framework Profiles
12
document for details on the use of XACML.
6.1.1.134 Configuring root policies
The PDP requires one or more root policies. These policies are used to define who may issue
policies or, in simple settings, they may be used by themselves to define access control. The PDP
service
provides
the
following
operations
to
manage
root
policies:
Operation
Input
Description
Return type
AddRootPolicy
An
<AddRootPolicy>
element from the
PDP
schema,
including
an
XACML policy or
policy set.
This adds a
root policy
(or
policy
set) to the
PDP
database of
policies. The
authority of
the policy is
not checked
at any time
during the
lifecycle of
the PDP.
A
<Response>
element from
the
PDP
schema,
either with the
id
of
the
policy
that
was added, or
with
an
<Error>
element
describing the
nature of the
error.
RemovePolicy
A
<RemovePolicy>
element from the
PDP
schema,
with the id of the
policy
to
be
removed.
Removes
the
policy
with
the
given
id
from
the
database.
There is no
indication of
error in case
the
policy
does
not
exist.
A
<Response>
element from
the
PDP
schema with
the id of the
policy
that
was removed,
or with an
<Error>
element
describing the
nature of the
error.
There are example <AddRootPolicy> and <RemovePolicy> messages included in the
Metadata directory of the package.
12
D63 TrustCoM Framework V4 - Appendix A
Page 188
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Developer‟s Guide
The following is a reference guide for all the interfaces and operations exposed by the PDP service.
For an example exercising all this operations, refer to the source code of the test class
se.sics.trustcom.pdp.test provided in this package.
Many operations require XACML elements as arguments. Please refer to the TrustCoM Framework
13
Profiles document for XACML specifics.
6.1.1.135 The TrustCoM PDP Access Request Interface
A service can use an associated PDP Service for determining whether a particular access to the
service should be allowed or not, based on the PDP‟s policy contents. For this purpose, the
interface has the following operations:
Operation
Input
Description
Return type
Request
An
XACML
<Request>.
Evaluates the given
request
against
the
currently loaded policies.
An
XACML
<Response>.
6.1.1.136 The TrustCoM PDP Management Interface
In addition to the access request method introduced in the previous section, the PDP Service has
operations that are used by policy administration points (PAPs), to update the policies that the PDP
has access to. These operations are the following:
Operation
Input
Description
Return type
AddRootPolicy14
An <AddPolicy>
element from the
PDP
schema,
including
an
XACML policy or
policy set.
This adds a
root policy
(or
policy
set) to the
PDP
database of
policies.
The
authority of
the policy is
not checked
at any time
during the
lifecycle of
the PDP.
A
<Response>
element from
the
PDP
schema,
either
with
the id of the
policy
that
was added,
or with an
<Error>
element
describing
the nature of
the error.
13
D63 TrustCoM Framework V4 - Appendix A
14
Note that in a production environment this method needs to be protected at the web server level
so only authorized components can load root policies, since a root policy can authorize anything
without further verification.
Page 189
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Operation
Input
Description
Return type
AddPolicy
An
<AddRootPolicy>
element from the
PDP
schema,
including
an
XACML policy or
policy set.
This adds a
policy
(or
policy set)
to the PDP
database of
policies.
The
authority of
the policy is
checked at
runtime
during
access
request
processing.
A
<Response>
element from
the
PDP
schema,
either
with
the id of the
policy
that
was added,
or with an
<Error>
element
describing
the nature of
the error.
RemovePolicy
A
<RemovePolicy>
element from the
PDP
schema,
with the id of the
policy
to
be
removed.
Removes
the
policy
with
the
given
id
from
the
database.
There is no
indication of
error
in
case
the
policy does
not exist.
A
<Response>
element from
the
PDP
schema with
the id of the
policy
that
was
removed, or
with
an
<Error>
element
describing
the nature of
the error.
Most of the messages that the PDP accepts and generates are defined in the PDP schema, which
has the namespace http://eu-trustcom.com/PDP/interface. The schema is supplied
further below in this document. There are example messages included in the Metadata directory of
the package.
6.1.1.137 The TrustCoM PDP Debugging and Testing Interface.
The following operations are provided for testing and debugging purposes:
Operation
Input
Description
Return type
GetPolicy
A <GetPolicy>
element from
the
PDP
schema.
Retrieves all
the
loaded
policies.
An XACML PolicySet
document with all the
loaded
policies,
including
root
policies.
Page 190
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
ClearPDP
A <ClearPDP>
element from
the
PDP
schema.
Completely
clears
the
contents of
the PDP.
A
<Response>
element from the
PDP schema, with
either a <Success>
element, or with an
<Error>
element
describing the nature
of the error
These operations are provided for conveniency, and they are not intended to be used in a
production environment.
6.1.1.138 The TrustCoM PDP schema
The input and output documents used by the PDP are defined by the following schema:
<?xml version="1.0" encoding="UTF-8"?>
<schema
targetNamespace="http://eu-trustcom.com/PDP/interface"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:pdp="http://eu-trustcom.com/PDP/interface"
xmlns:xacml="urn:oasis:names:tc:xacml:1.0:policy"
elementFormDefault="unqualified"
attributeFormDefault="unqualified"
version="2.0">
<xs:import namespace="urn:oasis:names:tc:xacml:1.0:policy"/>
<xs:element name="AddPolicy" type="pdp:AddPolicyType"/>
<xs:complexType name="AddPolicyType">
<xs:sequence>
<xs:element ref="pdp:AssertWithToken"/>
</xs:sequence>
</xs:complexType>
<xs:element name="AssertWithToken" type="pdp:AssertWithTokenType"/>
<xs:complexType name="AssertWithTokenType">
<xs:sequence>
<xs:element ref="pdp:MockToken"/>
<xs:element ref="pdp:Signature"/>
Page 191
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
<choice>
<xs:element ref="xacml:Policy"/>
<xs:element ref="xacml:PolicySet"/>
</choice>
</xs:sequence>
</xs:complexType>
<xs:element name="MockToken" type="pdp:MockTokenType"/>
<xs:complexType name="MockTokenType">
<xs:sequence>
<xs:element ref="pdp:Claim" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:element name="Claim" type="pdp:ClaimType"/>
<xs:complexType name="ClaimType">
<xs:sequence>
<xs:element ref="pdp:AttributeId"/>
<xs:element ref="pdp:AttributeValue"/>
</xs:sequence>
</xs:complexType>
<xs:element name="AttributeId" type="xs:anyURI"/>
<xs:element name="ValueId" type="xs:string"/>
<xsd:element name="Signature">
<xsd:complexType>
<xsd:complexContent>
<xsd:restriction base="xsd:anyType"/>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="ClearPDP">
<xsd:complexType>
<xsd:complexContent>
<xsd:restriction base="xsd:anyType"/>
</xsd:complexContent>
Page 192
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
</xsd:complexType>
</xsd:element>
<xsd:element name="GetPolicy">
<xsd:complexType>
<xsd:complexContent>
<xsd:restriction base="xsd:anyType"/>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xs:element name="RemovePolicy" type="xs:anyURI"/>
<xs:element name="AddRootPolicy" type="pdp:AddRootPolicyType"/>
<xs:complexType name="AddPolicyType">
<xs:sequence>
<choice>
<xs:element ref="xacml:Policy"/>
<xs:element ref="xacml:PolicySet"/>
</choice>
</xs:sequence>
</xs:complexType>
<xs:element name="Response" type="pdp:ResponseType"/>
<xs:complexType name="ResponseType">
<xs:sequence>
<choice>
<xs:element ref="pdp:Success"/>
<xs:element ref="pdp:Error"/>
<xs:element ref="pdp:PolicyId"/>
<xs:element ref="xacml:Policy"/>
<xs:element ref="xacml:PolicySet"/>
</choice>
</xs:sequence>
</xs:complexType>
<xs:element name="Success" type="xs:string"/>
<xs:element name="Error" type="xs:string"/>
Page 193
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
<xs:element name="PolicyId" type="xs:anyURI"/>
</schema>
SICS SLA Management Subsystem
Installation Guide
This section covers the installation of the SLA Management components developed by SICS.
The package includes the following components:
Name
Type
Description
Service
This is the component that a VO instantiator
calls to manage the SLA Management
subsystem.
SLA
Repository
Service
The component
documents.
that
stores
the
SLA
SLA Template
Repository
Service
The component that
Template documents15.
stores
the
SLA
Performance
Log
Service
The persistent storage for performance
notifications.
SLA Evaluator
Service
An engine to evaluate SLA Service Level
Objectives.
SLA Evaluator
Manager
Service
The SLA manager that manages the SLA
Evaluator.
SLA Evaluator
Factory
Service
The SLA Evaluator Factory.
VO
Manager
SLA
6.1.1.139 Package Contents
The SICS SLA Management subsystem package contains:
Name
Type
Description
15
This component is not needed for the normal functioning of the SLA management and monitoring
subsystem. It is provided in order to support the negotiation of SLAs during the VO formation phase.
Page 194
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Name
Type
Description
Doc
Directory
Package documentation, including Javadocs.
Lib
Directory
JAR file dependencies.
MetaData
Directory
Additional files for configuration, deployment
and testing.
Dist
Directory
The binary
components.
Src
Directory
Java sources for the SLAM Components.
Readme.txt
Text
Package guide
build.xml
Ant
file
build
distribution
of
the
SLAM
Main build file to compile and deploy the SLAM
components.
6.1.1.140 Requirements
The libraries the SICS SLAM subsystem is dependant on are provided with the package, in the Lib
directory. For more details on dependencies, see section 6.1.1.144 below.
Required software:







Java 1.5 SDK (http://java.sun.com).
Ant 1.6.5 (http://ant.apache.org).
Tomcat 5.5 (http://tomcat.apache.org).
Xindice (http://xml.apache.org/xindice), implementing the SLA Repository.
Globus Toolkit 4.0.1, Java WS Core Binary Installer (http://www.globus.org/toolkit/downloads/4.0.1).
TrustCoM Notification subsystem.
TrustCoM Application Service Monitors.
6.1.1.141 Installation
0. Install pre-requisites according to their respective installation instructions.
1. Set the environment variable GLOBUS_LOCATION to point to the directory where the Globus Toolkit is
installed, e g: C:/ws-core-4.0.1.
2. Set the environment variable TOMCAT_HOME to point to the directory where Tomcat is installed, e g:
C:/apache-tomcat-5.5.17.
3. Configure the services by editing the configuration.properties files found in the following
source directories:
Component
Directory
SLA Performance Log
src/xfire/main/java/org/trustcom/slam/log/xfire
Page 195
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Component
Directory
VO SLA Manager
src/xfire/main/java/org/trustcom/slam/vo/xfire
SLA Evaluator
src/globus/main/java/org/trustcom/slam/evaluator/globus
4. Open a command line console.
5. Assuming you have placed the contents of this package under the SLAM-SICS directory, cd to the
SLAM-SICS/MetaData directory.
6. Deploy all the web services running:
ant deploy
7. Start or re-start Tomcat and Globus servers.
8. You are done!
6.1.1.142 Configuration
The services can be re-configured after installation by editing the configuration.properties
files
found
in
the
following
web
application
directories:
Component
Directory
SLA
Performance
Log
(TOMCAT_HOME)
/webapps/trustcom/WEB-INF/lib/slam-log-jar0.9.jar/org/trustcom/slam/log/xfire/
VO
SLA
Manager
(TOMCAT_HOME)
/webapps/trustcom/WEB-INF/classes/org/trustcom/slam/vo/xfire/
SLA
Evaluator
(GLOBUS_LOCATION)
/lib/slaevaluatorwebservice.jar/org/trustcom/slam/evaluator/globus/
The Tomcat and Globus servers must be re-started for the changes to take effect.
6.1.1.143 Testing
You can test your system with the SLA GUI (more details on how to use the GUI in section 6.1.1.152
below).
0.
1.
2.
3.
4.
5.
6.
Configure and start the GUI.
Add the SLA found at MetaData/ws-agreement-example.xml
Select the SLA to the left named ws-agreement-example
Make sure that the internal monitor check box is selected in the Configure panel
Move to the Control panel
Press the Read toggle buttons to enable log reading
Press the start button that will start all relevant services.
Now you should see from the Remote Evaluator log entries that the evaluator is being started and
thereafter from the Remote Accounter log that the accounter is being started. Lastly the internal
monitor should become visible in separate window.
7. Select appropriate interval values when prompted (should be valid values by default)
Page 196
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
8. Press the Clear buttons to hide shown log entries
9. Press the send one button once.
Soon you will see in the evaluator log that it receives a notification, evaluates it and sends a new
violation notification.
Then you will see in the accounter log that the accounter receives and processes the evaluator‟s
notification.
10. Press the Stop button to stop all relevant services.
11. If no exception occurred, your are done.
6.1.1.144 Dependencies
All dependencies can be found in the package‟s Lib directory. The following dependencies list is
provided for informational purposes.
Library
Origin
activation-1.1.jar
SUN JavaBeans Activation Framework
antlr-2.7.5.jar
ANTLR Parser Generator
cglib-full-2.0.2.jar
Code Generation Library
commons-beanutils-1.7.0.jar
Apache Commons
commons-codec-1.3.jar
commons-httpclient-3.0.jar
commons-logging-1.0.4.jar
dom4j-1.6.1.jar
dom4j XML framework
drools-all-jdk5-2.1.jar
Drools rules engine
jaxb-api-2.0.jar
Java Architecture for XML Binding
jaxb-impl-2.0.1.jar
jaxb-xjc-2.0.1.jar
jaxen-1.1-beta-9.jar
Jaxen: universal Java XPath engine
jdom-1.0.jar
Jdom: XML manipulation
jsr94-1.1.jar
Java Rule Engine API
jsr94-tck-1.1.jar
junit-3.8.1.jar
jUnit testing framework
log4j-1.2.13.jar
Logging package
Page 197
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Library
Origin
mail-1.4.jar
JavaMail API
quartz-1.5.1.jar
Quartz job scheduling system
stax-api-1.0.1.jar
SUN StAX API
wicket-1.2.jar
Web application framework
wsdl4j-1.5.2.jar
WSDL for Java Toolkit
wstx-asl-2.9.3.jar
Woodstox XML processor
xbean-2.1.0.jar
Apache Xbean
xerces-2.6.0.jar
Apache Xerces XML parser
xercesImpl-2.7.1.jar
xfire-annotations-1.1.1.jar
Codehaus XFire SOAP framework
xfire-core-1.1.1.jar
xfire-generator-1.1.1.jar
xfire-java5-1.1.1.jar
xfire-jaxb2-1.1.1.jar
xfire-jsr181-api-1.0-M1.jar
xfire-xmlbeans-1.1.1.jar
xindice-1.1b4.jar
Apache Xindice XML database
xml-apis-1.0.b2.jar
SUN XML API
xmldb-api-20030701.jar
XML:DB API
xmldb-common-20030701.jar
XML:DB
xmlParserAPIs-2.6.2.jar
Apache Xerces XML parser
xmlrpc-1.2.jar
Java XML-RPC
XmlSchema-1.0.3.jar
Apache Commons XML Schema
Page 198
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
User‟s Guide
There is no direct user interaction with the SLA Management sub-system. All these components are
managed by other components of the TrustCoM infrastructure. In order to set up the SLA
Management subsystem, these components should only interact with the SLA Repository and the
VO SLA Manager.
The package includes a GUI to update the SLA Repositories and to act as the VO SLA Manager, to
be used for debugging and testing purposes. See section 6.1.1.152 below for more details on how to
use the GUI.
Developer's Guide
The following is a reference guide for all the interfaces and operations exposed by the SLA
Management subsystem.
6.1.1.145 SLA Repository
The SLA repository is a specialised XMLdatabase which stores SLA documents. An SLA
document is stored under a unique key, which is taken from the AgreementId attribute specified in
the <Agreement> element of the document. It is the responsibility of the creator of the document to
provide a unique AgreementId.
The service has the following operations:




store(SLA SLA_doc)
Stores an SLA document in the repository database. The document must conform to TrustCoM‟s own
16
extension of the WS-Agreement specification. Refer to the TrustCoM Framework Profiles document
for details on TrustCoM‟s use of WS-Agreement.
remove(String agreementId)
Removes the SLA document with the given id.
getAgreement(String agreementId)
Returns the SLA document with the given id.
ArrayOfSLA query(String xpath)
17
Returns an array of SLA documents which match the given XPath expression .
6.1.1.146 VO SLA Manager Service
This is the component that a VO instantiator calls to manage the SLA Management subsystem. The
VO SLA Manager is a component that manages the SLA subsystem configuration at a high level
(VO level). The component exposes three methods: configure, start, stop which require an
agreementId as their only argument. The agreementId identifies an SLA document which
specifies all the details necessary to set up the monitoring and evaluation of the agreement. The VO
SLA Manager will identify and manage the individual SLA subsystem components required to
monitor that particular SLA as specified by the SLA document. Notice that there must be an SLA
document with the corresponding agreementId in an SLA repository accessible to the VO SLA
manager.
The service has three operations:
16
TrustCoM Framework Profiles document (D63 TrustCoM Framework V4 - Appendix A)
17
For more information see http://xml.apache.org/xindice/guide-xpath.html
Page 199
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007



Boolean configure(String agreementId)
called to initialize the monitoring and evaluation of an Service Level Agreement document referred to
by its AgreementId.
Boolean start(String agreementId)
called to start the monitoring and evaluation of the SLA (starts the enactment of the SLA).
Boolean stop(String agreementId)
called to stop the monitoring and evaluation of the SLA (stops the enactment of the SLA).
6.1.1.147 SLA Evaluator Manager Service
The VO SLA Manager uses the SLA Evaluation Manager service to configure the evaluation of the
SLAs.
The service has three operations:



Boolean configure(String agreementId)
called to initialize the evaluation of an SLA document referred to by its AgreementId.
Boolean start(String agreementId)
called to start the evaluation of the SLA (starts the enactment of the SLA).
Boolean stop(String agreementId)
called to stop the evaluation of the SLA (stops the enactment of the SLA).
6.1.1.148 SLA Evaluator Factory Service
The SLA Evaluator factory is a service that in correspondence to WS-Resource Framework (WSRF)
implements a factory to create new SLA Evaluator resources. When the SLA Evaluation Manager
calls the create resource operation, it gets an endpoint reference to the new SLA Evaluator
resource.
This is a service only used internally by the SLA Evaluation Manager and it is not exposed outside
the TTP.
The factory has only one operation:

EndpointReferenceType createResource(SLA SLA_doc, String proxyID)
The SLA Evaluation Manager calls operation createResource in order to instantiate a new SLA
18
evaluator service for evaluating the conditions of a SLA defined by a XML document .
6.1.1.149 SLA Evaluator Service
The SLA Evaluator service is the access point for calling the SLA Evaluator resources created by
SLA Evaluator factory. Given an endpoint reference to a SLA Evaluator resource, the SLA
Evaluation Manager can configure it to receive notifications form the monitors according to the WSNotification (v.1.2 2004/06) specifications via the Notification Proxy. The SLA Evaluator
implementation is based on Globus Toolkit 4‟s WSRF and WS-Notification implementations.
This service has no operations other than those specified by WS-BaseNotification (Notify,
Subscribe) and by WS-ResourceLifetime (Destroy).
6.1.1.150 SLA Performance Log
The SLA Performance log is used to log all notifications sent by the SLA Evaluator service. It is in
fact a generic notification logger that can store anything that is sent to it by calling its notify
operation. It is also possible to query it for any notifications that are stored in its XML database. The
service uses an instance of Apache XIndice as its XML database backend.
18
TrustCoM Framework Profiles document (D63 TrustCoM Framework V4 - Appendix A)
Page 200
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The SLA Performance log has two operations:


List<Document> query(String xpath)
The query operation returns an array of XML documents that matches the given XPath expression.
The XML documents can be of any type.
void Notify(Document notificationMessage)
The Notify operation implements the corresponding WS-BaseNotification operation. All notification
messages of any XML type, for any topic are accepted. This operation can be called by any service
(with access rights) to log any message of any type.
6.1.1.151 SLA Template Repository
This component is not needed for the normal functioning of the SLA management and monitoring
subsystem. It is provided in order to support the negotiation of SLAs during the VO formation phase.
Please refer to the documentation of the corresponding subsystem for more details.
The service has the following operations:




store(RepositoryData data)
throws MissingElementException;
Stores a repository data in the database: a repository data consists of a business key, a role, a SLA
negotiator and an array of templates.
remove(String templateID)
throws TemplateNotRemoved;
Removes all templates with the given template id.
removeData(String businessKey, String businessRole)
throws TemplateNotRemoved, MissingElementException;
Removes all templates with the given key and role.
ArrayOfRepositoryDataType query(RepositoryQueryType serviceQuery)
throws MissingElementException;
Returns an array of repository data, where each repository data contains the templates belonging to
a key, a role and a negotiator. The key and role is given in the search query. It is possible to leave
out the key in the repository query and then return all repository data for a role. Similarly, it is
possible to leave out the role and return all roles for a key.
6.1.1.152 The SLAM Graphical User Interface
HPC SLA Monitoring Infrastructure
Installation Guide
For a successful installation you need the archive trustcom.zip and the MSI installers
SLAManagerSetup.msi, SLARepositorySetup.msi and GangliaServiceSetup.msi
6.1.1.153 Package Contents
Description of the elements of the package
Name
Type
Description
SLAManager
This component is used to setup the SLA
monitoring infrastructure
SLARepository
This component provides a local SLA
repository to store the negotiated SLAs.
Page 201
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
This repository is queried during the setup
by the SLAManager with the corresponding
SLA-ID.
SLAMonitorinDaemon
This component sends out the notifications
with the current system status.
GangliaService
This component is a webservice-wrapper for
the standard ganglia service. Furthermore
this component provides an internal SLA
parser allowing to extract the parameters of
interest from the corresponding SLA.
6.1.1.154 Requirements
The following prerequisites have to be available on the hosting system:
.Net Framework 2.0
WSE 3.0
SQL Server (Express) 2005
IIS 5++
Ganglia (actually tested with version 3.0 for Windows)
Notification Subsystem (installed with standard installation settings)
Service Instance Registry (SIR) service (alternatively use the one hosted at the HLRS server:
http://csharp.hlrs.de:8080/axis/services/SIR
6.1.1.155 Installation
6.1.1.155.1 Extracting the SLAMonitoringDaemon
Extract the content of trustcom.zip to c:\trustcom\. Take care that the content of trustcom.zip is not
extracted to another location! Finally assign to the c:\trustcom\ folder and all its subfolders read &
write access rights for the IIS service (usually referred by the ASPNET user). Note that if you want to
recompile the SLAMonitoringDaemon you have to copy the new compiled executable version (.exe)
into C:\TrustCom\SLAMonitoringDaemon\.
6.1.1.155.2 Installation of the SLAMonitor-Manager
Run the MSI-Installer SLAManagerSetup.msi. This will install and automatically deploy the SLAMonitoring-Manager to your IIS and will be available under the following URL:
http://localhost/trustcom/slamanager/slamanagerservice.asmx. Before the first usage of this service
please call the setup (string repositoryURL, string SIRURL, string hostID) method with the following
parameters:


repositoryURL: use here the URL of your local SLARepository. How to install and where to find the
service is described in the next paragraph
SIRURL: The URL of a service instance registry. How to install this service is described in another
document. For testing purposes you can use the HLRS SIR service being located at the following
URL: http://csharp.hlrs.de:8080/axis/services/SIR
Page 202
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007

hostID: The identifier of the machine that is going to be monitored. If this is your local machine, set
here for the host identifier “localhost”.
6.1.1.155.3 Installation of the SLA Repository
Run the MSI-Installer SLARepositorySetup.msi. This will install and automatically deploy the SLA
Repository
to
your
IIS
and
will
be
available
under
the
following
URL:
http://localhost/trustcom/slamanagement/slarepository/slarepositoryservice.asmx.
After the successful deployment of the SLA repository you have to call the initRepository() method
before the first usage. This method creates the needed tables for the repository in the corresponding
database.
6.1.1.155.4 Installation of the Ganglia Service
Run the MSI-Installer GangliaServiceSetup.msi. This will install and automatically deploy the
Ganglia Service to your IIS and will be available under the following URL:
http://localhost/trustcom/gangliamonitor/gangliaservice1.asmx
User‟s Guide
This component is configured and enacted directly by the VOSLAManager, so there is no direct user
interaction.
Developer's Guide
6.1.1.156 SLA-Manager
The SLAManager provides the following methods:
6.1.1.156.1 bool configure (string slaID)
Setup and configure the SLA monitoring sub system. In detail the ganglia
service is initialized.


slaID: The string representation of the SLA-ID referencing the SLA to be loaded.
returns: true, if configuration could be executed successfully, false otherwise
6.1.1.156.2 bool start (string slaID)
Starts the SLAMonitoring daemon. This daemon is polling the ganglia service and is sending the
corresponding status notification messages. Before starting the monitoring the configure method
must be executed successfully


slaID: The string representation of the SLA-ID referencing the SLA to be monitored.
returns: true, if a monitoring daemon was set up successfully
6.1.1.156.3 bool stopMonitoring (string slaID)
Stops the monitoring (daemon) for the given SLA, referenced by the SLA-ID

returns: true, if monitoring was stopped successfully, false otherwise (e.g. no monitoring daemon has
been instantiated for the given SLA)
Page 203
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The following methods have been used for testing purposes. For these purposes
they are still available.
6.1.1.156.4 bool configureBroker(string uriNotificationBroker)
Register the notification broker accessable with the given URL to the service instance registry.


uriNotificationBroker: The string representation of the URL of the notification broker
returns: true if the registration has been completed successfully, false otherwise.
6.1.1.156.5 string setHostID(string hostID)
Sets the host ID of the SLAManager, and the Ganglia service consequently.


hostID: The host ID to be set.
returns: The (new) current host ID of the SLAManager
6.1.1.156.6 bool setup(string Repository_URL, string SIRURL, string hostID)
Sets the URL of the Repository URL.




Repository_URL: The repository URL to be set.
SIRURL: The SIR-URL to be set.
hostID: The host identifier of the system that is going to be monitored.
returns: true, if the setting of a new repository URL was successful, false otherwise.
6.1.1.157 SLARepository
The SLARepository provides a local storage for SLADocument being provided in XML.
6.1.1.157.1 XmlDocument getSLA(string SLA_id)
Returns the SLA document with the given ID.


SLA_id: The ID of the SLA that has to be retrieved by the repository.
returns: The SLA with the corresponding ID. If no such SLA exists in the repository, a XML error
message with enclosing <error></error> tags is returned.
6.1.1.157.2 string getStatus(string SLA_id)
Returns the string representation of the current status of a specific SLA


SLA_id: The identifier of the SLA whose status should be returned.
Returns: The string representation of the current status of the SLA.
6.1.1.157.3 bool setStatus(string SLA_id, string status)
Sets the status of a SLA being already stored in the repository to a specific value.



SLA_id: The identifier of the SLA whose status should be set.
status: The string representation of the status that should be set for a specific SLA
returns: true if status has been set and stored to the repository, false otherwise.
Page 204
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.157.4 bool storeSLA(string SLA_id, XmlDocument SLA_document, string status)
Stores a SLA with unique identifier and status information in the repository




SLA_id: the unique identifier for the SLA document
SLA_document: the SLA document that has to be stored in the repository
Status: the string representation of the current status information of the SLA document
Returns: false if the identifier is already in use (overwrites the content!), true otherwise.
6.1.1.157.5 string storeNewSLA(XmlDocument SLA_document)
Generates a new, locally unique identifier for the corresponding SLA document and stores it under
this identifier in the repository.


SLA_document: The SLADocument that has to be stored in the repository.
Returns: The identifier being created and associated with the given SLADocument.
6.1.1.157.6 bool initRepository()
Initializes the database used by the repository. In particular all old tables being used by the
repository are dropped and recreated. This method has to be called before the first usage of the
repository.

Returns: true if the initialization of the database has been processed successfully, false otherwise.
6.1.1.157.7 bool setupRepository(string SLA_ID)
Allows the easy setup of the repository with predefined SLA documents for testing purposes.


SLA_ID: The identifier of the SLA document that should be stored in the repository. This
document has to be placed at the following location: "c:\trustcom\SLA\" + SLA_ID +
".xml". E.g. if you want to load the SLA document “c:\trustcom\SLA\sla0010.xml” in the
repository, you have to call this method as follows: setupRepository (sla0010)
Returns: true if the SLA has been stored successfully in the repository, false if an error
occurred during the storing process or if the SLA with the same identifier has already
been stored in the repository.
6.1.1.158 Ganglia Service
This component acts as a Webservice-Wrapper for the locally installed Ganglia system. Beside the
webservice interface this component also provides an internal SLA document parser to extract and
map the parameters that has to be monitored by the local ganglia system.
6.1.1.158.1 bool initGangliaWSLAMonitor(string sla_ID, XmlNode wsla_doc)
Initializes the Ganglia Monitor by parsing the given SLA document and thereby extracting the
parameters that have to be monitored by the entire Ganglia system. These extracted parameters are
associated with the given SLA ID, so it is possible to setup the Ganglia Monitor with several SLAs.



sla_ID: The identifier of the corresponding SLA document.
wsla_doc: The SLA document to be used to initialize the Ganglia Monitor.
Returns: true if the initialization of the Ganglia Monitor was completed successfully, otherwise an
Exception is thrown. The main reason for the latter case is an invalid SLA document being passed to
this method.
Page 205
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.158.2 void setGangliaHost(string wslaID, string ganglia_host, int ganglia_port)
Sets the Ganglia host and port. If you use the default settings of your Ganglia System, you do not
have to modify this settings in the Ganglia Monitor at all.



wsla_ID: The identifier of the corresponding SLA
ganglia_host: The name of the Ganglia Host System
ganglia_port: The port of the Ganglia System.
6.1.1.158.3 void setMonitoredHostID(string wslaID, string host_id)
Sets the host ID of the monitored system.


wslaID: The identifier of the corresponding SLA document
host_id: The name of the host system to be monitored.
6.1.1.158.4 XmlNode getMonitoredWSLAData(string wslaID)
Get the monitored values for specified SLA document.


wslaID: The identifier of the corresponding SLA document
returns: A XML representation of the monitored data
6.1.1.158.5 GangliaScheduleData getScheduleData(string slaID)
Returns the current schedule settings fort he coreesponding SLA.


slaID: The identifier of the corresponding SLA document / setup.
Returns: The schedule setting of the corresponding SLA document.
6.1.1.159 SLAMonitoringDaemon
This component acts as a standalone-program. After the setup of the SLA Manager the
corresponding monitoring data has to be sent out considering the defined schedule interval in the
corresponding SLA document. Therefore a new daemon process is started sending out the
corresponding status notifications. Therefore the SLAMonitoringDaemon subscribes itself as a
producer for the topic
“SLA_statusupdate”. This daemon is realized with the SLAMonitoringDaemon. The executable file
can be found at C:\TrustCom\SLAMonitoringDaemo\SLAMonitoringDaemon.exe.
The SLAMonitoringDaemon is called as follows:
SLAMonitorindDaemon.exe –slaID id

id: The identifier of the SLA that has to be monitored.
TrustCom Policy Server
Installation Guide
There are two steps to the installation of the TrustCom Policy Server, installing the Policy Server
itself and installing a service into Tomcat/Axis to be able to register as a receiver of TrustCom
Notifications from the Notification Broker.
Page 206
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.160 Package Contents
Unpacking the PolicyServer.zip file produces the following top-level files and directories:
Name
Type
Description
BTLibMuse/
Directory
Library files for interaction with BT‟s PEP
HowTo.txt
File
Basic instructions to get you going
PSlibs/
Directory
Library files containing the Policy Service
code itself
PSxml/
Directory
XML code to test the Policy Server
installation and the interaction with other
TrustCom components
Proxylibs/
Directory
Installation package to enable the Policy
Service to receive notifications from the
trustCom Notification Broker
Review/
Directory
Script files used for the review
SICSlibs/
Directory
Library files to enable the Policy Service to
interact with the SICS PDP
SICSxml/
Directory
XML used by the Policy Service to clear the
SICS PDP
STDlibs/
Directory
Open source library files used with the
Policy Service
Testbed/
Directory
XML to drive the Policy Service for use with
the TestBeds
TrustCom
Sources/
Directory
All the source files for the TrustCom Policy
Service
TrustComPS.jws
File
Java file to connect the Notification Broker
end point to the Policy Service
build.xml
File
Ant script to test and run the Policy Service
docs/
Directory
Full installation and running documentation
written as a set of web pages
pssend*
File
A Unix script to enable any program to send
XML commands to the Policy Service
pssend.bat*
File
A Windows script to enable any program to
send XML commands to the Policy Service
src/
Directory
All the sources in one file
6.1.1.161 Requirements
The Policy Service requires Java 1.5 or later to be installed. It runs on any version of Linux,
Windows and Mac OS X that supports Java 1.5. Apache Tomcat and Axis are required on the same
machine to interact with the TrustCom Notification Broker.
Page 207
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.162 Installation
There are two steps to the installation of the TrustCom Policy Server, installing the Policy Server
itself and installing a service into Tomcat/Axis to be able to register as a receiver of TrustCom
Notifications from the Notification Broker.
6.1.1.163 Installing the Web Services Interface in Axis
The Policy Server can accept Web Service calls, either from another Policy Server or from an
external program which wants to configure the Policy Server. It can also receive external events via
a Web Service call.
To receive Web Service calls, the Policy Server uses an Apache Axis service which communicates
with the Policy Server using Java RMI.
The Web Service interface for Axis used a .jws file call TrustComPS.jws. This file must be placed
into the Axis main directory.
This is normally under the TomCat installation in
.../tomcat/webapps/axis. The following commands assume a Unix system.
$ cp TrustComPS.jws /somewhere/tomcat/webapps/axis/TrustComPS.jws
The TrustComPS.jws file is the Web Service entrypoint for Web Service calls to the Policy Server. It
communicates with the Policy Server using RMI and therefore requires the Policy Server's RMI
interface to be available in the axis library. Knowledge of the interface is set up by copying the
TrustCom Policy Server JAR file to the Axis lib directory. For example:
$ cp PSlib/trustcom.jar /.../tomcat/webapps/axis/WEB-INF/lib
These instructions assume that your axis server is at http://localhost:8080/axis/. If this is not the
case then the build.xml file must be edited to reflect the correct address and other instructions in this
documentation must be changed accordingly. e.g. change:
<property name="epr"
value="http://localhost:8080/axis/TrustComPS.jws"/>
to
<property name="epr"
value="http://localhost:8180/axis/TrustComPS.jws"/>
Restart
the
Axis
server
and
test
the
new
service
by
going
to
page
http://localhost:8080/axis/TrustComPS.jws you should see a message telling you
that there is a "Web Service here." Click on the WSDL link and you will get a page with the WSDL
for the service on it. If running Safari, you will see a blank page and will have to use the View
Source menu item.
From now on, if you want to run the Policy Server so that it can receive Web Service or RMI calls
you must start it using the command
Page 208
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
$ ant -Drmi=true
You should get the following output if the Policy Server sucessfully registers its RMI name (make
sure that rmiregistry is running):
[java] Shell: trying port 13570
[java] My WS address is http://localhost:8080/axis/TrustComPS.jws
[java] Shell port 13570 ready
You can test the setup by leaving the Policy Server running, and in another terminal window enter:
$ ant testws
You should get the following output if it is all working properly:
[java] Test OK
Use ctrl-C to kill the Policy Server.
Note: To use the Policy Server Web Services at any time you must have the Java rmiregistry
running on the same machine as the Policy Server.
6.1.1.164 Running the Policy Server
The Policy Server can be run as either a stand-alone application or can be started within an existing
Java VM. However it is started, there are some simple tests to ensure that it is running correctly.
6.1.1.164.1 Classpath
The classpath should include the jar files from the supplied directories in the following order: PSlib,
BTlibMuse, SICSlib and STDlib.
6.1.1.164.2 Stand-Alone Application
To run the policy server as a stand alone application the ant command can be used. This script sets
up the Java classpath correctly and starts the Policy Server. All the examples here assume that
your current working directory is the Policy Server directory.
NB. Windows users must edit the build.xml file as described at the top. The code base has to
contain the full path name to the Policy Server directory.
To run the Policy Server use
$ ant
to run with RMI use
Page 209
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
$ ant -Drmi=true
to use a Policy Server xml script from the PSxml directory, e.g. PSxml/newtest.xml use
$ ant -Druntest=newtest
to use a Policy Server xml file for any location you can specift the path name using the boot
argument. e.g.:
$ ant -Dboot=PSxml/newtest.xml
6.1.1.164.3 Within a Java VM
All the library jar files mentioned in the psclasspath file must be included for the Policy Server to run
within a VM. To start the Policy Server you need to call the main method from a new Thread
String args[]={"-rmi","-","-boot",
"/PATH/TO/proxytrial.xml"};
org.trustcom.PolicyServer.main(args);
Method calls are available to interact with the Policy Server to create events and policies and to
inject new events.
6.1.1.165 Testing the Implementation
To test the Policy Server open a new terminal session and:
$ telnet localhost 13570
You will get a shell prompt from the Policy Server's built-in shell (but it is not a Unix shell!). Now
enter
$ read PSxml/testsetup.xml
This will load the testsetup XML file which defines some test event types and policies. You can now
create events causing the test policy to be activated. It will simply print something out to show that it
is working.
You can now try creating an event and injecting it into the Policy Server
$ event colourevent red 23
This will print out an alert message and shows you that the policy server is running correctly. You
should see:
Page 210
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
[java]
[java]
[java]
[java]
[java]
[java]
[java]
[java]
event colourevent red 23
Command is event
ObligationPolicy: responding
Obligationpolicy: executing <action>
Received an event with colour=red and intensity=23
</action>
Received an event with colour=red and intensity=23
Received an event with colour=red and intensity=23
An easier way of starting the policy service so that it reads its configuration XML file immediately is
$ ant -Druntest=testsetup
Note: Please ignore the duplicated line in the above output, it is only executed once!
User‟s Guide
This section is designed for the user to be able to interact with a running Policy Server. The section
above describes the various options available for starting the service running.
6.1.1.166 Sending XML to the Policy Server
XML can be sent to the Policy Server from a stand-alone application, from a direct Java call, a Java
RMI call or a Web Service call.
6.1.1.166.1 Stand-Alone Application
XML can be sent to the PolicyServer using a simple application embedded within the Trustcom Jar
file. This application uses Web Services to make the call so the receiving Policy Server must have
already been set up to use Web Services. The execution takes the format:
java -classpath trustcom.jar... org.trustcom.comms.XMLRemoteWSClient epr
execute [file]
where ... indicates many Jar files and the file argument is optional, don't include the "[" and "]"
characters. If a file name is there, XML is expected and it is sent to the Policy Server. If a file name
is not included then the XML for the command is taken from standard input. See examples below.
This example expects that a Policy Server has been started as detailed in the Web Services section
i.e. using
ant -Drmi=true
There are two basic commands available, one to send XML to the Policy Server and one to send an
Event within the Policy Server. First we will send some XML through to create an event and a
policy, then we will send an event to trigger the policy.
The library setup is a little complicated so scripts have been included to facilitate the use of this
method. On Windows the pssend.bat script can be used and on Unix the shell script pssend is
available. So, to setup an Event and a Policy and to send such an event we can execute:
Page 211
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
pssend execute PSxml/testsetup.xml
pssend execute < PSxml/sendevent.xml
The second example uses standard input instead of opening a given filename. If something goes
wrong then pssend will exit with a return code of 1 and will print a short error message.
NB.
The
above
assumes
that
you
are
using
an
epr
of
http://localhost:8080/axis/TrustComPS.jws, if this is not the case then the file
pssend or pssend.bat must be edited.
6.1.1.166.2 Java Call
If the Policy Server is running in the same VM as your Java application then you can send an XML
string with the call:
Util.Parse("<use name=\"...\"><more xml=\"ok\"/></use>");
This call returns a string which may have an error message if something went wrong. The method
definition in the Util class is
public static String parse(String xmlString);
6.1.1.166.3 Java RMI
If the Policy Server is running within another VM on the same or different machine then RMI may be
used to send it XML:
XMLRemoteInterface remotePS =
(XMLRemoteInterface)Naming.lookup("//localhost/"+rmiName+port);
result = remotePS.execute(xmlMessage);
So for the above XML you can use:
result = remotePS.execute("<use name=\"...\"><more xml=\"ok\"/></use>");
The RMI method definition is
public String execute(String xmlString) throws RemoteException;
The TrustComPS.jws file may be inspected to see an example of the RMI call in action with its
surrounding try/catch clause.
Web Service
The Policy Service can have XML commands and events sent to it using Web Service calls via
Page 212
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
TrustComPS.jws. The Java signatures are shown here but if you use a different language then refer
to the WSDL.
To execute XML use the Web Service call execute with the signature:
public String execute(String xmlMessage)
e.g.
execute("<use name=\"...\"><more xml=\"ok\"/></use>");
To send an event into the Policy Service use the Web Service call event with the signature:
public String event(String eventName, String[] args)
e.g.
event("/Event/ReputationChange", "Fred", 55, 25, "Leave Now");
6.1.1.167 Sending an Event to the Policy Server
Once an Event Type has been created, an event can be generated from a stand-alone application, a
direct Java call, a Java RMI, a Web Service call, from directly executed Policy Server XML or from
the command-line shell
6.1.1.167.1 Stand-Alone Application
An event can be generated in the PolicyServer using a simple application embedded within the
Trustcom Jar file. This application uses Web Services to make the call so the receiving Policy Server
must have already been set up to use Web Services. The execution takes the format:
java
-classpath
trustcom.jar...
org.trustcom.comms.XMLRemoteWSClient epr event eventname arg1 arr2...
where ... indicates many Jar files and one or more optional arguments. You must have as many
arguments as the event in question was defined with.
This example expects that a Policy Server has been started as detailed in the Web Services page
i.e. using ant -Drmi=true
There are two basic commands available, one to send XML to the Policy Server and one to send an
Event within the Policy Server.
The library setup is a little complicated so scripts have been included to facilitate the use of this
method. On Windows the pssend.bat script can be used and on Unix the shell script pssend is
available. So, to send an event one can enter:
Page 213
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
pssend event colourevent red 53
or
pssend /Event/event colourevent red 53
The event name can be shortened to just the name if it is within /Event, otherwise the full path name
as in the second example must be used.
If something goes wrong then pssend will exit with a return code of 1 and will print a short error
message.
Events can also be created within the Policy Server using XML similar to that supplied
(PSxml/sendevent.xml) which can be sent using the special stand-alone application as described in
sending XML. An example of the XML to send an Event can be found below.
NB. The above assumes that you are using an epr of http://localhost:8080/axis/TrustComPS.jws, if
this is not the case then the file pssend or pssend.bat must be edited
6.1.1.167.2 Java Call
If the Policy Server is running in the same VM as your Java application then you can create the
above event with the call:
org.trustcom.Event.SendEvent("/Event/testevent", "red", "53");
This call returns a boolean indicating whether the event was created and sent. The arguments are
the full path name of the event type within the Policy Perver followed by a list or array of String
arguments, enough to satisfy the arguments expected by that event type. The method definition in
the Event class is
public static boolean SendEvent(String template, String... args);
6.1.1.167.3 Java RMI
If the Policy Server is running within another VM on the same or different machine then RMI may be
used to send an event:
XMLRemoteInterface remotePS =
(XMLRemoteInterface)Naming.lookup("//localhost/"+rmiName+port);
result = remotePS.event(eventName, args);
So for the above event you can use:
result = remotePS.event("/Event/testevent", new String[]{"red", "53"});
Page 214
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The RMI method definition is
public String event(String eventName, String[] args) throws
RemoteException;
The TrustComPS.jws file may be inspected to see an example of the RMI call in action with its
surrounding try/catch clause.
6.1.1.167.4 Web Service
The Policy Service can have an event sent to it using a Web Service call. The arguments are the
port number that the Policy Server was started at, the event name and a sequence of string
arguments. See the WSDL for more information.
<wsdl:message name="eventRequest">
<wsdl:part name="port" type="xsd:int"/>
<wsdl:part name="eventName" type="xsd:string"/>
<wsdl:part name="args" type="impl:ArrayOf_xsd_string"/>
</wsdl:message>
6.1.1.167.5 Policy Server XML
An event can be created and sent to a particular managed object using Policy Server executable
XML
<use name="/managed/object">
<event name="/Event/colourevent">
Red<!-- -->
34
</event>
</use>
6.1.1.168 Command Line Shell
After starting the Policy Server and observing the port number that it has started at, you can telnet to
the Policy Server and access its shell command module. The following Policy Server output shows
it starting at socket 13571
Shell: trying port 13570
Shell: trying port 13571
Shell port 13571 ready
So, to access this Policy Server enter the following telnet command in a new terminal window:
$ telnet localhost 13571
The shell may look a little like a Unix shell but it is not as sophisticated. You can now create events
by typing (to the Policy Service shell)
Page 215
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
$ event /Event/testevent Red 34
As a shorthand simplification the /Event/ may be omitted, however if the event type is in any other
domain, the full path name must be used. You can only send simple arguments without spaces
using this method. It is useful for quick testing.
Developer's Guide
6.1.1.169 Policy Server XML
The Policy Server interprets XML as a sequence of statements that identify managed object and
sub-elements of that XML that are to be sent to those managed objects. For example the following
snippet identifies the root domain ("/") and sends it an add command. The add command has its
own structure and information saying what is to be added. From the snippet we can see that the
managed object to be added to the root domain will be called newobject.
<use name="/">
<add name="newobject">
...
</add>
</use>
Typically, sequences of use clauses are interpreted by the Policy Server. To maintain the integrety
of a single XML structure, a sequence of XML statements may be enclosed with in xml tags. i.e.
<xml>
<use ...>
...
</use>
<use ...>
...
</use>
</xml>
Of course, xml tags may be nested, they are only used for grouping and have no other meaning.
A common way to create objects is to use templates and send them a create command. this has to
be wrapped within an add statement adding them to an existing domain if the object is to be refered
to later. e.g. to create a new domain:
<use name="/">
<add name="newdomain">
<use name="/Template/domain">
<create/>
</use>
</add>
</use>
Page 216
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Now to create a policy we can use the following XML found in the policy description. For a more
complete example, the boostrap XML can be inspected.
6.1.1.170 Anatomy of an Event
An Event Type is created from the Event Template. An Event Type is the specification of a
particular event with named arguments. Instances of the Event Type are created and then picked
up by Policies that have "subscribed" to that particular Event Type.
The Event Template is generally located at /Template/Event. An Event Type is created as follows.
To create an Event Type called /Event/testevent that has two arguments, colour and intensity, we
can use the following XML:
<use name="/Event">
<add name="testevent">
<use name="/Template/event">
<create>
<arg name="colour"/>
<arg name="intensity"/>
</create>
</use>
</add>
</use>
We can now create and send an event of this type.
6.1.1.171 Anatomy of a Policy
Policies are the Event Condition Action rules of the Policy Server. A policy is written in XML and
describes the Event Type that it will respond to, the event's arguments that it will use, optional
conditions that must be satisfied and a set of actions to be performed.
A policy, called /Policy/testpolicy, that uses testevent can be described as follows:
<use name="/Policy">
<add name="testpolicy">
<use name="/Template/policy">
<create type="obligation" event="/Event/testevent" active="true">
<arg name="colour"/>
<arg name="intensity"/>
<condition>
<and>
<equals>!colour;<!-- -->red</equals>
<gt>!intensity;<!-- -->34</gt>
</and>
</condition>
<action>
<!-- Add one to a counter managed object -->
<use name="/dom1/counter">
<inc/>
</use>
Page 217
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
</action>
</create>
</use>
</add>
</use>
6.1.1.171.1 Breakdown of Policy XML
Create a new Policy called /Policy/testpolicy
<use name="/Policy">
<add name="testpolicy">
<use name="/Template/policy">
<create ...>
...
</create>
</use>
</add>
</use>
The Policy will be an ECA type policy ("obligation") and it will respond to events of type
/Event/testevent, described here. The Policy will become active as soon as it is created.
<create type="obligation" event="/Event/testevent" active="true">
...
</create>
The policy will make use of two named arguments that the event provides:
<create event="/Event/testevent" ...>
<arg name="colour"/>
<arg name="intensity"/>
...
</create>
Named arguments are substituted as text before the XML action is evaluated by enclosing the
name inside the two characters "!" and ";"
6.1.1.171.2 Condition
The optional condition can contain simple boolean statements comparing string and integer values.
In this case we are checking whether the colour is red and the intensity is greater than 34.
Conditions can contain any combination of and, or, not, eq, ne, gt, ge, lt or le. and and or take any
number of XML sub-elements, not takes one, the others all take two. Note the string substitution of
the arguments colour and intensity. Note also that the arguments for the comparisons have been
separated by XML comments to ensure that they are separate XML elements.
<condition>
<and>
<equals>!colour;<!-- -->red</equals>
<gt>!intensity;<!-- -->34</gt>
</and>
</condition>
Page 218
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.171.3 Action
The action part of the ECA policy is mandatory. It simply consists of Policy Service XML, the only
difference being that execution of the XML is delayed until the Policy's event and condition parts
are satisfied.
<action>
<!-- Add one to a counter managed object -->
<use name="/dom1/counter">
<inc/>
</use>
</action>
6.1.1.172 API Documentation
See supplied JavaDoc files.
6.1.1.173 Example
This example shows how the Review demonstration can be set up and run. The Ant script build.xml
contains all the necessary values for remote EPRs of other TrustCom services and also contains the
arguments to start the Policy Service running.
BT Gateway
Installation Guide
In addition to installing the actual gateway software, the actual gateway needs very careful & specific
configuration before it can be used. We will first address the software installation, and in a later
stage, the configuration. It is paramount the configuration is properly and carefully done.
6.1.1.174 Package Contents
Name
Type
Description
Gateway.war
Web
archive
The web archive is a Java web application
that is packaged in such a way that it can
automatically be deployed. It contains 2
folders: META-INF and WEB-INF. The latter
contains two folders: classes and lib. The
former contains configuration information
and any other item prone to change, the
latter contains the libraries, the application
logic, and other dependencies.
6.1.1.175 Requirements
The gateway depends on the following software, each of which needs to be installed prior to
installing the gateway:
- Java 1.5 and above
- Tomcat 5.5 and above. Apache Tomcat is the servlet container that is used in the official Reference
Implementation for the Java Servlet and JavaServer Pages technologies.
Page 219
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
- MySQL CE 5.0 and above. MySQL is an open source relational database management system that
uses Structured Query Language (SQL).
- OpenSSL 0.9.8. OpenSSL is an open source implementation of the SSL and TLS protocols. The core
library (written in the C programming language) implements the basic cryptographic functions and
provides various utility functions.
19
In addition, there are library dependencies, e.g. Hibernate . However, these dependencies are
already packaged with the gateway application. Henceforth, the user installing the gateway needn‟t
worry about them.
6.1.1.176 Installation
Installing the gateway is easy and straightforward. However, installing the required software and
configuring it appropriately is trickier. In addition, configuring the actual gateway is also non trivial.
For convenience and to guarantee the installation is done with known versions of each software,
one can download the software here.
6.1.1.177 Third party software installation
6.1.1.177.1 Java 1.5
In order to run the gateway, the Java runtime environment must be installed on your system. Make
sure that the binary folder of the JRE is part of your system path once installed. Make sure there are
no conflicting versions of Java installed. Java 1.5 is the strict minimum needed for the gateway to
operate. One dependency on this version of Java is UUID which is a new addition in that version
that Java 1.4 didn‟t have.
You can find the JRE and JDK here.
6.1.1.177.2 Tomcat 5.5
Unzip Tomcat 5.5 to a location of your choice. Make a note of the location here:
My Tomcat location:
You now need to configure the Tomcat administrator user, the ports Tomcat will be using, and
Tomcat‟s reload behavior:
1. Define a new administrator user. In order to do so, go to the conf folder in your Tomcat location.
Locate the tomcat-users.xml. It should contain the “admin” and “manager” roles. In addition these two
roles should be associated to a given user as follows: <user username="admin"
password="bla" roles="admin,manager"/>. A sample file can be found here. This
administrator account is used to login to the manager interface of Tomcat via a browser e.g.
http://localhost:8080/manager/html.
2. Choose a set of three ports to use for your Tomcat installation e.g. 8080, 8005, and 8009 (these are
the default values). 8080 is the port on which Tomcat listens and is what matters most. All these
ports must be available meaning that no other server can run at the same port. In order to change the
port numbers – should you wish to – edit the conf/server.xml file and look for port=”. Replace the
port numbers by the values that you wish to use.
3. Again, in the same file, update the <Host name="localhost" debug="0" element and add the
following attribute: reloadable=“true”. This ensures that configuration changes are applied
19
Hibernate is an Object-relational mapping (ORM) solution for the Java language. It is free, open
source software that is distributed under the LGPL. Hibernate was developed by a team of Java
software developers around the world. It provides an easy to use framework for mapping an objectoriented domain model to a traditional relational database.
Page 220
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
dynamically and do not require server restart. Effectively the reloadable attribute ensures the web
application is reloaded when a change occurs.
Your Tomcat server is now ready to use. To run it, create a simple batch file containing the following
lines:
set CATALINA_BASE=D:\server\registry-tomcat
set CATALINA_HOME=D:\server\registry-tomcat
set CATALINA_TMPDIR=D:\server\registry-tomcat\temp
"%CATALINA_HOME%\bin\startup.bat"
Of course, you need to replace the path aforementioned with the actual path to your Tomcat
installation.
6.1.1.177.3 Installing OpenSSL
You can find the version of OpenSSL used in the gateway here. It‟s a Windows installer. It is
straightforward. All you need to specify is standard Windows information such as folder where to
install OpenSSL, whether you want a Program group in the start menu, and so on.
One you‟ve installed OpenSSL, make a note of the folder where it was installed:
My OpenSSL directory:
Make sure that you now have access to the openssl binary from anywhere in your system i.e. open
a windows command prompt and type openssl. If it opens an openssl shell, then congratulations. If
Windows complains that it doesn‟t know what OpenSSL is, make sure your Windows path includes
the path to the binary folder of your OpenSSL installation.
6.1.1.177.4 Installing MySQL
MySQL comes with a Windows installer that will guide through the installation steps. Make sure to
note the administrator user name (typically root) and its password. Note it here:
My MySQL username:
password :
Make sure that MySQL runs as a service and that it is automatically started when you log into
Windows. Otherwise, you will need to make sure MySQL is running prior to starting the gateway.
The username and password noted above are only used to create the gateway database and user.
6.1.1.178 Installing the gateway
As aforementioned, installing the gateway in itself isn‟t difficult. However, properly configuring it can
be quite tricky. Let‟s get started!
We‟ll assume here that Tomcat is running at localhost on port 8080. We‟ll also assume MySQL‟s
root account is root identified by the password bla.
6.1.1.178.1 Deploying the web application
Gateway.war is the web application file. There are two possible ways to deploy it:
1. via the web interface. Go to http://localhost:8080/manager/html; this will prompt you for a username
and password: these are the Tomcat administration credentials set up in [6.1.1.177.2 Tomcat 5.5].
Page 221
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Once logged in, look for the Deploy section and in particular the WAR File to deploy subsection:
Figure 60 - Uploading the web application to the server
2. Click on browse to select the war archive to upload and deploy.
3. Alternatively, simply copy the gateway war archive to the webapps folder of your Tomcat installation.
It will then be deployed automatically.
Congratulations, you‟re 90% installed! The web services are up and running, the gateway
application is up and running too. However, they need a database in the background to store and
fetch data. We‟ve already installed the database engine, MySQL, so let‟s now install the database
itself.
6.1.1.178.2 Installing the gateway database
SQL is the language used to create and access databases. Each database engine has got its own
variant of SQL albeit the different flavours are almost all equal.
The gateway release comes with an SQL script that creates (a) a gateway-specific user in order to
access the database engine, and (b) the actual database with no initial dataset: the database is
therefore empty.
To run the script, follow these instructions.
Download the database creation script from here to a location on your system, e.g. c:\temp
Open a command prompt
Browse to the folder containing the database creation script e.g. c:\temp
Type mysql –uroot –pbla where root and bla are the username and associated password of the
root account of your MySQL installation. In order for this to work the binary folder of your MySQL
installation must be in your system path. Otherwise, you will need to specify the full path to your
MySQL binary.
5. Once inside the MySQL prompt, type source instantiator_db_commentless.sql where the
argument is the name of the file.
6. You‟ve now successfully installed the gateway registry database.
1.
2.
3.
4.
6.1.1.178.3 Creating and Browsing the Initial dataset
A. Federation Profiles
The gateway is all about exposing services as virtual resources within one given context, called in this
case federations although the actual federation (as in the trust federation) is only one part of what is here
called federation (an ensemble of infrastructure services configurations).
So prior to creating any federations, one may want to use a federation template, i.e. a profile defining a
set of default values for the infrastructure services available e.g. PEP, PDP, and so on.
Page 222
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Take your browser to http://localhost:8080/gateway/servlet/FpBrowser. The page displays a list of
available infrastructure profiles to be used when creating a new federation. Having such profiles removes
the hassle of specifying the addresses of PDPs, PEPs, STSs for the federation creation initiator. All they
have to do is specify a new federation id and federation profile. Better yet they can rely on the default
federation profile and not specify one at all (See p. 225, paragraph C, Gateway Federation Manager
Configuration). Here‟s a screenshot of the profile manager:
Figure 61 - Adding a new federation profile to the gateway registry
Note that the GVOA and SLA fields are no longer used and that therefore their values are not taken into
consideration.
B. Services.
Obviously since the gateway‟s aim is to virtualize services, one needs to define them beforehand. This is
done in the local service registry. Again, the service browser and editor is a servlet exposing a webpage
(See screenshot hereafter). In the current version of the gateway, the only services that can be virtualized
are simple web services (excluding WSRF-enabled web services and those services requiring specific
headers). A service‟s registration contains the internal URI where the service can be found, a name, a
type which a human-readable type, and a role (either requestor / receiver or both). A requestor is a
service issuing a request e.g. a client; a receiver is a service acting as a request processor. Once you‟ve
defined one or more services, and at least one federation profile, you‟ve setup the minimal dataset.
Page 223
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 62 - Adding a new service to the gateway registry
6.1.1.178.4 Initial gateway configuration
Navigate to http://localhost:8080/gateway (replace localhost and 8080 with the appropriate values).
Click on Gateway Configuration Page. This should take you to a page containing three configuration
sections. Let‟s go over them one by one to make sure the right details are fed in:
A. Gateway Infrastructure Configuration
This section focuses on the overall gateway configuration. It contains default infrastructure configuration
as well as other parameters:
a. Default infrastructure configuration
i. pdp : the address of the default policy decision point to be used during the
virtualization process if no other PDP has been given. For more information about
the gateway see the SICS PDP documentation.
ii. ps : the address of the policy service. However in this version of the gateway, it is
unused and can be left blank.
iii. Pep: this refers to two endpoints: the URI of the management service as well as the
URI of the operational interface of the PEP e.g.
pep.mgmt=http://localhost:6060/mwsng/services/WsResourceFactory
pep.oper=http://btg172269:8080
iv. The STS section (security token service) also contains two endpoints, one for the
management interface, the other for the operational interface. In addition it contains
the path to a crypto property file ( a file used by the wss4j cryptographic library)
which defines which certificate should be used to communicate with the STS
sts.mgmt=http://localhost/TrustCoM/STSv2/ManagementX509.ashx
sts.mgmt.cryptoConfig=crypto/mgmt.crypto.properties
sts.ops=http://localhost/TrustCoM/STSv2/STSX509.ashx
b. Token generator configuration
i. tmp.dir: where to temporarily store the tokens created on the fly
ii. caCert: the absolute path to the X509 certificate of the issuing certificate authority
iii. caKey: the absolute path to the private key of the issuing certificate authority
iv. caPwd: the password protecting the private key of the CA
v. keySize: the key size to be used when generating a new key pair for the certificateto-be
vi. days: the lifetime of the certificate-to-be
vii. keyPwd: the password protecting the private key of the certificate-to-be. It cannot be
null.
c. Other
i. checkXacml: this tells the instantiation process whether it should check incoming
XACML claims when instantiating a requestor. For a fully automated process, set this
Page 224
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
value to false. If you set it to true, each client instantiation will halt and the gateway
administrator will be prompted to analyze the claims before approving / declining the
instantiation request.
B. Gateway Proxy Configuration
Because the gateway can run in a network that is separated from other networks by means of a proxy, it
needs to be made aware of that proxy domain and port. Should the gateway needs a proxy (e.g. if it‟s not
sitting in the same network as the STS, PDP, or PEP), specify it here.
C. Gateway Federation Manager Configuration
Lastly, the gateway federation manager requires a minimal configuration. Firstly, it needs to know which
credentials to use to communicate with the STS. This is specified in the wss4j property file specified by
the attribute fedManager.default.federationProfile.id. Secondly, a default federation profile
id must be given. In the previous section, we entered one (or more) federation profiles. Now‟s the time to
choose either of those profiles, copy their id and paste here. It will be used as a default profile whenever
the gateway receives a federation creation order without any specified profile.
User‟s Guide
This section focuses on how to make use of the gateway. It is an introduction to the gateway clients,
their use, and their aim.
6.1.1.179 Gateway Interfaces List
There are 3 main web service interfaces each of which have a client associated to them. Of course,
one can develop their own client in whatever technology they fancy. In the case of the gateway, two
.NET Win32 applications have been developed for the 2 main interfaces: the federation manager
and the instantiator. The third client is a servlet exposing a web page with a form. To sum up, the
three main interfaces are:
-
-
-
Gateway instantiator
o Axis 1.4 web service
o Windows 32bit .NET application
Gateway federation manager
o Axis 1.4 web service
o Windows 32bit .NET application
Gateway Registry Service Manager
o Axis 1.4 web service
o Java servlet exposing a webpage with an HTTP form.
All this is further detailed in the Developer's Guide.
6.1.1.180 Gateway Federation Manager Client
6.1.1.180.1 Requirements & location
The client can be downloaded here. It simply requires Windows 32bit (e.g. XP). In addition the client
can be configured to run behind a proxy. In order to do so, edit the configuration file included in the
zip file: gatewayclients.exe.config. Look for:
<system.net>
<defaultProxy>
<proxy proxyaddress="http://myproxyhost.com:8080"/>
</defaultProxy>
</system.net>
And amend, comment out or remove altogether accordingly.
Page 225
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.180.2 Overview & screenshots
Figure 63 - Configuring the gateway federation
manager client
In the first tab, one needs to specify to which
federation manager the client should connect to.
This is the address of the federation manager
service in the gateway. To determine this go to
http://localhost:8080/gateway/servlet/AxisServlet
and click on FederationManager (wsdl). The URI
displayed in the browser minus the ?wsdl is the
location of the service
Figure 64 - Browsing the list of available
federations in a gateway
This tab lists all the available federations.
The listing happens automatically upon
clicking the “Federation List” tab. Therefore
the view is always refreshed. Note that this
reflects the contents of the gateway
registry and bears no guarantees that the
other infrastructure services actually
contain those federations (namely the
STS).
Selecting a cell by simply clicking on it then
copying by pressing Ctrl+C copies the
contents of the cell to the clipboard.
Double-clicking on any one line will take
the user to the third tab “Federation
Details”. See below.
Page 226
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 65 - Exploring a federation with the gw
federation manager client
Figure 66 - Adding a new federation with
the gw federation manager client
This tab must never be accessed directly as the
information it contains is only relevant if it has
been called through double clicking the
federation list. By doing this you are querying the
gateway federation manager service for the very
latest information.
Use this tab to add a new federation view.
You can use the random id button to
generate a new id. This is clientside
functionality: it does not call the gateway.
The textbox is masked to a UUID and will
complain should the contents not comply.
You can add here the partner business cards.
Add in the owner business card the “self”
business card e.g. in this case Venus. The other
function “Add Partner” is to add other business
cards of course.
Adding a business card that has already been
added will result in an exception of the type
“cannot add partner as it‟s already a member of
the federation”. Note that the STS doesn‟t throw
such an exception. It merely replies that it‟s
already got the partner. The gateway registry is
the one complaining.
The Partners part of the GUI is graphically
bugged but doesn‟t affect its actual functionality.
Possible exceptions are:
-
Could not talk to the STS
Federation id is already taken
Possible exceptions later on as a result of
misconfiguration:
-
Federation not enabled (you need to do that
in the other tab)
Missing partner
The adding of the federation when
successful takes you to the Federation List
tab where you should double click on the
newly created federation to edit its details
(enable + partners).
The status checkbox reflects the current status
of the federation.
The messages tab is used to display exceptions. Never go there yourself. Only take into account the
exception if automatically taken to that tab (in other words, the tab is never cleared therefore the
trace of an exception will stay although there may be no exception anymore).
Page 227
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
The exception received is the one computed by the Gateway Federation Manager. For instance it
can tell that the STS was not configured. The most typical reason as said is that you‟re using the
wrong endpoint. Other reasons are that the federation already exists at the STS (it can normally
happen although generating 2 identical UUIDs is very bad luck and per definition nearly impossible).
6.1.1.180.3 Missing functionality
The user cannot:
-
delete federations
update federations (i.e. change anyone of the infrastructure endpoints)
6.1.1.181 Gateway Instantiator
Once you‟ve added a federation, you may want to add a service instance (aka a virtual resource).
6.1.1.181.1 Requirements & location
The client can be downloaded here. It simply requires Windows 32bit (e.g. XP). In addition the client
can be configured to run behind a proxy. In order to do so, edit the configuration file included in the
zip file: gatewayclients.exe.config. Look for:
<system.net>
<defaultProxy>
<proxy proxyaddress="http://myproxyhost.com:8080"/>
</defaultProxy>
</system.net>
And amend, comment out or remove altogether accordingly.
6.1.1.181.2 Overview & screenshots
The instantiator client follows a similar layout as the federation manager client.
Figure 67 - Instantiator Client Configuration
Set here the service endpoint. Any wrong endpoint will throw an exception and display a message in
the error tab. To locate the URI of an instantiator service, follow the same technique as described in
[Gateway Federation Manager Client].
Page 228
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 68 - Instances browser (Instantiation client)
This tab lists the currently present virtual resources at the gateway. The Internal Address column
contains the internal EPR of the capability instance whereas the yellow part below contains the EPR
of the virtual resource. To display that EPR double click on the line for which you wish to get the
virtual EPR. Make sure you have double clicked correctly and that the EPR displayed is the right
one. This tab is known to bug when calling the refresh list too often (or after a certain period of time).
The only solution is to close and restart the application.
Page 229
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Figure 69 - Add a new instance (Instantiation client)
This GUI allows the user to add new virtual resources. It‟s handy to have the federation manager
client at hand as well in order to copy the federation ID as well as the PEP Operational endpoint
which is the basis for the logical address (the virtual URI).
Never use Both in the GUI as the functionality hasn‟t been tested in the scope of WP34. The service
field expects a URI which refers to an internal service. So it‟s handy to have the service browser
open in a browser window.
Figure 70 - Error tab in the instantiation client
This tab works in the same way as the gateway federation manager client tab. Never go there
yourself. If an exception occurs you will be taken there automatically. The form is never cleared. An
old exception will stay there until a new one comes.
Page 230
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.181.3 Missing functionality
One cannot edit instances, one cannot delete instances. In addition one cannot add XACML claims
to a client instance. Instead, this has to be done via the STS client interface (see the STS
documentation).
Developer's Guide
6.1.1.182 BT Gateway Design & Specification
Please see the Gateway Architecture Overview. In addition, the following documents bring further
details:
-
Gateway Instantiator
Gateway Federation Manager
6.1.1.183 API Documentation
Please see the Gateway Javadoc.
6.1.1.184 Example
We‟ll assume that we‟ve got the following initial datasets installed:
Service:
-
Name: Weather service
Type: Meteorological
Role: Receiver
Internal address: http://localhost:80/weather/dew.asmx (note this is not necessarily a service hosted
by Tomcat where the gateway‟s running)
To get this data into the gateway, use the service browser you can find here.
Federation profile:
-
id: automatically generated by the page, e.g. 556146b1-ca1d-40ca-994f-45f675bdaa94. Make sure
you update the gateway configuration accordingly should you wish to use it as the default profile
name: weather federation type
PEP Mgmt EPR: http://localhost:6060/TioPepe/services/PepMgmt
PEP Operational EPR: http://localhost:6000/. Note that this will be a subset of the operational
endpoint of your virtual resource
STS Mgmt EPR: http://localhost/reviewsts/ManagementX509.ashx
STS Ops EPR: http://localhost/reviewsts/STSX509.ashx
PDP EPR: http://mypdp.com/pdp
6.1.1.184.1 Creating the federation
Connect to http://localhost:6060/gateway/services/FederationManager with the Gateway Federation
Manager Client. Click on the Add Fed tab. Then click on Random id and then ok. Provided you‟ve
given a valid STS URI, the federation creation should work smoothly. If the IIS server where the STS
is running has just been started, its response may be slow enough to trigger a time out exception.
No worries: try again.
Once the federation has been created, go to the federation list (if you haven‟t been redirected
automatically) and double click on the newly created federation. This takes you to the details page.
Click on Enabled to change its state. Then add an owner and one or more partners. You can find
sample business cards here.
You‟re now ready to move to the instantiation phase. Wait, don‟t close the federation manager as
you‟ll need to copy the federation id over.
6.1.1.184.2 Creating the instance
Page 231
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Go straight to the add new instance tab – after, of course, you‟ve connected to the appropriate
service – and start filling in the data required. Put in the federation id that you used in the previous
step.
Also copy the PEP operational endpoint which should be http://localhost:6000/ according to our
initial dataset in the logical address field. Append anything you like to it e.g. myVirtualResource:
http://localhost:6000/myVirtualResource. Type the business key of the owner of the federation in the
corresponding field. You need to have a look at the business card you uploaded as owner and
check its business key. Check consumer or producer, and then create.
You should be now finished.
6.1.1.184.3 Now what?
Well, the gateway without a PEP, STS, and PDP isn‟t very useful. Effectively, the gateway mostly
interacts with the lifecycle of resources as opposed to the PEP which mostly deals with the runtime
of resources. Configured infrastructure is only useful if tried out. Your next logical step is therefore to
try out the PEP.
Policy Enforcement Point
Installation Guide
The enforcement runtime comes in a distributable zip archive including the requried libararies and
an ant build file. Prior to execution the JCE unlimited strenght extensions must be installed and the
enforcement runtime needs to be configured to its environment.
The enforcement management services comes as a distributable war archive that can be droped in
a J2EE container such as tomcat. No further steps required.
6.1.1.185 Package Contents
Name
Type
Description
enforcement02-04.zip
Archive
Enforcement runtime
Mwsng.war
Web
Archive
Enforcement management service
6.1.1.186 Requirements
The
PEP



is
a
java
application
and
has
following
requirements.
JAVA 1.5 with unlimited JCE strength extensions
Tomcat (version 5.5 or higher)
Ant (version 1.6 or higher)
It requires the following other trustcom components



BT gateway
EMIC Security Token service
SICS Policy Decision Point
Page 232
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.187 Installation
For installation of the required components please refer to their corresponding documentation.
6.1.1.188 Install Enforcement Management Web service
Simply drop the mwsng.war archive into tomcat
6.1.1.189 Installation of Enforcement Runtime
6.1.1.189.1 Extract the zip file
6.1.1.189.2 Adjust to environment
This is done via the transport.properties file in ./etc/cfg. The transport.lstPort needs to be adjusted to
the port number the PEP should be listing on for application messages and the
enforcer.config.locator properties needs to be set to the directory where the configurations produced
by the enforcement management service are stored. Finally application services to protect need to
be configured to use the transport.lstPort as their http level proxy.
User‟s Guide
The application is not intended to be used by users, but by applications. What follows is a
description of how application services use the pep to protect messages.
Company A and B have agreed to collaborate. This document assumes that certain steps
that are covered by the BT gateway component have already been carried out. We assume
the federation has already been established (STS deployed, business cards exchanged
and installed) and that the WS-Addressing enabled services have been created and
instantiated at two machines in company A and B (policies have been uploaded to pep,
pdp & sts) and that the services are configured correctly to use their corresponding PEP as
http proxy.
Further we assume a basic synchronous interaction with a request / response message
exchange pattern. We assume that the client at organization A is invoking the service at
organization B.
The application service messages are required to include a To and a From EPR in the
messages being exchanged. These EPRs have to confirm to the structure described
below.
<wsa:EndpointReference
xmlns:wsa =http://schemas.xmlsoap.org/ws/2004/08/addressing
xmlns:emic=http://www.microsoft.com/emic/SAFe/
xmlns:emicfpi=http://www.microsoft.com/emic/SAFe/#FederationPartners
xmlns:uddi="urn:uddi-org:api_v2">
<wsa:Address>http://demo/services/VersionClient</wsa:Address>
<wsa:ReferenceProperties>
<emic:FederationUUID>
07b7031c-b5c3-04f2-04ae-8254c3045bae
</emic:FederationUUID>
Page 233
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
<emicfpi:FederationPartnerIdentifier >
<uddi:businessKey >
00000000-0000-0000-0000-000000000001
</uddi:businessKey>
</emicfpi:FederationPartnerIdentifier>
</wsa:ReferenceProperties>
</wsa:EndpointReference>
The non – standard part are the two reference properties emic:FederationUUID and
emicfpi:FederationPartnerIdentifier that define the context of this message by specifying
the federation and partner identifiers that the EPR corresponds to.
Developer's Guide
6.1.1.190 Enforcement Runtime (Proxy Server)
6.1.1.190.1 Description
The proxy server intercepts HTTP messages processes and forwards them again. It can be
configured to execute a set of Interceptors prior to a message is received and returned from the core
Proxy Service. The proxy service forwards the message to the intended destination. It has a basic
threading model that ensures that each request is handled by a separated Connection Processor
Thread that has his own copy of the interceptors and the transport service.
6.1.1.190.2 Tasks



Intercepts the message, extracts the payload, extract EPRs, query registry, locates policy
Logs messages prior to forwarding and after receiving responses to those requests
Ultimate error handling, wrapping SOAP errors in HTTP
The following diagram describes the packages, classes and their relationship in the proxy server
Illustration 1: Class diagram of proxy server implementation
Page 234
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.190.3 Description of implementation
Package: com.bt.gw.http
This package deals with HTTP connection handling. It is based on the samples provided with the
httpCore package. It contains an http server implementation, that is used to intercept requests, and a
http client implementation that is used to make requests to the intended destination

HttpServer: Responsible for starting the process. It is passed a property files as an argument
(transport.properties) which it parses and makes accessible to other objects through a static
method. The last thing it does is creating and starting a new RequestListenerThread.

RequestListenerThread: Holds the ServerSocket object and HttpParams objects. The run
method of the Thread contains a loop that is running unless thread gets interrupted. Run()
first makes a call to ServerSocket.accept() which blocks further execution until
something connects to this socket. When a connection is accepted, it creates a new
HttpServerConnection and binds the HttpParams to this connection. It then creates a new
ProxyService object and loads the required HTTP Protocol and custom interceptors (this
includes
the
[Request|Response]PayloadProcessors)
and
spawns
a
new
ConnectionProcessorThread passing the ProxyService as Service used to process this
connection.

ConnectionProcessorThread: run() method loops and calls the passed HttpService's
handleRequest() method. The loop only ends when it gets interrupted externally, or the
HttpService finsihed processing a request and is no longer active.

ProxyService: doService() method is executed from within superclass HttpService's
handleRequest() method after the loaded interceptors have executed in
preprocessRequest(httpRequest,httpContext). This method first determines
the transport address used to send the message to. The precedence is the requestLine of the
original request, overwritten by the transport.address header as used by the enforcement
package which can again be overwritten by the transport.fwdHost and transport.fwdPort
fields in the transport.properties config file. The transport adress URI passed to a newly
created HttpClient. Next it calls the client’s executeRequest(httpRequest) method
and updates the entity transported in the response with the responsed the recieved from the
HttpClient

HttpClient: makes a POST request to a given URI. The payload is set by ProxyService by
what it has in its HttpRequest entity at the time of the doService() method call (updated
payload). Within its executeRequest(httpRequest) method, the client determines
its proxy settings and copies a selection of HTTP Headers from the initial request recieved
into the new request.
Package: com.bt.http.gw.interceptors:
This package contains the interceptors that are dealing with logging and processing the message.
The PayloadProcessor interceptor engages the enforcement engine with the current payload of the
message.

RequestDumper: extracts the payload and stores it in the HttpContext object from where
every other interceptor reads it. Additionally it dumps the whole request into a file called
request.txt.

RequestPayloadDumper: Dumps the payload of the request it obtains from the HttpContext
Page 235
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
object as an xml document to request-payload.xml

RequestPayloadProcessor: First it reads payload from HttpContext. Then it tries to determine
the base directory for the configuration. Therefore it reads the values
enforcer.config.basedir and enforcer.config.locator fields from
transport.properties. If enforcer.config.locator is set it queries the internal
database for the matching UUID for this endpoint and appends it to the basedir value. Then
this directory is added to the thread’s classpath to make it accessible for the enforcement
component which uses it for loading policy and certificates. It creates a new GenericChain
and calls chain._invoke(cfgBaseDir,data). Finally it obtains the transport
Address from the state bean and sets the Http Header field transport.address and updates the
current request with what the chain returned.

ResponseDumper: dumps response to a text file (response.txt), does not populate any context
attributes yet, would need to populate the payload (in order to process response) and the
configDir (in order to have different enforcement engine configuration for response)

ResponsePayloadDumper: see RequestPayloadDumper

ResponsePayloadProcessor: see RequestPayloadProcessor
6.1.1.190.4 Forwarding Algorithm
The proxy service determines about where to forward the request based on the following
algorithmus. First it will use the URI information in the request line. The second location it looks for
the forward address is the transport.address header, that is used by the RequestPayloadProcessor and
contains any transport address as returned by the enforcement engine. This value overwrites what
existed previously. Finally it inspects the transport.forward.host and transport.forward.ports
properties from the configuration file. If these values are set they overwrite anything that existed
previously.
6.1.1.190.5 Log files



Request.txt / response.txt contain the unmodified http message as received / returned
Request-payload.xml / response-payload.xml contain only the xml payload of the message.
Depending on their position in the sequence of interceptors, they contain either the original, the
modified or both messages
HttpClientRequest.txt / HttpClientResponse.txt contain the http request as sent / received.
6.1.1.190.6 Summary

Intercept
message,
extract
payload
(HttpServer,
ConnectionProcessThread, com.bt.gw.http.interceptors.*)

Obtain UUID used to load enforcement configuration (RequestPayloadProcessor)

Set configuration and engage enforcement engine (RequestPayloadProcessor)

Update original message with result (RequestPayloadProcessor)

Send the message on, considering changed routing information in message (ProxyService,
HttpClient)
RequestListenerThread,
Page 236
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Illustration 2: Sequence diagram describing processing model
6.1.1.191 Enforcement Runtime (XML Payload Processing)
6.1.1.191.1 Description
The enforcement engine carries out enforcement actions. It expects an xml document and a
configuration path as input parameters. It loads a set of handlers based on the configuration, creates
a new state object and starts executing the handlers in sequence. The state object is used to share
information between the handlers and resolve dependencies. The result of the sequential
processing is a modified xml document according to the configuration policy.
6.1.1.191.2 Tasks


Process the message according to policy, update state bean
Inspect policy, load handlers, execute in sequence passing and updating state bean accordingly
therefore propagating information between atomic handlers
Page 237
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Illustration 3: class diagram of enforcement engine implementation + dependencies
6.1.1.191.3 Description of implementation
Package: com.bt.handler
This package contains the handler that make up the Enforcement Engine. The handlers and the chain
comply to a common pattern, the _init() method is used to read the configuration whereas
invoke(MessageContext) does the actual processing work.

GenericChain: The chain interfaces directly with the PayloadProcessors who passes the
configuration directory and the message as a string the chain. The chain itself holds the
configDir, the state bean and the handler vector. The _init() method reads the policy and
loads the corresponding handlers. The invoke(MessageContext) iterates over the
handler vector sets, for each handler it
o Sets the config dir for the handler and state bean for the handler
o initializes the handler by calling handler._init()
o invokes the handler by calling handler.invoke(MessageContext)
o copies the handler’s (updated) state bean over the copy it holds

SimpleHandler: invoke(MessageContext) calls invokeInput(MessageContext) or
invokeOutput(MessageContext) depending on the MessageContext object
Page 238
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007

AddressingHandler: invoke(MessageContext) gets AddressingHeaders (with the help
of axis' AddressingHandler) and puts them in the state bean together with the transport
address read from the wsa.to part of the addresing header.

HttpRoutingHandler: _init() reads the configuration. The invoke(MessageContext)
method creates an URI object and sets transport address in state bean and updates the wsa
information in the message.

PDPHandler: Implements the XACML Message Exchange Pattern (MEP) for Authorization
queries. The _init() method reads configuration (address), invoke(MessageContext)
populates WSClient.VariableParsers properties with the claims information from the state
bean.Then it creates a new WSClient with the corresponding address, sets VariableParser,
executes client and extracts the DECISION and STATUS_CODE data from response.

STSHandler: _init() reads configuration (useRegistry, address, cryptoConfig). The
invoke(MessageContext) obtains the addressing headers from the state bean and creates a
new Target Service object. Next it checks whether a SAML token is contained in the
message. If no token is found it executes issueToken, if it can locate a token it tries executes
validateToken.
issueToken(MessageContext): creates and configures a new WSTrustClient and calls
WSTrustClient.doRstIssue (), extracts the SAML Token from STS response, inserts it into
message header, sets the XACML claims in stateBean. Then it extracts and decrypts the
proof token and uses the symmetric key contained within to encrypt the appilcation message.
validateToken(MessageContext): extracts the SAML Token and creates and configures a
new WSTrustClient it uses to request token validation from the STS. If the STS validates the
token it extracts the claims from the response, sets them in StateBean, removes WSSE
header and decrypts the application message with the proof token it recieved.
Package: com.bt.state

StateBean: Container object for state transfer within chain.
Package: com.bt.test:

Test cases for handlers, chain and statebean.
The following diagram shows the coupling between the ProxyServer and Enforcement Engine part
of the PEP as well as describing the high level processing model of the enforcement engine from a
generic SimpleHandler (common base class to all handlers) point of view.
Page 239
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Sequence Diagram describing high level processing model of enforcement engine
6.1.1.191.4 Log files


Infrastructure handler based on WSClient log to HandlernameRequest HandlernameResponse
Chain logs to log4j, general PEP output
6.1.1.191.5 Summary

The enforcement engine expects a xml document and directory where to find the
configuration

It creates a state bean and populates the chain

It
executes
each
handler
in
sequence,
updating
the
state
bean
Page 240
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.192 Management Service
6.1.1.192.1 Description
Purpose is twofold. It serves as the management interface to the enforcement engine by providing
means of setting policies and uploading certificates. It serves as a virtualization device together with
the interceptor component and the enforcement engine, by creating a new virtualized resource and
exposing it to a user defined operational endpoint, where the interception engine gets the message,
extracts the configuration information to start a parameterized instance of enforcement process.
6.1.1.192.2 Details
A resource created through this interface has an associated uuid that is used to write out the values
of the resource‟s properties to the file system. These values are written to the temp directory of
tomcat / uuid / cfg (layout as expected by enforcement).
In addition to that, each resource appends its uuid and the values of the operational endpoint to a
text file in tmp directory of tomcat called resources.txt.
This file is used to do the mapping between between EPR and internal policy identifier.
On resource creation the resources tries to connect to rmi to expose tbd functionality to the
enforcement engine.
Service Instance Registry (SIR)
Installation Guide
Unzip the file archives sir.zip and sirguiclient.zip into separate folders.
6.1.1.193 Package Contents
Name
Type
Description
SIR
Service
Web Service interface providing all relevant
functionalities in order to deal with logical
names and end point references within
multiple federations. Should be installed at
each partner site.
SIRGUIClient
ClientApplication
Graphical application which allows the
testing of almost all functionalities provided
by the SIR service. This application is also
connected to the Gateway component
(developed by BT) to enable the
instantiation of local services and / or clients
whose resulting endpoint references are
directly stored within the SIR.
Page 241
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
6.1.1.194 Requirements
- Java JRE 1.5 is strongly recommended (http://java.sun.com/downloads)
- Apache Ant 1.5 or higher (http://ant.apache.org)
- Apache Tomcat Server 5.5 or higher (http://tomcat.apache.org)
- Apache Axis 1.4 or higher (http://ws.apache.org/axis)
- MySQL Database Server 5 (http://dev.mysql.com/downloads)
Remark:
The complete installation procedure and all (test) applications have been developed and tested using
these software versions. Older versions may work but it could not be guaranteed. If an older version of a
MySQL database server will be used, you have to download the corresponding driver from
http://dev.mysql.com/downloads/ and copy the jar-library into the lib folder of the SIR directory.
You also have to adjust the 'db.driver' property in the 'sir.properties' file.
6.1.1.195 Installation
Assumes that you are familiar with Ant & Tomcat and that a MySQL Server is already installed and
running within your local environment.
Please
verify
that
the
environment
variable
CATALINA_HOME=PATH_TO_TOMCAT_ROOT_FOLDER
for
Tomcat
is
set
and for Ant ANT_HOME=PATH_TO_ANT_ROOT_FOLDER
-
Start Tomcat unless the server is not yet running
Adjust the 'sir.properties' file by changing the following settings for Tomcat and the MySQL Server
tomcat.host=YOUR_TOMCAT_HOST
tomcat.port=YOUR_TOMCAT_PORT
db.host=YOUR_MYSQL_HOST
db.port=YOUR_MYSQL_PORT
db.user=trustcom
Leave it!
db.pw=trustcom
Leave it!
db.root=YOUR_MYSQL_ADMIN_USERNAME
db.root.pw=YOUR_MYSQL_ADMIN_PASSWORD
db.driver=mysql-connector-java-5.0.0-beta-bin.jar Leave it!
Page 242
to
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Run 'ant createDB' from your console:
Creates the database needed by the SIR.
Run 'ant install' from your console:
Compiles and installs all necessary components on your machine and
deploys the service into Tomcat.
Restart Tomcat!!!
Remark:
The installation procedure as well as all test applications have been successfully tested with Windows
(XP and Server 2003) and Ubuntu (http://www.ubuntu.com) Linux.
User‟s Guide
6.1.1.196 Testing the Installation
6.1.1.196.1 Verification using Tomcat
Visit the http://tomcat_location:tomcat_port/axis/servlet/AxisServlet website.
There should be an entry called SIR with different actions.
Click on 'wsdl' to see the appropriate Web Service Description File.
The SIR service entry after successful deployment
6.1.1.196.2 Running Test Applications
Page 243
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
Run 'ant TestClient' to print out some results of different actions
Run 'ant UnitTestClient' to see a graphical application appearing
that enables interactive unit testing.
Note: Before invoking a test, you should uncheck 'reload classes every
run' to avoid errors!
Remark:
To enable debugging, adjust the 'log4j.properties' file in 'metadata/properties' by setting the level for
'log4j.rootCategory‟ and 'log4j.category.org.hlrs.utils.SQLManager‟ to 'DEBUG'.
6.1.1.197 Working with the SIRGUIClient
Apart from the previously mentioned test applications shipped together with the SIR package, there is
also a “real” graphical application available (refer to package sirguiclient.zip) that allows users to
interactively play with several functionalities provided by the SIR service. This graphical user interface
can be seen as a management front-end for storing, updating, and deleting service instances within the
SIR. The following screenshot depicts the general view of the GUI which is divided into to main parts: The
upper part shows an overview of all current SIR entries and available data manipulation operations
whereas the lower part is reserved for the Gateway Instantiator provided by BT.
General view of the SIR client application
All supported operations are listed on the right side and each of them can be
invoked by simply clicking on the corresponding button.
Page 244
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
For manually registering a new service instance at the SIR, just click on the
„Add new Service Instance‟ button. A new window will immediately pop up
where all necessary information has to be filled in.
Adding a new service instance
Afterwards, the entry will be permanently stored in the SIR database and the
new entry will appear in the overview table. All other operations (adding and
updating) are executed in a similar way: A new window pops up where the
user has to put in all relevant data that needs to be stored / updated within the
SIR. If an instance should be deleted, you have to select to appropriate entry
within the table before clicking the „Remove Service Instance‟ button.
In order to link the Gateway component together with the SIR, the lower part
of the application is dedicated to provide Gateway-specific functions.
A user can instantiate a new service or client instance at the Gateway and at
the same time the appropriate entry is automatically created and forwarded to
the SIR database. This entry contains the just created EPR which consists of
information about the current federation and the corresponding partner
business key as well as the logical name of the provided service.
The latter enhancement is strongly related to the TrustCoM project and is not
required for managing and or using the SIR. It can be seen as a nice example
Page 245
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
which explains the interactions between the SIR and a different component.
Details about the instantiation of service or client instances at the Gateway
can be found in a different documentation and should not be mentioned here.
Instantiating a new service instance at the Gateway
Developer's Guide
6.1.1.198 SIR
The Web Service interface of the SIR provides a dozen of functions which enable the direct
communication with the database backend. These functions also include manipulation operations to add,
update, and delete appropriate data sets.
6.1.1.198.1 Interfaces

public boolean addServiceInstance(String[] entries)
Add a new service instance to the SIR.
- entries: an array of strings including the relevant data to be stored.
The order of the entries is very important and must have
the following guideline:
Page 246
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
1. Logical name (DB Type varchar(255))
2. EPR (DB Type text)
3. Federation UUID (DB Type varchar(255))
4. Additional Identifier (DB Type text)
- return true if instance is successfully stored in database
otherwise false
public boolean addServiceEpr(String federationUUID, String logicalName, String serviceEpr)
Add a new EPR to an already given service instance identified by its
federation UUID and logical name.
- federationUUID: a string representing the federation UUID of the
instance to be added
- logicalName: the unique logical name within the given federation
- serviceEpr: the new Epr
- return true if instance is successfully stored in database
otherwise false
public boolean addAddIdentifier(String federationUUID, String logicalName, String
addIdentifier)
Add a new additional identifier to a given instance identified by its
federation UUID and logical name.
- federationUUID: a string representing the federation UUID of the
instance to be updated
- logicalName: the unique logical name within the given federation
- addIdentifier: the new identifier
- return true if instance is successfully stored in database
otherwise false
public boolean updateServiceInstance(String[] entries)
Update a given instance identified by its federation UUID and logical
name.
- entries: an array of strings including the relevant data to be
updated
The order of the entries is very important and must have
the following guideline:
1. Logical name (DB Type varchar(255))
2. EPR (DB Type text)
3. Federation UUID (DB Type varchar(255))
4. Additional Identifier (DB Type text)
- return true if instance is successfully stored in database
otherwise
false
public boolean updateLogicalName(String federationUUID, String logicalName, String
newLogicalName)
Update the logical name of a given instance by its federation UUID
and logical name.
- federationUUID: a string representing the federation UUID of the
instance to be updated
- logicalName: the unique logical name within the given federation
- newLogicalName: the new logical name
- return true if instance is successfully stored in database
otherwise
false
public boolean updateServiceEpr(String federationUUID, String logicalName, String
serviceEpr)
Update the EPR of a given instance by its federation UUID and logical
name.
Page 247
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
- federationUUID: a string representing the federation UUID of the
instance to be updated
- logicalName: the unique logical name within the given federation
- serviceEPR: the new EPR
- return true if instance is successfully stored in database
otherwise
false
public boolean updateAddIdentifier(String federationUUID, String logicalName, String
addIdentifier)
Update the additional identifier of a given instance by its federation
UUID and logical name.
- federationUUID: a string representing the federation UUID of the
instance to be updated
- logicalName: the unique logical name within the given federation
- addIdentifier: the new identifier
- return true if instance is successfully stored in database
otherwise
false
public boolean removeAllFederationInstances (String federationUUID)
Delete all entries from database within the specified federation.
- federationUUID: a string representing the federation UUID of the
instance to be deleted
- return true if all instances are successfully removed from the
database otherwise false
public boolean removeServiceInstances(String logicalName)
Delete all entries from database identified by their logical name.
- logicalName: the logical name of the entries
- return true if all instances are successfully removed from the
database otherwise false
public boolean removeServiceInstance(String federationUUID, String logicalName)
Delete the instance from database identified by its federation UUID
and its logical name.
- federationUUID: a string representing the federation UUID of the
instance to be deleted
- logicalName: the logical name of the entry
- return true if instance is successfully removed from the database
otherwise
false
public boolean clearSIR()
Delete all entries from the database.
- return true if all instances are successfully removed from the
database otherwise false
public org.hlrs.trustcom.sir.ws.Datalist[] getAllServiceInstances()
Retrieve all instances stored in the database.
- return Datalist: A Java object for storing the columns of a
database table. Here, an array of Datalist is
which represents each row of the table
returned
public org.hlrs.trustcom.sir.ws.Datalist[] getAllFederationInstances(String federationUUID)
Retrieve all instances of a given federation.
- federationUUID: a string representing the federation UUID of the
instance to be selected
- return a Datalist array binding the different rows of the database
table
Page 248
D53 – Enhanced set of TrustCoM methods and support tools – 11/06/2007
public org.hlrs.trustcom.sir.ws.Datalist[] getServiceInstances(String logicalName)
Retrieve all instances identified by a specific logical name.
- logicalName: the logical name of the entries
- return a Datalist array binding the different rows of the database
table
public String[] getServiceInstance(String federationUUID, String logicalName)
Select the instance identified by its federation UUID and its logical
name.
- federationUUID: a string representing the federation UUID of the
instance to be selected
- logicalName: the logical name of the entry
- return an array of strings representing one row of the database
table
public String getLogicalName(String federationUUID)
Select the logical name identified by a given federation UUID.
- federationUUID: a string representing the federation UUID of the
instance to be selected
- return the logical name or „NULL‟
public String getServiceEpr(String federationUUID, String logicalName)
Select the EPR identified by its federation UUID and its logical name.
- federationUUID: a string representing the federation UUID of the
instance to be selected
- logicalName: the logical name of the entry
- return the EPR or „NULL‟
public String getAddIdentifier(String federationUUID, String logicalName)
Select the additional identifier identified by its federation
UUID and its logical name.
- federationUUID: a string representing the federation UUID of the
instance to be selected
- logicalName: the logical name of the entry
- return the additional identifier or „NULL‟
public boolean validateLogicalName(String federationUUID, String logicalName)
Look whether a logical name is already used within a given
federation.
- federationUUID: a string representing the federation UUID of the
instance to be selected
- logicalName: the logical name to be searched for
- return true if an instance with the specified logical name and
federation UUID is found in the database otherwise false
6.1.1.198.2 Example
If you want to test different functionalities of the SIR service, please refer to the test client applications
shipped with the SIR service package sir.zip. These examples explain how to use the methods within a
Java class.
Page 249
Download PDF