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 two properties 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 UserNameToken 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.

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.5.0/docs/tooldocs/solaris/keytool.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 uncomment one of the client security configuration options. The client configuration options are listed in Sample Security Configuration File Options, and also list which client and server configurations work together. For example, if you want to use XML Encryption for the client, you would uncomment this option:

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

Be sure to uncomment only one client security configuration at a time.

To set the security configuration that you want to run for the server, locate the server.security.config property, and uncomment one of the server security configuration options. 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 uncomment this option:

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

Be sure to uncomment only one client security configuration at a time.

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. Some possible combinations are discussed in more detail in the referenced sections.

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 a response.

The encrypt-client.xml file looks like this:

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              Since no targets have been specified below, the 
contents of
              the soap body would be encrypted by default.
            -->
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as"/>
            </xwss:Encrypt>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

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 sends its response.

The sign-client.xml file looks like this:

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              Note that in the <Sign> operation, a Timestamp is 
exported
              in the security header and signed by default.
            -->
            <xwss:Sign>
                <xwss:X509Token certificateAlias="xws-security-
client"/>
            </xwss:Sign>
            <!--
              Signature requirement. No target is specified, 
hence the 
              soap body is expected to be signed. Also, by 
default, a
              Timestamp is expected to be signed.
            -->
            <xwss:RequireSignature/>
        </xwss:SecurityConfiguration>
   </xwss:Service>

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

</xwss:JAXRPCSecurity> 

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:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:Sign/>
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as" 
keyReferenceType="Identifier"/>
            </xwss:Encrypt>
            <!-- 
              Requirements on messages received:
            -->
            <xwss:RequireEncryption/>
            <xwss:RequireSignature/>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

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 sends its response.

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

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              First encrypt the contents of the soap body
            -->
            <xwss:Encrypt>
                <xwss:X509Token keyReferenceType="Identifier" 
certificateAlias="s1as"/>
            </xwss:Encrypt>
            <!--
              Secondly, sign the soap body using some default 
private key.
              The sample CallbackHandler implementation has code 
to handle
              the default signature private key request.
            -->
            <xwss:Sign/>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

Signing a Ticket

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

Client signs the ticket element, which is inside the message body.
Client signs the message body.
Server verifies signatures.

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

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!-- 
              Signing multiple targets as part of the same 
ds:Signature
              element in the security header
            -->
            <xwss:Sign>
                <xwss:Target type="qname">{http://xmlsoap.org/
Ping}ticket</xwss:Target>
                <xwss:Target type="xpath">//env:Body</xwss:Target>
            </xwss:Sign>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

Adding a Timestamp to a Signature

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

Client signs the request, including a timestamp in the request.

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

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              Export a Timestamp with the specified timeout 
interval (in sec).
            -->
            <xwss:Timestamp timeout="120"/>
            <!--
              The above Timestamp would be signed by the following 
Sign
              operation by default.
            -->
            <xwss:Sign>
                <xwss:Target type="qname">{http://xmlsoap.org/
Ping}ticket</xwss:Target>
            </xwss:Sign>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

Symmetric Key Encryption

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

Client encrypts the request using the specified symmetric key.

This is a case where the client and server security configuration files do not match. This combination works because the server requirement is the same (the body contents must be encrypted) when the client-side security configuration is either encrypt-using-symmkey-client.xml or encrypt-client.xml. The difference in the two client configurations is the key material used for encryption.

The encrypt-using-symmkey-client.xml file looks like this:

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              Encrypt using a symmetric key associated with the 
given alias
            -->
            <xwss:Encrypt>
                <xwss:SymmetricKey keyAlias="sessionkey"/>
            </xwss:Encrypt>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

Adding a UserName Password Token

The security configuration pair user-pass-authenticate-client.xml and user-pass-authenticate-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 sends response.

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

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              Default: Digested password will be sent.
            -->
            <xwss:UsernameToken name="Ron" password="noR"/>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

Encrypt Request Body and a UserNameToken

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

Client encrypts request body.
Client encrypts the UsernameToken as well before sending the request.
Server decrypts the encrypted message body and encrypted UsernameToken.
Server authenticates the user name and password against a username-password database.

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

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <!--
              Export a username token into the security header. 
Assign it
              the mentioned wsu:Id
            -->
            <xwss:UsernameToken name="Ron" password="noR" 
id="username-token"/>
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as"/>
                <xwss:Target type="xpath">//SOAP-ENV:Body</
xwss:Target>
                <!--
                  The username token has been refered as an 
encryption
                  target using a URI fragment
                -->
                <xwss:Target type="uri">#username-token</
xwss:Target>
            </xwss:Encrypt>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

In this sample, the UsernameToken is assigned an id username-token. This id is used to refer to the token as an encryption target within the <xwss:Encrypt> element. The id becomes the actual wsu:id of the UsernameToken in the generated SOAPMessage.

Adding a UserName Password Token, then Encrypting the UserName Token

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

Client adds a UsernameToken.
Client encrypts the UsernameToken before sending the request.
Server decrypts the UsernameToken.
Server authenticates the user name and password against a username-password database.

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

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

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:UsernameToken name="Ron" password="noR"/>
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as" 
keyReferenceType="Identifier"/>
                <xwss:Target type="qname">
                    {http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-
                        secext-1.0.xsd}UsernameToken
                </xwss:Target>
            </xwss:Encrypt>
        </xwss:SecurityConfiguration>
    </xwss:Service>

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

</xwss:JAXRPCSecurity> 

Adding Security at the Method Level

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

Adds security to a particular method.

The simple sample's WSDL file contains two operations, Ping and Ping0, and two port instances of type PingPort. The port names are Ping and Ping0. The method level security configuration file demonstrates how different sets of security operations can be configured for the operations Ping and Ping0 under each of the two Port instances Ping and Ping0.

The method-level-client.xml file looks like this:

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

    <xwss:Service>
        <!--
          Service-level security configuration
        -->
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:Encrypt>
                <xwss:X509Token certificateAlias="s1as"/>
            </xwss:Encrypt>
        </xwss:SecurityConfiguration>

        <xwss:Port name="{http://xmlsoap.org/Ping}Ping"> 

            <!--
              Port-level security configuration. Takes precedence 
over the
              service-level security configuration
            -->
            <xwss:SecurityConfiguration dumpMessages="true"/>

            <xwss:Operation name="{http://xmlsoap.org/Ping}Ping"> 

                <!--
                  Operation-level security configuration. Takes 
precedence
                  over port-level and service-level security 
configurations.
                -->
                <xwss:SecurityConfiguration dumpMessages="true">
                    <xwss:UsernameToken name="Ron"
                                        password="noR"
                                        digestPassword="false"
                                        useNonce="false"/>
                    <xwss:Sign>
                        <xwss:Target type="qname">{http://
xmlsoap.org/Ping}ticket</xwss:Target>
                        <xwss:Target type="qname">{http://
xmlsoap.org/Ping}text</xwss:Target>
                    </xwss:Sign>
                    <xwss:Encrypt>
                        <xwss:X509Token certificateAlias="s1as"/>
                    </xwss:Encrypt>            
                </xwss:SecurityConfiguration>

            </xwss:Operation> 

            <xwss:Operation name="{http://xmlsoap.org/
Ping}Ping0">

                <xwss:SecurityConfiguration dumpMessages="true">
                    <xwss:Encrypt>
                        <xwss:X509Token certificateAlias="s1as"/>
                    </xwss:Encrypt>
                </xwss:SecurityConfiguration>

            </xwss:Operation>

        </xwss:Port>

        <xwss:Port name="{http://xmlsoap.org/Ping}Ping0"> 

            <xwss:SecurityConfiguration dumpMessages="true">
                <xwss:Encrypt>
                    <xwss:X509Token certificateAlias="s1as"/>
                </xwss:Encrypt>
                <xwss:RequireSignature/>
            </xwss:SecurityConfiguration>

            <xwss:Operation name="{http://xmlsoap.org/Ping}Ping"/
> 

            <xwss:Operation name="{http://xmlsoap.org/
Ping}Ping0"/> 

        </xwss:Port>          

    </xwss:Service>

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

</xwss:JAXRPCSecurity>  

In this example, the following has been configured for the Ping operation under port instance Ping:

Inserts a UsernameToken into the request.
Signs the ticket and text child elements of the request body.
Encrypts the contents of the request body.

The following has been configured for the Ping0 operation under port instance Ping:

Encrypt the content of the body of the message.

When the xwss:Encrypt element is specified with no child elements of type xwss:Target, it implies that the default Target (which is SOAP-ENV:Body) has to be encrypted. The same rule applies to xwss:Sign elements with no child elements of type xwss:Target.

The configuration file in this example also configures the following security for all the WSDL operations under port instance Ping0:

Encrypts the request body.
Expects a signed response from the server.Username

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.4Start 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 ==== 

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.