OIO Service Oriented Infrastructure
OIO Service Oriented Infrastructure
RASP Library for Java 1.01
Overview
OIO Service Oriented Infrastructure
Contents
1
2
3
4
5
Introduction .................................................................................................................2
1.1 Dependencies .........................................................................................................4
Project structure - CODE ..............................................................................................6
The RASP implementation .............................................................................................8
3.1 Axis2 provided functionality ....................................................................................9
3.1.1
Security ...........................................................................................................9
3.1.2
Reliable messaging ...........................................................................................9
3.2 Custom implemented RASP functionality .............................................................. 10
3.2.1
RASP SOAP headers ....................................................................................... 10
3.2.2
Signature validation proof ............................................................................... 11
3.2.3
XML validation ............................................................................................... 11
3.2.4
UDDI lookups ................................................................................................ 11
3.2.5
LDAP lookups................................................................................................. 13
3.2.6
OCSP lookups ................................................................................................ 14
Examples ................................................................................................................... 16
Appendix – References ................................................................................................ 17
1 Introduction
The OIOSI RASP Library for Java is a java based toolkit for implementation of RASP business
applications.
This distribution is Version 1.01.
From v 1.0 Releases of the Java API have been aligned with the RASP for .Net API. For an
overview of the Rasp API consult the RASP for .Net documentation.
This document describes the Java implementation of RASP that builds on top of Apache
Axis2.
The distribution is part of the OIOSI work for exchanging business documents in a secure
and reliable way using the internet. See http://www.oio.dk/arkitektur/soa/infrastruktur for
more information.
The framework can be downloaded from
http://www.softwareborsen.dk/projekter/softwarecenter/serviceorienteretinfrastruktur/rasp-library-for-java/
This document is a high-level introduction to the architecture in the Java version of the
RASP Framework. The purpose is to explain the overall architecture of the Java RASP
implementation and its dependency on the Apache Axis2 framework. The indented audience
is developers and software architects.
It is assumed that the reader of this document is slightly familiar with the protocols and
implementations referred to in the appendix. Please take some time to skim through those
resources before reading any further.
2
OIO Service Oriented Infrastructure
3
OIO Service Oriented Infrastructure
1.1 Dependencies
The Java RASP implementation is built on top of several open source project distributed by
the Apache Software Foundation, such as Axis2 and the Jakarta-commons components
(logging, configuration etc.).
Axis2, Apache’s SOAP implementation, has been chosen as the base for the library, as it
currently has wide support for web services standards and proven interoperability with the
Microsoft platform. Furthermore it is very common, and widely used for implementing and
consuming web services in Java.
Client application
RASP API
Axis2 SOAP stack
Axis2 SOAP stack
RASP API
Client application
SOAP
Request
SOAP
Reply
The relation between Axis2/the RASP API
To enable the implementation of the full RASP protocol a few extensions to Axis2 have been
written in the form of Axis2 handlers.
The functionality of these includes:
 Custom SOAP header handling
 Signature validation proofs
 XML validation in form of Schema and Schematron validation.
These can be found under the “module/src/dk/gov/oiosi/axis2/module/” source folder, and
in the distributed module archive file “rasp.mar”.
In the Axis2 configuration, modules are selected to assemble a communications stack that
provides RASP compliant communications. As an example, the stack for a RASP client (as set
up in the configuration file “conf/Client_Axis2” in the Client Skeleton example) looks like:
4
OIO Service Oriented Infrastructure
Application Layer
Reliable Messaging (WS-RM)
Custom Headers (RASP)
Security (WS-Security)
Transport (HTTP/MAIL)
Where
 Reliability is provided via the WS-ReliableMessaging protocol [WSRM] (as
implemented in the open source module Mercury)

Security is provided via the WS-Security protocol [WSS](as implemented in the
Apache Rampart module)
5
OIO Service Oriented Infrastructure
2 Project structure – CODE RELEASE
This section will shortly introduce the structure of the Java RASP project.
The project root folder contains the following folders:
1. .settings
 Contains project settings for eclipse.
2. conf
 Contains configuration files used by the library and Axis2.
3. doc
 Contains documentation files for the Java RASP library. This is also where the
junit test result reports and javadoc files arevdropped when running the build
scripts.
4. keys
 Contains the Java key stores, containing X509 certificates, used for secure
communications
5. lib
 Contains external libraries, such as Axis2 components
6. mar
 Contains Axis2 modules (.mar files), add-ons for enabling functionality such as
WS-Security and WS-Reliable messaging
7. module
 Contains the files used to generate a RASP module for Axis2. This module
describes the RASP specific operations needed to be done to the SOAP message
before sending (such as adding custom SOAP headers and creating signature
validation proofs)
8. resources
 Contains resource files used in the RASP profile. Here one can find OIOUBL
schemas, schematron stylesheets, transformation stylesheets and user interface
stylesheets. Furthermore a tool called raspkeytool.jar, for importing .cer and .pfx
6
OIO Service Oriented Infrastructure
certificate files into java key stores, can be found here
9. skeletons
 Contains example code, simple skeletons for both a RASP client and service.
10. src
 Contains the source code for the RASP library.
11. test
 Contains the source code, certificates, test XML-documents and configurations
used in the test cases.
12. web
 Contains the structure used when generating the a web archive for the
deployment of a RASP service to an application server (such as Tomcat or
Glassfish).
The project root folder contains the following files:
1. .classpath
 The class path settings used by eclipse
2. .project
 The project file used by eclipse
3. build.xml
 The Ant build script
7
OIO Service Oriented Infrastructure
3 The RASP implementation
The RASP library provides functionality for both making preparations, and for making actual
RASP compliant web service calls.
The typical RASP service call (as seen in the Client_Skeleton example project) would be made
in four stages, as shown below:
UDDI Service
Lookup
LDAP Certificate
Lookup
OCSP Certificate
Validation
RASP
Communications
stack
1. The endpoint address of the service being called is looked up in a UDDI registry.
Along with it a certificate subject string is returned, identifying the certificate used by
the service for encrypting and signing messages
2. The actual certificate is downloaded from an LDAP server using the subject string
returned in the previous call
3. The certificate revocation status is checked against an OCSP server
4. And finally the service is called using the information gathered in the earlier steps
8
OIO Service Oriented Infrastructure
3.1 Axis2 provided functionality
3.1.1 Security
Security in the RASP library is provided via the WS-Security 1.0 [WSS] implementation
provided by the Axis2 module Rampart [RAMPART].
The WS-Security configuration used by RASP is:





Symmetric keys are encrypted using the RSA-OAEP
(http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p)
Digests are generated using SHA1(http://www.w3.org/2000/09/xmldsig#sha1)
Canonicalization is done using XML-C14N(http://www.w3.org/2001/10/xml-excc14n#).
The signature is created using RSA/SHA1
(http://www.w3.org/2000/09/xmldsig#rsa-sha1)
Body encryption is done using AES256
(http://www.w3.org/2001/04/xmlenc#aes256-cbc)
3.1.2 Reliable messaging
Message reliability, a guarantee of delivery, is provided via the WS-ReliableMessaging 1.0
[WSRM] module Mercury [MERCURY].
WS-RM provides functionality for acknowledging incoming messages as well as re-sending
missing messages. A reliable session might look as shown below:
CreateSequence
CreateSequenceResponse
Send document (id=1)
Acknowledge (range=1)
Send document (id=2)
Acknowledge (range=1,2)
Server application
Client application
Send document (id=2)
LastMessage
LastMessage
TerminateSequence
TerminateSequence
1.
2.
3.
4.
5.
The sequence is set up (CreateSequence, CreateSequenceResponse)
Payload (in our case, a OIO UBL 2.0 business document) is sent
An acknowledgement is returned
In case our payload was not acknowledged, we send it again
The sequence is shut down (LastMessage, TerminateSequence)
9
OIO Service Oriented Infrastructure
3.1.3 Configuration
There are several configurations in the AXIS2 framework that can be used for setting the
transportation.
The mail configuration that is used for the mail transport makes it possible to set host,
username, password, reply-address and usage of SSL. The specific implementation example
of code writing to the configuration can be viewed at the AXIS2 documentation at the
following address:
http://ws.apache.org/axis2/1_4/mail-configuration.html
3.2 Custom implemented RASP functionality
3.2.1 RASP SOAP headers
A set of SOAP headers, as defined in [RASP 1.1], are required when communicating via RASP
(see table below).
These headers are added in the Axis2 module found in the namespace
dk.gov.oiosi.axis2.module.customheaders.
Table: Custom RASP SOAP headers
Element
name
Description
Example
Format
Transport/
Payload
Mandatory
SenderParty
Identifier
In contrast to the WS-Addressing
“From” element, this element holds
the logical address of the sender,
e.g. an EAN number.
E.g. an EAN
number
Nonempty
string
Transport +
Payload
Yes
E.g. an EAN
number
Nonempty
string
Transport +
Payload
Yes
Nonempty
string
Payload
Yes
ReceiverParty
Identifier
Message
Identifier
When the receiver sends response
messages (i.e. all transport
messages), he must add both the
“SenderPartyIdentifier” and
“ReceiverParty” header and set
them to the value of the received
“ReceiverPartyIdentifier” and
“SenderPartyIdentifer” headers,
respectively.
Corresponds to the EBMS “To”
element. In contrast to the WSAddressing “To” element, this
element holds the logical address of
the reciever, e.g. and EAN number.
Corresponds to the EBSM
“MessageId” element. Represents a
business-level message identifier,
whereas the WS-Addressing
message ID represents a transportlevel message ID.
1
0
OIO Service Oriented Infrastructure
3.2.2 Signature validation proof
The signature validation proof is generated in the Axis2 module found in the namespace
dk.gov.oiosi.axis2.module.signatureproof.
3.2.3 XML validation
Xml validation can be done in two ways; the first is to call the validator with an XMLdocument and the second is to use the handlers in the Axis2 communication stack.
The two validators that can be called with an XML-document are located in package
“dk.gov.oiosi.xml.schema” and “dk.gov.oiosi.xml.schematron”.
The validation is implemented as two Axis2 Handlers, that schema and schematron validates
incoming or outgoing payloads.
The implementation can be found the package “dk.gov.oiosi.axis2.modules.xml”.
3.2.4 UDDI lookups
The UDDI is used in the ARS (Address Resolving Service), which is used to resolve business
level endpoints to service endpoints. Below you can see the main UDDI classes for lookup.
«interface»IUddiLookupClient
+Lookup(in parameters : LookupParameters) : List<dk.gov.oiosi.uddi.UddiLookupResponse>
UddiLookupClient
-_uddiInquiry : UddiInquiry
-_configuration : UddiConfig
-CacheLock : object = new object()
+Lookup(in parameters : LookupParameters) : List<dk.gov.oiosi.uddi.UddiLookupResponse>
-Init()
+UddiLookupClient(in configuration : UddiConfig)
+UddiLookupClient()
-CachedInquire(in parameters : LookupParameters, in inquiryResult : List<dk.gov.oiosi.uddi.UddiLookupResponse>) : List<dk.gov.oiosi.uddi.UddiLookupResponse>
-FilterResponse(in parameters : LookupParameters, in inquiryResult : List<dk.gov.oiosi.uddi.UddiLookupResponse>) : List<dk.gov.oiosi.uddi.UddiLookupResponse>
-GatewayLookup(in parameters : LookupParameters) : List<dk.gov.oiosi.uddi.UddiLookupResponse>
The lookup is based on an endpoint key (e.g. an EAN number) and other lookup options like
address type etc. You can for example set a process definition (such as an OIOUBL profile
definition) as a filter.
The component can also handle automatic caching of endpoints of resolving attempts and
supports caching policies based on the call result feedback. You can also set a fallback
address, so it uses a secondary UDDI registry in case the primary is unavailable.
The client takes a configuration object, which sets attributes like UDDI endpoint URL, return
options, timeouts etc.
1
1
OIO Service Oriented Infrastructure
UddiConfig
-_profileConformanceClaim : string = ""
-_registrationConformanceClaim : string = ""
-_uddiInquireEndpointURL : string = ""
-_uddiInquireEndpointURLFallback : string = ""
-_uddiPublishEndpointURL : string = ""
-_uddiSecurityEndpointURL : string = ""
-_fallbackTimeoutMinutes : int = 0
-_lookupReturnOptions : LookupReturnOptionEnum = LookupReturnOptionEnum.allResults
-_tryOtherHostsOnFailure : bool = true
-_gatewayRange : GatewayRange = null
+ProfileConformanceClaim() : string
+RegistrationConformanceClaim() : string
+UddiInquireEndpointURL() : string
+UddiInquireEndpointURLFallback() : string
+UddiPublishEndpointURL() : string
+UddiSecurityEndpointURL() : string
+FallbackTimeoutMinutes() : int
+LookupReturnOptions() : LookupReturnOptionEnum
+TryOtherHostsOnFailure() : bool
+GatewayRange() : GatewayRange
+UddiConfig()
The response from the lookup contains the endpoint address and other parameters.
UddiLookupResponse
-_endpointIdentifierActual : IIdentifier
-_endpointAddress : EndpointAddress
-_expirationDate : DateTime
-_activationDate : DateTime
-_certificateSubjectSerialNumber : CertificateSubject
-_termsOfUseUrl : Uri
-_ServiceContactEmail : MailAddress
-_version : Version
-_newerVersionReference : UddiId
+EndpointIdentifierActual() : IIdentifier
+EndpointAddress() : EndpointAddress
+ExpirationDate() : DateTime
+ActivationDate() : DateTime
+CertificateSubjectSerialNumber() : CertificateSubject
+TermsOfUseUrl() : Uri
+ServiceContactEmail() : MailAddress
+Version() : Version
+NewerVersionReference() : UddiId
+HasNewerVersion() : bool
+UddiLookupResponse()
+UddiLookupResponse()
One of the UDDI support classes is the UddiLookupClientFactory, which creates an
IUddiLookup implementation, as set in config.
UddiLookupClientFactory
-_config : UddiLookupClientFactoryConfig
+CreateUddiLookupClient() : IUddiLookupClient
Developers may add their own implementation libraries and instantiate these just by
changing the factory configuration.
The UDDI inquiry represents an inquiry to the UDDI inquiry API. The inquiry takes
parameters like endpoint key, lookup policies, the UDDI endpoint etc.
1
2
OIO Service Oriented Infrastructure
UddiInquiry
-uddiLookupLibrary : Inquiry = new Inquiry()
#pConfiguration : UddiConfig
+UddiInquiry(in configuration : UddiConfig)
-IsInactiveOrExpired(in service : BusinessService) : bool
+Inquire(in endpointKey : IIdentifier, in inquiryParameters : LookupParameters, in lookupPolicies : UddiLookupClientPolicy) : List<dk.gov.oiosi.uddi.UddiLookupResponse>
-GetTModels(in template : BindingTemplate) : TModel[]
-IsAcceptableProcessInstance(in tmodel : TModel, in parameters : LookupParameters) : bool
-IsProcessInstance(in tmodel : TModel, in parameters : LookupParameters) : bool
-MeetsTModelCriteria(in tmodels : TModel[], in parameters : LookupParameters) : bool
-AddEndpointAddress()
-IsAcceptableAddressType(in address : EndpointAddress, in parameters : LookupParameters) : bool
-GetTModelDetail(in tmodelKey : string) : TModel
-GetCertificate(in service : BusinessService) : string
-GetTermsOfUseUrl(in service : BusinessService) : Uri
-GetContactMail(in service : BusinessService) : MailAddress
-GetVersion(in service : BusinessService) : Version
-GetNewerVersion(in service : BusinessService) : UddiId
-GetCategory(in service : BusinessService, in category : ArsCategory) : ArsCategory
-GetDatetimeFromLifetimeDates(in datestring : string, in getActivationDate : bool) : DateTime
-GetActivationDate(in service : BusinessService) : DateTime
-GetExpirationDate(in service : BusinessService) : DateTime
-GetAuthenticationRequired(in service : BusinessService) : bool
-GetServiceDetails(in servicekeysFound : string[]) : BusinessService[]
-GetServices()
3.2.5 LDAP lookups
The LdapCertificateLookup uses the LDAP protocol to query for a given certificate. It is also
responsible for opening and closing connections to the LDAP server.
«interface»Lookup::ICertificateLookup
+GetCertificate(in subjectSerialNumber : CertificateSubject) : X509Certificate2
Ldap::LdapCertificateLookup
-_settings : LdapSettings
+GetCertificate(in subjectSerialNumber : CertificateSubject) : X509Certificate2
+LdapCertificateLookup(in settings : LdapSettings)
+LdapCertificateLookup()
-ConnectToServer() : LdapConnection
-Search(in ldapConnection : LdapConnection, in subject : CertificateSubject) : LdapSearchResults
-GetCertificate(in ldapSearchResults : LdapSearchResults) : X509Certificate2
-SaveCertificate(in byteDate : byte[])
The LdapCertificateLookup constructor takes an LdapSettings object as a parameter. The
setting object is used every time a lookup is performed in the GetCertificate function.
1
3
OIO Service Oriented Infrastructure
Ldap::LdapSettings
-_host : string
-_port : short
-_connectionTimeoutMsec : short
-_searchServerTimeoutMsec : short
-_searchClientTimeoutMsec : short
-_maxResults : short
+Host() : string
+Port() : short
+ConnectionTimeoutMsec() : short
+SearchServerTimeoutMsec() : short
+SearchClientTimeoutMsec() : short
+MaxResults() : short
The LdapLookupFactory instantiates classes with the ICertificateLookup interface based on
the configuration.
Ldap::LdapLookupFactory
+CreateLdapLookupClient() : ICertificateLookup
The factory could instantiate either LdapCertificateLookup or LdapCertificateLookupTest, or
you may create your own implementation. You can change this behavior in the
RaspConfiguration.xml file, in the section <LdapLookupFactoryConfig> element by setting
the namespace and assembly name of the ICertificateLookup implementation to instantiate.
Developers may add their own implementation libraries and instantiate these just by
changing the configuration.
3.2.6 OCSP lookups
OCSP lookup component is used to check certificate revocation status against an OCSP
server.
«interface»Ocsp::IOcspLookup
+CheckCertificate(in certificate : X509Certificate2) : OcspResponse
+Configuration() : OcspConfig
Ocsp::OcspLookup
-_configuration : OcspConfig
-_defaultOcesRootCertificate : X509Certificate2
+CheckCertificate(in certificate : X509Certificate2) : OcspResponse
+Configuration() : OcspConfig
-Init(in configuration : OcspConfig)
+OcspLookup(in configuration : OcspConfig)
+OcspLookup()
-CheckCertificateCall(in certificate : X509Certificate2) : OcspResponse
The OcspConfig is used to dynamically set the URL to the OCSP server, timeout, various
default settings etc.
1
4
OIO Service Oriented Infrastructure
ocsp::OcspConfig
-_serverUrl : Uri = new Uri("http://localhost")
-_defaultTimeoutMsec : int = 10000
+ServerUrl() : string
+DefaultTimeoutMsec() : int
+OcspConfig()
+GetDefaultOcesRootCertificateFromStore() : X509Certificate2
The response from the lookup contains an isValid boolean, which indicates if the certificate
has been revoked, either temporarily or permanently. The response also contains a
nextUpdate value, which is used to store the time when newer information will be available,
but this has not been implemented for this preview. This is however not implemented with
the underlying library that this release implements.
Ocsp::OcspResponse
-_isValid : bool
-_nextUpdate : DateTime = new DateTime()
+NextUpdate() : DateTime
+IsValid() : bool
OcspLookupFactory creates an instance of a class with the IOscspLookup interface.
Ocsp::OcspLookupFactory
-_config : OcspLookupFactoryConfig
+CreateOcspLookupClient() : IOcspLookup
The factory could instantiate either OcspLookup or OcspLookupTest, or you can derive your
own implementation. You can change this behavior in the RaspConfiguration.xml file, in the
section <OcspLookupFactoryConfig> element by setting the namespace and assembly
name of the IOcspLookup implementation to instantiate. Developers may add their own
implementation libraries and instantiate these just by changing the configuration.
1
5
OIO Service Oriented Infrastructure
4 Examples
For examples using all the above mentioned functionality, see the tutorials document,
describing how to deploy the client and service skeleton projects that ship with the RASP
source code, or as a separate download from
http://www.softwareborsen.dk/projekter/softwarecenter/serviceorienteretinfrastruktur/rasp-library-for-java/releases/1.01
1
6
OIO Service Oriented Infrastructure
5 Appendix – References
[RASP 1.1] OIO Reliable Asynchronous Profile version 1.1
http://www.softwareborsen.dk/projekter/softwarecenter/serviceorienteretinfrastruktur/serviceorienteret-infrastruktur-wsprofiler/releases/RASP1.1/OIO_Reliable_Asynchronous_Secure_Profile_1.1.doc
[WSRM] Web Services Reliable Messaging Protocol
http://specs.xmlsoap.org/ws/2005/02/rm/ws-reliablemessaging.pdf
[WSS] Web Services Security: SOAP Message Security 1.0
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf
[AXIS2] Apache Axis2 SOAP engine
http://ws.apache.org/axis2/
[RAMPART] Apache Rampart, WS-security implementation for Axis2
http://ws.apache.org/rampart/
[MERCURY] Mercury, WS-ReliableMessaging implementation for Axis2
http://wso2.org/projects/commons/mercury
1
7