Home | PDF | API | FAQ | Search | Feedback | History

Soap With Attachments Sample Application

The swainterop sample application demonstrates the Soap with Attachments (SwA) interoperability scenarios. SwA describes how a web service consumer can secure SOAP attachments using XWS-Security for attachment integrity, confidentiality and origin authentication, and how a receiver may process such a message. Read more about SwA at http://www.oasis-open.org/committees/download.php/10090/wss-swa-profile-1.0-draft-14.pdf.

This sample application was used as Sun's entry in a virtual interoperability demonstration sponsored by OASIS. This sample implements a set of interop scenarios required by the event. The scenarios addressed in this sample are described in The SwA Interop Scenarios. Read more about the SwA interop scenarios at http://lists.oasis-open.org/archives/wss/200410/pdf00003.pdf.

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 is sent to stdout or whichever stream is used by the configured log handler. Messages are logged at the INFO level.

In this example, server-side code is found in the /swainterop/server/src/swainterop/ directory. Client-side code is found in the /swainterop/client/src/swainterop/ directory. The asant (or ant) targets build objects under the /build/server/ and /build/client/ directories.

The SwA Interop Scenarios

All four SwA interop scenarios use the same, simple application. The Requester sends a Ping element with a value of a string as the single child to a SOAP request. The value is the organization that has developed the software and the number of the scenario, for example, in this application the value is "Sun Microsystems - Scenario #1". The Responder returns a PingResponse element with a value of the same string. Each interaction includes a SOAP attachment secured via one of the content-level security mechanisms described in the WSS SwA Profile.

The following is a summary of each of the SwA interop scenarios demonstrated in this sample application. You will need the numbers for the scenarios when you run the sample application.

Scenario #1 - Attachment Signature

Scenario #1 tests the interoperability of a signed attachment using an X.509 certificate. The certificate used to verify the signature shall be present in the SOAP header. No security properties are applied to any part of the SOAP envelope.

Scenario #2 - Attachment Encryption

The SOAP request has an attachment that has been encrypted. The encryption is done using a symmetric cipher. The symmetric encryption key is further encrypted for a specific recipient identified by an X.509 certificate. The certificate associated with the key encryption is provided to the requestor out-of-band. No security properties are applied to any part of the SOAP envelope.

Scenario #3 - Attachment Signature and Encryption

The SOAP request contains an attachment that has been signed and then encrypted. The certificate associated with the encryption is provided out-of-band to the requestor. The certificate used to verify the signature is provided in the header. The Response Body is not signed or encrypted. There are two certificates in the request message. One identifiers the recipient of the encrypted attachment and one identifies the signer.

Scenario #4 - Attachment Signature and Encryption with MIME Headers

The SOAP request contains an attachment that has been signed and then encrypted. The certificate associated with the encryption is provided out-of-band to the requestor. The certificate used to verify the signature is provided in the header. The Response Body is not signed or encrypted. There are two certificates in the request message. One identifies the recipient of the encrypted attachment and one identifies the signer. This scenario differs from the first three scenarios in that it covers MIME headers in the signature and encryption. This means that it uses the Attachment-Complete Signature Reference Transform and Attachment-Complete EncryptedData Type.

Aside from these two changes, Scenario #4 is identical to Scenario #3.

SwA Sample Configuration Files

The security configuration pair swa-client.xml and swa-server.xml are used to secure message attachments. Each file contains the security configuration for each of the four scenarios.

You specify attachments as targets by specifying the value of the Content-ID (CID) header of the attachment. To do this, set the type attribute to uri and specify the target value as cid:<part-name>, where part-name is the WSDL part name of the AttachmentPart.

The swa-client.xml file looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>
      
    <!-- Port 1: SwA Scenario 1 Sign Attachment Only-->
      <xwss:Port name="{http://xmlsoap.org/Ping}Ping1"> 
        <xwss:SecurityConfiguration dumpMessages="true">
            <!-- 
              Note that in the <Sign> operation, a Timestamp is 
exported
              in the security header and signed by default.
            -->
            <xwss:Sign includeTimestamp="false">
                <xwss:X509Token certificateAlias="xws-security-
client"/>
                <xwss:CanonicalizationMethod 
                   algorithm="http://www.w3.org/2001/10/xml-
exc-c14n#"/>
                <xwss:SignatureMethod 
                   algorithm="http://www.w3.org/2000/09/
xmldsig#rsa-sha1"/>
                <xwss:SignatureTarget type="uri" 
value="cid:foobar">
                    <xwss:DigestMethod algorithm="http://
www.w3.org/2000/09/xmldsig#sha1"/>
                    <xwss:Transform algorithm="http://docs.oasis-
open.org/wss/2004/XX/
                       oasis-2004XX-wss-swa-profile-
1.0#Attachment-Complete-Transform"/>
                </xwss:SignatureTarget>
            </xwss:Sign>            
        </xwss:SecurityConfiguration>
      </xwss:Port>
        
      <!-- Port 2: SwA Scenario 2 Encrypt Attachment Only -->    
      <xwss:Port name="{http://xmlsoap.org/Ping}Ping2"> 
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as" 
keyReferenceType="Direct"/>
                <xwss:Target type="uri">cid:foobar</xwss:Target> 
            </xwss:Encrypt>            
        </xwss:SecurityConfiguration>
      </xwss:Port>

    <!-- Port 3: SwA Scenario 3 Attachment Signature and Encryp-
tion -->    
      <xwss:Port name="{http://xmlsoap.org/Ping}Ping3"> 
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:Sign includeTimestamp="false">
                <xwss:X509Token certificateAlias="xws-security-
client"/>
                <xwss:CanonicalizationMethod 
                     algorithm="http://www.w3.org/2001/10/xml-
exc-c14n#"/>
                <xwss:SignatureMethod 
                     algorithm="http://www.w3.org/2000/09/
xmldsig#rsa-sha1"/>
                <xwss:SignatureTarget type="uri" 
value="cid:foobar">
                    <xwss:DigestMethod algorithm="http://
www.w3.org/2000/09/xmldsig#sha1"/>
                    <xwss:Transform algorithm="http://docs.oasis-
open.org/wss/2004/XX/
                        oasis-2004XX-wss-swa-profile-
1.0#Attachment-Complete-Transform"/>
                </xwss:SignatureTarget>
            </xwss:Sign>            
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as" 
keyReferenceType="Direct"/>
                <xwss:Target type="uri">cid:foobar</xwss:Target> 
            </xwss:Encrypt>            
        </xwss:SecurityConfiguration>
      </xwss:Port>

      <!-- Port 4: SwA Scenario 4 Attachment Signature and 
Encryption 
                          With MIME Headers-->    
      <xwss:Port name="{http://xmlsoap.org/Ping}Ping4"> 
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:Sign includeTimestamp="false">
                <xwss:X509Token certificateAlias="xws-security-
client"/>
                <xwss:CanonicalizationMethod 
                    algorithm="http://www.w3.org/2001/10/xml-
exc-c14n#"/>
                <xwss:SignatureMethod 
                    algorithm="http://www.w3.org/2000/09/
xmldsig#rsa-sha1"/>
                <xwss:SignatureTarget type="uri" 
value="cid:foobar">
                    <xwss:DigestMethod algorithm="http://
www.w3.org/2000/09/xmldsig#sha1"/>
                    <xwss:Transform algorithm="http://docs.oasis-
open.org/wss/2004/XX/
                         oasis-2004XX-wss-swa-profile-1.0#
                         Attachment-Content-Only-Transform"/>
                </xwss:SignatureTarget>
            </xwss:Sign>            
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as" 
keyReferenceType="Direct"/>
                <xwss:Target type="uri" conten-
tOnly="false">cid:foobar</xwss:Target> 
            </xwss:Encrypt>            
        </xwss:SecurityConfiguration>
      </xwss:Port>
        
   </xwss:Service>

    <xwss:SecurityEnvironmentHandler>
        com.sun.xml.wss.sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity> 

The security configuration file for the server is swa-server.xml. Ideally, each scenario would contain a RequireSignature and/or RequireEncryption element, but we have not done this yet. The swa-server.xml file looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>

    <!-- Port 1: SwA Scenario 1 Sign Attachment Only-->
       <xwss:Port name="{http://xmlsoap.org/Ping}Ping1"> 
         <xwss:SecurityConfiguration dumpMessages="true">
</xwss:SecurityConfiguration>
       </xwss:Port>

    <!-- Port 2: SwA Scenario 2 Encrypt Attachment Only-->
       <xwss:Port name="{http://xmlsoap.org/Ping}Ping2"> 
         <xwss:SecurityConfiguration dumpMessages="true">
        </xwss:SecurityConfiguration>
       </xwss:Port>

   <!-- Port 3: SwA Scenario 3 Attachment Signature and Encryp-
tion-->
       <xwss:Port name="{http://xmlsoap.org/Ping}Ping3"> 
        <xwss:SecurityConfiguration dumpMessages="true"/>
       </xwss:Port>

  <!-- Port 4: SwA Scenario 4 Attachment Signature and Encryp-
tion 
         With MIME Headers -->
       <xwss:Port name="{http://xmlsoap.org/Ping}Ping4"> 
        <xwss:SecurityConfiguration dumpMessages="true"/>
       </xwss:Port>

    </xwss:Service>
    
    <xwss:SecurityEnvironmentHandler>
        com.sun.xml.wss.sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity> 

Running the SwA Sample Application

To run the swainterop sample application, follow these steps:

Complete the tasks defined in the following sections of this addendum:
Setting System Properties
Configuring a JCE Provider
Setting Build Properties
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.4Start Default Server.
Make sure that you have modified the /swainterop/build.properties file for this sample as described in Setting Build Properties.
Build and run the application from a terminal window or command prompt.
On the Application Server, the command to build and run the application is: asant run-sample-<number>
On the other containers, the command to build and run the application is: ant run-sample-<number>

Where the <number> variable is the number of the interop scenario you want to run.

---

Note: To run the sample against a remote server containing the deployed endpoint, use the run-remote-sample target in place of the run-sample target. In this situation, make sure that the endpoint.host, endpoint.port, http.proxyHost, http.proxyPort, and service.url properties are set correctly in the build.properties file (as discussed in Setting Build Properties) before running the sample.

---

If the application runs successfully, you will see a message similar to the following. The final response will have Sun Microsystems Scenario#<scenario-number>.

     [echo] Running the client program....
     [java] ==== Sending Message Start ====
     ...
     [java] ==== Sending Message End ====
     [java] ==== Received Message Start ====
     ...
     [java] ==== Received Message End ==== 

You will see similar messages in the server log files, which are located in the following files:

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

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.