RASP Library for Java 1.01

normalpetsSoftware and s/w Development

Nov 4, 2013 (4 years and 9 days ago)

95 views

OIO Service Oriented Infrastructure




OIO Service Oriented Infrastructure




RASP Library for Java 1.01

Overview
OIO Service Oriented Infrastructure


2

Contents
1

Introduction

................................
................................
................................
.................

3

1.1

Dependencies

................................
................................
................................
.........

4

2

Project structure
-

CODE

................................
................................
..............................

6

3

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

................................
................................
...............

10

3.2.3

XML validation

................................
................................
...............................

10

3.2.4

UD
D
I lookups

................................
................................
................................

11

3.2.5

LDAP look
ups
................................
................................
................................
.

13

3.2.6

OCSP lookups

................................
................................
................................

14

4

Examples

................................
................................
................................
...................

15

5

Appendix


Referenc
es

................................
................................
................................

16




OIO Service Oriented Infrastructure


3


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 w
ith the RASP for .Net API. For an
overview of the Rasp API consult the RASP for .Net documentation.


This document describe
s

the Java implementation

of RASP that builds

on top of Apache
Axis2.


The distribution is part of the OIOSI work for exchanging busi
ness 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/serviceorienteret
-
infrastruktur/rasp
-
library
-
for
-
java/


This document is a high
-
level introdu
ction 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 archi
tects.


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.










OIO Service Oriented Infrastructure


4

1.1

Dependencies


The J
ava 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
Axis
2
SOAP stack
Client application
RASP API
Axis
2
SOAP stack
SOAP
Request
SOAP
Reply


The rela
tion 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 include
s
:



Custom SOAP header handling



Signature validation proof
s



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 a
ssemble 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:










OIO Service Oriented Infrastructure


5



Application Layer
Reliable Messaging
(
WS
-
RM
)
Security
(
WS
-
Security
)
Transport
(
HTTP
/
MAIL
)
Custom Headers
(
RASP
)



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)







OIO Service Oriented Infrastructure


6

2

Project structure



CODE

RELEASE

This sec
tion 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



Contai
ns documentation
files for the Java RASP library.

T
his is
also w
here the
junit
test
result report
s

and javadoc
files arev
dropped when running the
build
scripts.


4.

keys



Contains the Java key stores
, containing X509

certificates, used for secure
communication
s


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
.

Thi
s 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 fin
d OIOUBL

schemas, schematron stylesheets, transformation stylesheets and user interface
stylesheets.

Furthermore a tool called raspkeytool.jar, for importing .cer and .pfx
OIO Service Oriented Infrastructure


7

certificate files into java key stores, can be found here


9.

skeletons



Contains
exampl
e code, simple
skeleton
s

for both
a RASP

client and service.


10.

src



Contains the source code for the RASP library.


11.

test



Contains the source code, certificate
s
, test XML
-
documents and configurations
used in the test cases.


12.

web



Contains the structure used wh
en 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 fi
le used by eclipse


3.

build.xml



The Ant build script









OIO Service Oriented Infrastructure


8

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 th
e Client_Skeleton example project) would be made
in four stages, as shown below:


LDAP Certificate
Lookup
OCSP Certificate
Validation
UDDI Service
Lookup
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 servic
e is called using the information gathered in the earlier steps



OIO Service Oriented Infrastructure


9

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
-
exc
-
c14n#
).



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 mes
saging

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:


Client application
Server
application
CreateSequence
CreateSequenceResponse
Send document
(
id
=
1
)
Acknowledge
(
range
=
1
)
Send document
(
id
=
2
)
LastMessage
Send document
(
id
=
2
)
LastMessage
TerminateSequence
TerminateSequence
Acknowledge
(
range
=
1
,
2
)



1.

The sequence is set up (CreateSequence, CreateSequenceResponse)

2.

Payload (in our case, a OIO UBL 2.0 business document) is sent

3.

An acknowledgement is returned

4.

In case our payload was not acknowledged, we send it again

5.

The seq
uence is shut down (LastMessage, TerminateSequence)

OIO Service Oriented Infrastructure


1
0

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

Trans
-

port/

Payload


Man
-
da
-

tory

SenderParty

Identifier

In contrast to the WS
-
Addressing
“From” element, thi
s element holds
the
logical

address of the sender,
e.g. an EAN number.



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 rece
ived
“ReceiverPartyIdentifier” and
“SenderPartyIdentifer” headers,
respectively.

E.g. an EAN
number

Non
-
empty
string

Trans
-
port +

Payload

Yes

ReceiverParty

Identifier

Corresponds to the EBMS “To”
element. In contrast to the WS
-
Addressing “To” element, th
is
element holds the
logical

address of
the reciever, e.g. and EAN number.



E.g. an EAN
number

Non
-
empty
string

Trans
-
port +

Payload

Yes

Message

Identifier

Corresponds to the EBSM
“MessageId” element. Represents a
business
-
level message identifier,
wher
eas the WS
-
Addressing
message ID represents a transport
-
level message ID.


Non
-
empty
string

Payload

Yes




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.signatu
reproof
.



3.2.3

XML validation

Xml validation can be done in two ways; the first is to call the validator with an XML
-
document and the second is to use the handlers in the Axis2 communication stack.

OIO Service Oriented Infrastructure


1
1

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.o
iosi.axis2.modules.xml”.


3.2.4

UD
D
I 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.




The lookup is based on a
n

endp
oint 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 attemp
ts 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 end
point
URL
, return
options, timeouts etc.


+
ProfileConformanceClaim
() :
string
+
RegistrationConformanceClaim
() :
string
+
UddiInquireEndpointURL
() :
string
+
UddiInquireEndpointURLFallback
() :
string
+
UddiPublishEndpointURL
() :
string
+
UddiSecurityEndpointURL
() :
string
+
FallbackTimeoutMinutes
() :
int
+
LookupReturnOptions
() :
LookupReturnOptionEnum
+
TryOtherHostsOnFailure
() :
bool
+
GatewayRange
() :
GatewayRange
+
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
UddiConfig


+
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
>
-
_
uddiInquiry
:
UddiInquiry
-
_
configuration
:
UddiConfig
-
CacheLock
:
object
=
new object
()
UddiLookupClient
+
Lookup
(
in parameters
:
LookupParameters
) :
List
<
dk
.
gov
.
oiosi
.
uddi
.
UddiLookupResponse
>
«interface»
IUddiLookupClient
OIO Service Oriented Infrastructure


1
2

The response from the l
ookup contains the endpoint address and other parameters.

+
EndpointIdentifierActual
() :
IIdentifier
+
EndpointAddress
() :
EndpointAddress
+
ExpirationDate
() :
DateTime
+
ActivationDate
() :
DateTime
+
CertificateSubjectSerialNumber
() :
CertificateSubject
+
TermsOfUseUrl
() :
Uri
+
ServiceContactEmail
() :
MailAddress
+
Version
() :
Version
+
NewerVersionReference
() :
UddiId
+
HasNewerVersion
() :
bool
+
UddiLookupResponse
()
+
UddiLookupResponse
()
-
_
endpointIdentifierActual
:
IIdentifier
-
_
endpointAddress
:
EndpointAddress
-
_
expirationDate
:
DateTime
-
_
activationDate
:
DateTime
-
_
certificateSubjectSerialNumber
:
CertificateSubject
-
_
termsOfUseUrl
:
Uri
-
_
ServiceContactEmail
:
MailAddress
-
_
version
:
Version
-
_
newerVersionReference
:
UddiId
UddiLookupResponse


One of the UDDI support classes is the UddiLookupClientFactory, which creates an
IUddiLookup implementation, as set in config.


+
CreateUddiLookupClient
() :
IUddiLookupClient
-
_
config
:
UddiLookupClientFactoryConfig
UddiLookupClientFactory



Developers may add their own implementation libraries and instantiate these just by
changing the
factory
configuration.


The UDDI i
nquiry represents an inquiry to the UDDI inquiry API. The inquiry takes
parameters like endpoint key, lookup policies, t
he UDDI endpoint etc.






+
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
()
-
uddiLookupLibrary
:
Inquiry
=
new Inquiry
()
#
pConfiguration
:
UddiConfig
UddiInquiry
OIO Service Oriented Infrastructure


1
3

3.2.5

LDAP lookups

The Ldap
CertificateL
ookup uses the
LDAP

protocol to query for a given certificate.
It is also
responsible for opening and closing connections to the LDAP server.



+
GetCertificate
(
in subjectSerialNumber
:
CertificateSubject
) :
X
509
Certificate
2
«interface»Lookup
::
ICertificateLookup
+
GetCertificate
(
in subjectSerialNumber
:
CertificateSubject
) :
X
509
Certificate
2
+
LdapCertificateLookup
(
in settings
:
LdapSettings
)
+
LdapCertificateLookup
()
-
ConnectToServer
() :
LdapConnection
-
Search
(
in ldapConnection
:
LdapConnection
,
in subject
:
CertificateSubject
) :
LdapSearchResults
-
GetCertificate
(
in ldapSearchResults
:
LdapSearchResults
) :
X
509
Certificate
2
-
SaveCertificate
(
in byteDate
:
byte
[])
-
_
settings
:
LdapSettings
Ldap
::
LdapCertificateLookup


The LdapCertificateLookup constructor takes an
L
dap
S
ettings object as a parameter. The
setting object is used every time a lookup is performed in the GetCertificate function.

+
Host
() :
string
+
Port
() :
short
+
ConnectionTimeoutMsec
() :
short
+
SearchServerTimeoutMsec
() :
short
+
SearchClientTimeoutMsec
() :
short
+
MaxResults
() :
short
-
_
host
:
string
-
_
port
:
short
-
_
connectionTimeoutMsec
:
short
-
_
searchServerTimeoutMsec
:
short
-
_
searchClientTimeoutMsec
:
short
-
_
maxResults
:
short
Ldap
::
LdapSettings



The LdapLookupFactory
instantiates classes with the ICertificateLookup interface

based on
the configuration.


+
CreateLdapLookupClient
() :
ICertificateLookup
Ldap
::
LdapLookupFactory


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
<
Ldap
LookupFactoryConfig>

element by setting
the namespac
e and assembly name of the ICertificateLookup implementation to instantiate.
Developers may add their own implementation libraries and instantiate these just by
changing the configuration.





OIO Service Oriented Infrastructure


1
4

3.2.6

OCSP lookups

OCSP lookup component is used to check certificate

revocation status against an OCSP
server.


+
CheckCertificate
(
in certificate
:
X
509
Certificate
2
) :
OcspResponse
+
Configuration
() :
OcspConfig
«interface»Ocsp
::
IOcspLookup
+
CheckCertificate
(
in certificate
:
X
509
Certificate
2
) :
OcspResponse
+
Configuration
() :
OcspConfig
-
Init
(
in configuration
:
OcspConfig
)
+
OcspLookup
(
in configuration
:
OcspConfig
)
+
OcspLookup
()
-
CheckCertificateCall
(
in certificate
:
X
509
Certificate
2
) :
OcspResponse
-
_
configuration
:
OcspConfig
-
_
defaultOcesRootCertificate
:
X
509
Certificate
2
Ocsp
::
OcspLookup


The OcspConfig is used to dynamically set the URL to the
OCSP

server, timeout, various
default settings etc.


+
ServerUrl
() :
string
+
DefaultTimeoutMsec
() :
int
+
OcspConfig
()
+
GetDefaultOcesRootCertificateFromStore
() :
X
509
Certificate
2
-
_
serverUrl
:
Uri
=
new Uri
("
http
://
localhost
")
-
_
defaultTimeoutMsec
:
int
=
10000
ocsp
::
OcspConfig



The response from the lookup contains an isValid boolean, which indicates if the certificate
ha
s 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.

+
NextUpdate
() :
DateTime
+
IsValid
() :
bool
-
_
isValid
:
bool
-
_
nextUpdate
:
DateTime
=
new DateTime
()
Ocsp
::
OcspResponse



OcspLookupFactory creates an

instance of a class with the IO
scspLookup interface.

+
CreateOcspLookupClient
() :
IOcspLookup
-
_
config
:
OcspLookupFactoryConfig
Ocsp
::
OcspLookupFactory


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 libra
ries and instantiate these just by changing the configuration.

OIO Service Oriented Infrastructure


1
5

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/serviceorienteret
-
infrastr
uktur/rasp
-
library
-
for
-
java/releases/1.01





OIO Service Oriented Infrastructure


1
6

5

Appendix


References


[RASP 1.1]
OIO Reliable Asynchronous Profile version 1.1

http://www.softwareborsen.dk/projekter/softwarecenter/serviceorienteret
-
infrastruktur/serviceorienteret
-
infrastruktur
-
ws
-
profiler/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 implementat
ion for Axis2

http://wso2.org/projects/commons/mercury