Download FAQ History

API Search Feedback

Understanding and Running the Simple Sample Application

This example is a fully-developed sample application that demonstrates various configurations that can be used to exercise XWS-Security framework code. By modifying one property in the build.properties file for the example, you can change the type of security that is being used for the client and/or the server. The types of security configurations possible in this example include XML Digital Signature, XML Encryption, and UserName-Token verification. This example allows and demonstrates combinations of these basic security mechanisms through the specification of the appropriate security configuration files.

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 /simple/server/src/simple/ directory. Client-side code is found in the /simple/client/src/simple/ 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 /simple/ directory.

This example uses keystores and truststores which are included in the /xws-security/etc/ directory. For more information on using keystore and truststore files, read the keytool documentation at the following URL:

http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/key-
tool.html 

Plugging in Security Configurations

This example makes it simple to plug in different client and server-side configurations describing security settings. This example has support for digital signatures, XML encryption/decryption, and username/token verification. This example allows and demonstrates combinations of these basic security mechanisms through configuration files. See Sample Security Configuration File Options, for further description of the security configuration options defined for the simple sample application.

To specify which security configuration option to use when the sample application is run (see Running the Simple Sample Application), follow these steps:

Open the build.properties file for the example. This file is located at <JWSDP_HOME>/xws-security/samples/simple/build.properties.
To set the security configuration that you want to run for the client, locate the client.security.config property, and enter one of the client security configuration options contained in the <JWSDP_HOME>/xws-security/samples/simple/config/ directory. The client configuration options are listed in Sample Security Configuration File Options. This section also lists which client and server configurations work together. For example, if you want to use XML Encryption for the client, you would set this property as follows:

# Client Security Config. file
client.security.config=config/encrypt-client.xml

To set the security configuration that you want to run for the server, locate the server.security.config property, and enter one of the server security configuration options listed in the <JWSDP_HOME>/xws-security/samples/simple/config/ directory. The server configuration options, and which server options are valid for a given client configuration, are listed in Sample Security Configuration File Options. For example, if you want to use XML Encryption for the server, you would set this property as follows:

# Server Security Config. file
server.security.config=config/encrypt-server.xml

Save and exit the build.properties file.
Run the sample application as described in Running the Simple Sample Application.

Sample Security Configuration File Options

The configuration files available for this example are located in the /xws-security/samples/simple/config/ directory. The configuration pairs available under this sample include configurations for both the client and server side. Any combination of the *-client.xml and *-server.xml configurations can be used. Some possible combinations are discussed in more detail in the referenced sections.

dump-client.xml, dump-server.xml
encrypt-client.xml, encrypt-server.xml
sign-client.xml, sign-server.xml
sign-encrypt-client.xml, sign-encrypt-server.xml
encrypt-sign-client.xml, encrypt-sign-server.xml
user-pass-authenticate-client.xml, dump-server.xml
encrypted-user-pass-also-client.xml, dump-server.xml
sign-ticket-also-client.xml, dump-server.xml

Dumping the Request and/or the Response

The security configuration pair dump-client.xml and dump-server.xml have no security operations. These options enable the following tasks:

Dump the request before it leaves the client.
Dump the response upon receipt from the server.

The container's server logs also contain the dumps of the server request and response. See Running the Simple Sample Application for more information on viewing the server logs.

Encrypting the Request and/or the Response

The security configuration pair encrypt-client.xml and encrypt-server.xml enable the following tasks:

Client encrypts the request body and sends it.
Server decrypts the request and sends back an encrypted response.
Client decrypts the response.

The encrypt-client.xml file looks like this:

<xwss:SecurityConfiguration xmlns:xwss=
   "http://com.sun.xml.wss.configuration"
      useTimestamps="true"
      dumpMessages="true">
   <xwss:Encrypt receiverCertificateAlias="s1as"/>
</xwss:SecurityConfiguration> 

Signing and Verifying the Signature

The security configuration pair sign-client.xml and sign-server.xml enable the following tasks:

Client signs the request body.
Server verifies the signature and signs its response.
Client verifies the signature over the body.

The sign-client.xml file looks like this:

<xwss:SecurityConfiguration xmlns:xwss=
   "http://com.sun.xml.wss.configuration"
      dumpMessages="true">
   <xwss:Sign 
      senderCertificateAlias="xws-security-client"/>
</xwss:SecurityConfiguration> 

Signing then Encrypting the Request, Decrypting then Verifying the Signature

The security configuration pair sign-encrypt-client.xml and sign-encrypt-server.xml enable the following tasks:

Client signs and then encrypts and sends the request body.
Server decrypts and verifies the signature.
Server signs and then encrypts and sends the response.

The sign-encrypt-client.xml file looks like this:

<xwss:SecurityConfiguration xmlns:xwss=
   "http://com.sun.xml.wss.configuration"
   useTimestamps="true"
   dumpMessages="true">
   <xwss:Sign/>
   <xwss:Encrypt keyReferenceType="Identifier"
      receiverCertificateAlias="s1as"/>
</xwss:SecurityConfiguration> 

Encrypting then Signing the Request, Verifying then Decrypting the Signature

The security configuration pair encrypt-sign-client.xml and encrypt-sign-server.xml enable the following tasks:

Client encrypts the request body, then signs and sends it.
Server verifies the signature and then decrypts the request body.
Server encrypts and then signs its response.

The encrypt-sign-client.xml file looks like this:

<xwss:SecurityConfiguration xmlns:xwss=
   "http://com.sun.xml.wss.configuration"
      useTimestamps="true"
      dumpMessages="true">
   <xwss:Encrypt keyReferenceType="IssuerSerialNumber"
      receiverCertificateAlias="s1as"/>
   <xwss:Sign/>
</xwss:SecurityConfiguration> 

Adding a UserName Password Token

The security configuration pair user-pass-authenticate-client.xml and dump-server.xml enable the following tasks:

Client adds a username-password token and sends a request.
Server authenticates the username and password against a username-password database.
Server dumps the response upon receipt.

The username-password database must be set up before this security configuration pair will run properly. Refer to Setting Up the Application Server For the Examples for instructions on setting up this database.

The user-pass-authenticate-client.xml file looks like this:

<xwss:SecurityConfiguration xmlns:xwss=
   "http://com.sun.xml.wss.configuration"
      dumpMessages="true">
   <xwss:Authenticate>
      <xwss:UsernameAndPassword
         name="Ron"
         password="noR"
      />
   </xwss:Authenticate>
</xwss:SecurityConfiguration> 

Adding a UserName Password Token, then Encrypting the UserName Token

The security configuration pair encrypted-user-pass-also-client.xml and dump-server.xml enable the following tasks:

Client adds a UsernamePassword token.
Client encrypts the UsernamePassword token before sending the request.
Server decrypts the UsernamePassword token.
Server authenticates the user name and password against a username-password database.
Server dumps the response upon receipt.

The user name-password database must be set up before this security configuration pair will run properly. Refer to Setting Up the Application Server For the Examples for instructions on setting up this database.

The encrypted-user-pass-also-client.xml file looks like this:

<xwss:SecurityConfiguration xmlns:xwss=
   "http://com.sun.xml.wss.configuration"
      dumpMessages="true">
   <xwss:Authenticate>
      <xwss:UsernameAndPassword name="Ron" password="noR"> 
         <xwss:Encrypt
            keyReferenceType="Identifier" 
            receiverCertificateAlias="s1as"/>
      </xwss:UsernameAndPassword> 
   </xwss:Authenticate>
</xwss:SecurityConfiguration> 

Signing the Ticket Element

The security configuration pair sign-ticket-also-client.xml and dump-server.xml enable the following tasks:

Client signs the ticket element present in the message body and then signs the message body itself.
Client sends request.
Server verifies these signatures.
Server dumps the response upon receipt.

The sign-ticket-also-client.xml file looks like this:

<xwss:SecurityConfiguration xmlns:xwss=
   "http://com.sun.xml.wss.configuration"
      useTimestamps="true"
      dumpMessages="true">
   <xwss:Sign target="{http://xmlsoap.org/Ping}ticket"
      keyReferenceType="Identifier"/>
   <xwss:Sign/>
</xwss:SecurityConfiguration> 

Running the Simple Sample Application

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 simple 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.
Modify the build.properties file to set up the security configuration that you want to run for the client and/or server. See Sample Security Configuration File Options for more information on the security configurations options that are already defined for the sample application.
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
On the other containers, the command to build and run the application is: ant run-sample

---

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:

[echo] Running the client program....
[java] ==== Sending Message Start ====
...
[java] ==== Sending Message End ====
[java] ==== Received Message Start ====
...
[java] ==== Received Message 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.