Download FAQ History

API Search Feedback

Understanding and Running the Interop Sample Application

This example is a fully-developed sample application that demonstrates various configurations that can be used to exercise XWS-Security framework code. The types of security configurations possible in this example include Digital Signature, XML Encryption, and UserName-Token verification. This example makes use of the XWS-Security framework to implement all WSS interop scenarios.

The interop sample application demonstrates a complete implementation of the seven WSS interop scenarios, as defined in the WSS Interop Scenarios document, which can be found at the following URL:

http://lists.oasis-open.org/archives/wss/200306/msg00002.html 

The application prints out both the client and server request and response SOAP messages. The output from the server may be viewed in the appropriate container's log file. The output from the client may be viewed using stdout.

In this example, server-side code is found in the /interop/server/src/interop/ directory. Client-side code is found in the /interop/client/src/interop/ directory. The asant (or Ant) targets build objects under the /build/server/ and /build/client/ directories. You can view other useful asant (or Ant) targets by entering asant (or ant) at the command line in the /interop/ directory.

This example uses keystores and truststores which are included in the /xws-security/etc/ directory. These are the only keystore and truststore files that will work with this example.

For this example, the keystore and truststore required on the server side have been packaged into the WAR (Web ARchive) file itself. It is therefore sufficient to ensure that the client sets the correct locations to the client-keystore.jks and client-truststore.jks in the build.properties file in order to run this sample.

Web Services Security Scenarios

This section discusses the interop sample application, which implements the seven existing WSS interop scenarios. Using these scenarios, developers will be able to send and receive messages compliant with the WSS Soap Message Security specification. Developers can use the framework to implement applications that have security requirements similar to those defined in the WSS interop scenarios.

Table 3-4 lists each of the WSS Interop Scenarios and provides a brief description of the security configuration used for each.

Table 3-4  WSS Interop Scenarios

Scenario	Description
Scenario 1	The Request header contains a user name and password. The Response does not contain a security header. More information on Scenario 1 can be found at http://lists.oasis-open.org/archives/wss/200306/msg00002.html, Draft Spec for Interop1 (draft 5). The sample client code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/client/src/interop/Scenario1Client.java. The sample server code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/server/src/interop/Scenario1Impl.java.
Scenario 2	The Request header contains a user name and password that have been encrypted using a public key provided out-of-band. The Response does not contain a security header. More information on Scenario 2 can be found at http://lists.oasis-open.org/archives/wss/200310/msg00003.html, Final Spec for Interop2 (draft 6). The sample client code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/client/src/interop/Scenario2Client.java. The sample server code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/server/src/interop/Scenario2Impl.java.
Scenario 3	The Request body contains data that has been signed and encrypted. The certificate used to verify the signature is provided in the header. The certificate associated with the encryption is provided out-of-band. The Response body is also signed and encrypted, reversing the roles of the key pairs identified by the certificates. The sample client code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/client/src/interop/Scenario3Client.java. The sample server code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/server/src/interop/Scenario3Impl.java.
Scenario 4	The Request body contains data that has been signed and encrypted. The certificate used to verify the signature is provided in the header. The symmetric key used to perform the encryption is provided out-of-band. The Response body is also signed and encrypted. The same symmetric key is used to perform the encryption. The certificate used to verify the signature is provided out-of-band. The sample client code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/client/src/interop/Scenario4Client.java. The sample server code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/server/src/interop/Scenario4Impl.java.
Scenario 5	The Request body contains data that has been signed twice. First the first element of the body is signed. The certificate used to verify this signature is provided out-of-band. Next the entire body is signed. The certificate used to verify this signature is provided in the header. The Response body is not signed or encrypted. The sample client code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/client/src/interop/Scenario5Client.java. The sample server code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/server/src/interop/Scenario5Impl.java.
Scenario 6	The Request body contains data that has been encrypted and signed. The certificate associated with the encryption is provided out-of-band. The certificate used to verify the signature is provided in the header. The Response body is also encrypted and signed, reversing the roles of the key pairs identified by the certificates. The sample client code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/client/src/interop/Scenario6Client.java. The sample server code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/server/src/interop/Scenario6Impl.java.
Scenario 7	The Request body contains data that has been signed and encrypted. The signature also protects an enclosed security token by means of the STR Dereference Transform. The certificate used to verify the signature is provided in the header. The certificate associated with the encryption is provided out-of-band. The Response body is also signed and encrypted, reversing the roles of the key pairs identified by the certificates. The sample client code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/client/src/interop/Scenario7Client.java. The sample server code that demonstrates this interop scenario is found in <JWSDP_HOME>/xws-security/samples/interop/server/src/interop/Scenario7Impl.java.

How is XWS-Security Implemented in the Interop Sample Application?

The SecurityConfigurator API adds a handler to the front of a handler chain on the server side. The handler contains an initially empty list of filters. Each of these filters can perform a specific, security-related, unit of work on a message. The SecurityConfigurator allows filters to be added to this list in order to provide security services. The interop samples all use this mechanism and, taken together, illustrate the full breadth of available functionality.

The following example code is from the Scenario4Client.java file from the interop example:

private static void scenario4(PingService service) throws 
Exception {
  try {
    SecurityConfigurator secCfg =
      new SecurityConfigurator(service, portName);
    SecurityEnvironment secDomain =
      initializeSecurityEnvironment();
    secCfg.setSecurityEnvironment(secDomain);
    X509Certificate certificate = (X509Certificate)
      ((DefaultSecurityEnvironmentImpl) 
      secDomain).getKeyStore().getCertificate(aliases[0]);
    secCfg.addRequestTimestamp();
    secCfg.addSignRequest("//SOAP-ENV:Body",certificate,
      SecurityConfigurator.DIRECT_REFERENCE_STRATEGY);
    secCfg.addFilterForOutgoingMessages(new
      ExportReferenceListFilter());
    secCfg.addFilterForOutgoingMessages(new
      EncryptElementFilter("//SOAP-ENV:Body",true, 
      new KeyNameStrategy()));

    if (debug) {
      // see what the request and response look like
      secCfg.addDumpRequest().addDumpResponse();
    }

    /* Add filters for Incoming messages */

    secCfg.addFilterForIncomingMessages(new
      ProcessSecurityHeaderFilter());

    } catch (Exception e) {
      e.printStackTrace();
      throw e;
    }
  } 

This mechanism does not handle the mustUnderstand portion of SOAP processing properly for encrypted headers. Therefore, because the wscompile utility with the
-security option does handle this portion of SOAP processing properly, wscompile is the preferred method for handling security in this release. Using the wscompile utility is the method described in Understanding and Running the Simple Sample Application.

Running the WSS Interop Scenario Sample Applications

Before the sample application will run correctly, you must have completed the tasks defined in the following sections of this addendum:

Setting System Properties
Configuring a JCE Provider
Setting Up the Application Server For the Examples
Setting Build Properties

To run the interop sample application, follow these steps:

Start the selected container and make sure the server is running. To start the Application Server,
From a Unix machine, enter the following command from a terminal window: asadmin start-domain domain1
From a Windows machine, choose StartProgramsSun MicrosystemsJ2EE 1.4 SDKStart Default Server.
If you are using a remote proxy server, add the proxy information to the run-client targets in the build.xml file. There are seven run-client targets, one for each of the interop scenarios, and each of these targets must have the following lines added if you are using a proxy server.

To modify the run-client targets,

Open the file /interop/build.xml in a text editor.
Locate the run-client<x> target definitions, which follow this format:
<target name="run-client1" ....>
<target name="run-client2" ....>
...
<target name="run-client7" ....>
Add the following lines to specify the proxy information to each of the seven run-client targets. The http.proxyHost and http.proxyHost properties should have been defined as specified in Setting Build Properties.
<sysproperty key="http.proxyHost"
   value="${http.proxyHost}"/>
<sysproperty key="http.proxyPort"
   value="${http.proxyPort}"/>
Build and run the application from a terminal window or command prompt, for example, on the Application Server,
   asant run-all
or on Tomcat or the Web Server,
   ant run-all
Build and run an individual interop scenario using the following command, where <x> is replaced by the number of the scenario to be run:

   asant run-client<x>
or on a remote proxy server,
   asant interop-client<x>

For example, to run WSS Interop scenario 1, the command would be:
   asant run-client1

---

Note: When the server is a remote server and the application is already deployed on the remote server, the interop-client<x> asant (or Ant) targets can be used instead of the run-Client<x> targets.

---

If the application runs successfully, you will see a message similar to the following:

[echo] Running the client program....
[java] ==== Request Start ====
...
[java] ==== Request End ====
[java] ==== Response Start ====
...
[java] ==== Response End ====
[java] Hello to Duke!  

You can view similar messages in the server logs:

<SJSAS_HOME>/domains/<domain-name>/logs/server.log 
<TOMCAT_HOME>/logs/launcher.server.log 
<SJSWS_HOME>/<Virtual-Server-Dir>/logs/errors 

Download FAQ History

API Search Feedback

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.