Applying digital signatures to Axis-generated SOAP messages in the OMII framework

normalpetsSoftware and s/w Development

Nov 4, 2013 (3 years and 10 months ago)

74 views


Applying digital signatures to Axis
-
generated SOAP messages in the
OMII framework


Author: Victor Tan

Date: 20 May 2005

Documentation type: User guide



1.
Background


The OMII framework provides libraries for creating signatures on outgoing client
-
side
S
OAP messages, and for verifying these signatures on server
-
side Web Services
deployed in the OMII Tomcat/Axis Web Service container. The process of
verification also produces an X509 Distinguished Name (DN) of the public key
certificate corresponding to th
e signature; this DN can later be used to decide whether
the incoming invocation is authorized or not (refer to the OMII user guide for further
details on signatures and authorization).


However, the OMII client
-
side library is designed primarily to sign
SOAP messages
in a manner that is tightly coupled to the way in which an OMII client marshals
arguments to constitute a SOAP message. The way that this is done by an OMII client
differs from standard Axis
-
type clients, in that the OMII framework does not s
upport
generation of client
-
side stubs from WSDL descriptions as Axis does. Consequently,
there is no straight forward way to use the OMII framework to sign SOAP messages
generated by Axis
-
type client stubs. This document describes a way in which this can
achieved with reference to version 1.2 of the OMII distribution.



2. Using WSDL to generate client side stubs in standard Axis


In general, services deployed in Axis will have a WSDL to describe their interface.
One way of constructing a client to intera
ct with such a service is to use the
WSDL2Java tool in Axis to generate client stubs and server skeleton classes that will
marshall and unmarshall SOAP messages on both the client and server side
respectively. This process is described in greater detail i
n the Axis manual at
(
http://ws.apache.org/axis/java/user
-
guide.html#UsingWSDLWithAxis
). Briefly it
involves the following steps:


1. Obtain the WSDL of the desired service i
n question


2. Generate the required client and server side stubs and/or skeletons with the
appropriate parameters supplied to the WSDL2Java tool. An example of an ant task
that does this is shown below:



<target name = "generatejava">


<axis
-
wsd
l2java url="XXX.wsdl"


output="generatedJava"


deployscope="session"


serverSide="yes"


skeletonDeploy="yes"


noimports="no"


verbose="no"


testcase="yes">


<mapping na
mespace="urn:Example6" package="widgetgenerate"/>


</axis
-
wsdl2java>


</target>


3. If server side classes are generated, XXXSoapBindingImpl.java (where XXX is the
name of the service) effectively becomes the server implementation and can
be filled
in with appropriate implementation code. Client side classes include
XXXS
erviceLocator

and XXX
SoapBindingStub
; these will be used by the actual
client code in invoking WS calls on the server end. Note that it is not compulsory to
generate both s
erver and client side skeletons and stubs. A service may already be
implemented and deployed appropriately in Axis; in which case, we merely need to
use the corresponding WSDL to generate the client side stubs to be used by our
clients.


4. Write the actu
al client code to make use of the generated stubs in order to marshall
the correct SOAP messages to the intended service destination. An example of such
code is shown below.



public static void main (String[] args) throws Exception {


XXX bindi
ng = new XXXServiceLocator().getXXX();


((XXXSoapBindingStub)binding).setMaintainSession(true);


try {


System.out.println ("Calling sample method on the service");


((XXXSoapBindingStub) binding).callSample();


}

catch (java.rmi.RemoteException re) {


System.out.println ("There's an error ! " + re);


}


}


5. Ensure that the client code and the client stubs are in the appropriate package
structure, compile and run them.



3. Signing SOAP messa
ges produced from client side stubs


As explained previously, the client side stubs marshal the arguments to be sent into an
appropriate XML format in the SOAP message body. This usually involves the use of
the
org.apache.axis.client.Call
object (the
Call
object could also be used directly to
invoke a service without going through the client side stubs). This body has to be
signed if the target service is deployed in the secure OMII container. In order to do
this, we somehow need to intercept SOAP messages

sent out by these stubs, sign them
using the appropriate OMII libraries and forward these signed messages onwards to
their intended destination. This can be achieved by a client side handler in accordance
with the handler chain architecture of Axis
(
http://ws.apache.org/axis/java/architecture
-
guide.html
). This handler must be
deployed in the same classpath as the client side stubs using an appropriate
deployment file. The required step
s are briefly outlined below:


1. A deploy.wsdd file is created that specifies the client side handler to be used. An
example of such a file is given below:

<deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/pr
oviders/java">



<handler name="redirect" type="java:clientcode.SimpleClientHandler">


<parameter name="sampleParameter" value="example parameter
value"/>


</handler>



<globalConfiguration>


<requestFlow>


<handler type="redirect"/>


</requestFlow>


<responseFlow>


<handler type="redirect"/>


</responseFlow>



</globalConfiguration>


</deployment>


2
.
Invoke
org.apache.axis.utils.Admin
with appropriate parameters on
this
deploy.wsdd
in order to
create a client
-
confi
g.wsdd in an appropriate directory
.


3. The source code for the client, client side stubs and client side handler are compiled
and client
-
config.wsdd is placed in the classpath of these classes.


4. When the client side stubs issue a SOAP message, this is

picked up automatically
by the handler and subsequently processed (signed, in this case) and then forwarded
onwards to its intended destination. Note that the client side handler will also intercept
messages on the return path from the destination, but ca
n be configured so that no
processing is done at this point (if so desired).


5. NOTE: Important ! A service in a secure OMII container uses a series of server
-
side handlers to verify the signature on an incoming SOAP message (see the
document Server side
security in the OMII container). However, these handlers are
unable to parse certain XML elements in SOAP messages that are usually found in
RPC
-
style services (such as xsd:int, xsd:string, and so on). This is less likely to be the
case with document
-
styl
e services. The client
-
side handler that signs the outgoing
SOAP messages may need to pre
-
process the intercepted SOAP messages in order to
take into account this shortcoming on the server
-
side handlers.


Please refer to the document for using a client sid
e handler for a secure OMII
Grimoires client for specific details in the context of a secure OMII Grimoires client.