Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

What is the XWS-Security Framework?

The XWS-Security framework is used to secure JAX-RPC applications. Use XWS-Security to secure SOAP messages (requests and responses) through signing some parts, or encrypting some parts, or sending username-password authentication info, or some combination of these. Some example applications that use the technology are discussed in Are There Any Sample Applications Demonstrating XWS-Security?.

Use the XWS-Security framework to secure JAX-RPC applications by using the -security option of the wscompile tool. When you create an asant (or ant) target for JAX-RPC clients and services, the wscompile utility generates stubs, ties, serializers, and WSDL files. XWS-Security has been integrated into JAX-RPC through the use of security configuration files. The code for performing the security operations on the client and server is generated by supplying the security configuration files to the JAX-RPC wscompile tool. The wscompile tool is instructed to generate security code via the -security option which specifies the security configuration file. See Configuring Security Configuration Files for more information on creating and using security configuration files.

To use the XWS-Security framework, set up the client and server-side infrastructure. A critical component of setting up your system for XWS-Security is to set up the appropriate database for the type of security (DSig, XML-Enc, UserName Token) to be used. Depending on the structure of your application, these databases could be any combination of keystore files, truststore files, and username-password files. More information on setting up the infrastructure is described in Setting Up the Application Server For the Examples.

Configuring Security Configuration Files

XWS-Security makes it simple to specify client and server-side configurations describing security settings using security configuration files. In this tutorial, build, package, and deploy targets are defined and run using the asant tool. The asant tool is version of the Apache Ant Java-based build tool used specifically with the Sun Java System Application Server (Application Server). If you are deploying to a different container, you may want to use the Apache Ant tool instead.

To configure a security configuration file, follow these steps:

  1. Create a security configuration file. Creating security configuration files is discussed in more detail in Understanding Security Configuration Files. Sample security configuration files are located in the directory <JWSDP_HOME>/xws-security/samples/simple/config/.
  2. Create an asant (or ant) target in the build.xml file for your application that passes in and uses the security configuration file(s). This step is discussed in more detail in How Do I Specify the Security Configuration for the Build Files?.
  3. Create a property in the build.properties file to specify a security configuration file to be used on the client side and a security configuration file to be used on the server side. This step is discussed in more detail in How Do I Specify the Security Configuration for the Build Files?.

Understanding Security Configuration Files

Security configuration files are written in XML. The elements within the XML file that specify the security mechanism(s) to use for an application are enclosed within <xwss:SecurityConfiguration></xwss:SecurityConfiguration> tags. The complete set of child elements along with the attributes that can be placed within these elements are described informally in XWS-Security Configuration File Schema. The formal schema definition (XSD) for XWS-Security Configuration can be viewed in XWS-Security Formal Schema Definition. This section describes a few of these options.

The first set of elements of the security configuration file contain the declaration that this file is a security configuration file. The elements that provide this declaration look like this:

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

Within these declaration elements are elements that specify which type of security mechanism is to be applied to the SOAP message. For example, to apply XML Digital Signature, the security configuration file would include an xwss:Sign element, along with a keystore alias that identifies the private key/certificate associated with the sender's signature. A simple client security configuration file that requires digital signatures would look 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> 

The xwss elements can be listed sequentially so that more than one security mechanism can be applied to the SOAP message. For example, for a client to first sign a message and then encrypt it, create an xwss element with the value Sign (to do the signing first), and then create an xwss element with the value of Encrypt (to encrypt after the signing). Building on the previous example, to add encryption to the message after the message has been signed, the security configuration file would be written like this example:

<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> 

The xwss:RequireSignature element present in the two examples shown is used by the client to indicate that it expects the Response to be a signed response. Similarly the xwss:RequireEncryption element in a client configuration file indicates that the client expects an encrypted response. In the second example, a RequireEncryption and a RequireSignature element specified in that order implies that the client expects the response to be signed and then encrypted.

The xwss:RequireSignature and xwss:RequireEncryption elements appearing in a server configuration file similarly indicate that the server expects the request to be signed and encrypted respectively. The normal behavior of a client or server when it specifies a requirement of the form xwss:RequireSignature or xwss:RequireEncryption is to throw an exception if the requirement is not met by the received response or request.

The xwss:SecurityEnvironmentHandler element appearing under xwss:SecurityConfiguration is a compulsory child element that needs to be specified. The value of this element is the class name of a Java class that implements the javax.security.auth.callback.CallbackHandler interface and handles a set of Callbacks defined by XWS-Security. There are a set of callbacks that are mandatory and that every CallbackHandler needs to implement. A few callbacks are optional and can be used to supply some finer-grained information to the XWS-Security run-time. The SecurityEnvironmentHandler and the Callbacks are described in Writing SecurityEnvironmentHandlers for XWS-Security Applications. The SecurityEnvironmentHandler is essentially a CallbackHandler which is used by the XWS-Security run-time to obtain the private-keys, certificates, symmetric keys, etc. to be used in the signing and encryption operations from the application. For more information, refer to the API documentation for the com.sun.xml.wss.impl.callback package, which is located in the <JWSDP_HOME>/xws-security/docs/api directory, to find the list of mandatory and optional callbacks and the details of the Callback classes.

Another type of security mechanism that can be specified in the security configuration file is user name authentication. In the case of user name authentication, the user name and password of a client need to be authenticated against the user/password database of the server. The xwss element specifies that the security mechanism to use is UsernameToken. On the server-side, refer to the documentation for your server regarding how to set up a user/password database for the server, or read Setting Up To Use XWS-Security With the Sample Applications for a summary. A client-side security configuration file that specifies UsernameToken authentication would look 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> 

The simple sample application includes a number of example security configuration files. The sample configuration files are located in the directory <JWSDP_HOME>/xws-security/samples/simple/config/. Further discussion of the example security configurations can be found in Sample Security Configuration File Options.

XWS-Security Configuration File Schema

When creating a security configuration file, there is a hierarchy within which the XML elements must be listed. This section contains a sketch of the schema for the data for security configuration files. The formal schema definition can be viewed at XWS-Security Formal Schema Definition.


Note: The schema for the configuration files for XWS-Security in Java WSDP 1.5 is significantly different from the schema shipped with Java WSDP 1.4. Security configuration files written under Java WSDP 1.4 will need to be updated to the new schema.


Figure 3-1 shows the XML schema. The tables in XWS-Security Configuration File Schema provide more information on the elements contained within the schema. The following notations are used to describe the schema:


Note: Due to a bug in the current release, there is no way to disable security for a particular Port if there is a <SecurityConfiguration> specified for the enclosing Service. Even if an empty <SecurityConfiguration/> is specified for a Port, the <SecurityConfiguration> specified for the Service will be applied, thereby violating the precedence rules.


Figure 3-1 XWS-Security Configuration File Schema

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

   <xwss:Service>
      ?<xwss:SecurityConfiguration>
          ....
       </xwss:SecurityConfiguration>
      *<xwss:Port name="port_name">
         ?<xwss:SecurityConfiguration>
             ....
          </xwss:SecurityConfiguration>
         *<xwss:Operation name="operation_name">
            ?<xwss:SecurityConfiguration>
                ....
             </xwss:SecurityConfiguration>
          </xwss:Operation>
       </xwss:Port>
   </xwss:Service>

   <xwss:SecurityEnvironmentHandler>
       {handler_implementation_class_name}
   </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity>


<xwss:SecurityConfiguration dumpMessages=("false")|"true">

   ?<xwss:Timestamp timeout=("300")/>

   *<xwss:Encrypt>
      ?<xwss:X509Token 
         ?id="token_id"
         ?certificateAlias="cert_alias"
         keyReferenceType=
           ("Direct")|"Identifier"|"IssuerSerialNumber"/>
      ?<xwss:SymmetricKey keyAlias="key_alias"/>
      *<xwss:Target type=("qname")|"uri"|"xpath"
                    contentOnly=("true")|"false">
          {target_value}
       </xwss:Target>
    </xwss:Encrypt>

   *<xwss:Sign includeTimestamp=("true")|"false">
      ?<xwss:X509Token 
         ?id="token_id"
         ?certificateAlias="cert_alias"
         keyReferenceType=
           ("Direct")|"Identifier"|"IssuerSerialNumber"/>
      *<xwss:Target type=("qname")|"uri"|"xpath">
          {target_value}
       </xwss:Target>
    </xwss:Sign>

   ?<xwss:UsernameToken 
      ?name="user_name"
      ?password="password"
      useNonce=("true")|"false"
      digestPassword=("true")|"false"
      ?id="username_token_id"/>

   ?<xwss:RequireTimestamp/>

   *<xwss:RequireEncryption>
      *<xwss:Target 
         type=("qname")|"uri"|"xpath"
         contentOnly=("true")|"false"
         enforce=("true")|"false">
          {target_value}
       </xwss:Target>
    <xwss:RequireEncryption>

   *<xwss:RequireSignature requireTimestamp=("true")|"false">
      *<xwss:Target 
         type=("qname")|"uri"|"xpath"
         enforce=("true")|"false">
          {target_value}
       </xwss:Target>
    </xwss:RequireSignature>

   ?<xwss:RequireUsernameToken 
      nonceRequired=("true")|"false"
      passwordDigestRequired=("true")|"false"/>

   *<xwss:OptionalTargets>
      *<xwss:Target 
         type=("qname")|"uri"|"xpath">
          {target_value}
       </xwss:Target>
    </xwss:OptionalTargets>
</xwss:SecurityConfiguration> 

Semantics of Security Configuration File Elements

This section contains a discussion regarding the semantics of security configuration file elements.

JAXRPCSecurity

The <JAXRPC> element is the top-level XML element for any XWS-Security configuration file. Table 3-3 provides a description of its sub-elements.

Table 3-3 Sub-elements of JAXRPCSecurity element 
Sub-elements of JAXRPCSecurity
Description
Indicates a JAX-RPC service within the XWS-Security environment for which XWS-Security can be configured. In this release, one service per configuration file is supported. Future releases may upgrade support to understand multiple services.
Specifies the implementation class name of the security environment handler (Required).

Service

The <Service> element indicates a JAX-RPC service within the XWS-Security environment for which XWS-Security can be configured. Table 3-4 provides a description of its sub-elements.

Table 3-4 Sub-elements of Service element 
Sub-elements of Service
Description
Indicates that what follows is the security configuration for the service.
A port within a JAX-RPC service. Any (including zero) number of these elements may be specified.

Port

The <Port> element represents a port within a JAX-RPC service. Table 3-5 provides a description of its attributes, Table 3-6 provides a description of its sub-elements.

Table 3-5 Attributes of Port element 
Attributes of Port
Description
name
Name of the port as specified in the wsdl (Required).

Table 3-6 Sub-elements of Port element 
Sub-elements of Port
Description
Indicates that what follows is security configuration for the port. This over-rides any security configured for the service.
Indicates a port within a JAX-RPC service. Any (including zero) number of these elements may be specified.

Operation

The <Operation> element creates a security configuration at the operation level, which takes precedence over port and service-level security configurations. Table 3-7 provides a description of its attributes, Table 3-8 provides a description of its sub-elements.

Table 3-7 Attributes of Operation  
Attributes of Operation
Description
name
Name of the operation as specified in the WSDL file, for example, name="{http://xmlsoap.org/Ping}Ping0". (Required)

Table 3-8 Sub-elements of Operation  
Sub-elements of Operation
Description
This element indicates that what follows is security configuration for the operation. This over-rides any security configured for the port and the service.

SecurityConfiguration

The <SecurityConfiguration> element specifies a security configuration. Table 3-9 provides a description of its attributes, Table 3-10 provides a description of its sub-elements. The sub-elements of SecurityConfiguration can appear in any order. The order in which they appear determines the order in which they are executed, with the exception of the OptionalTargets element.

Table 3-9 Attributes of SecurityConfiguration  
Attributes of SecurityConfiguration
Description
dumpMessages
If dumpMessages is set to true, all incoming and outgoing messages are printed at the standard output. The default value is false.

Table 3-10 Sub-elements of SecurityConfiguration
Sub-elements of SecurityConfiguration
Description
Indicates that a timestamp must be sent in the outgoing messages.
Indicates that a username token must be sent in the outgoing messages.
Indicates that a sign operation needs to be performed on the outgoing messages.
Indicates that an encrypt operation needs to be performed on the outgoing messages.
Indicates that a timestamp must be present in the incoming messages.
Indicates that a username token must be present in the incoming messages.
Indicates that the incoming messages must contain a signature.
Indicates that the incoming messages must be encrypted.
Specifies a list of elements on which security operations are not required in the incoming messages, but are allowed.

Timestamp

The <Timestamp> element specifies that a timestamp must be sent in outgoing messages. For a discussion of using the Timestamp element with the includeTimestamp attribute of Sign, see Using Timestamp and includeTimestamp. Table 3-11 provides a description of its attributes.

Table 3-11 Attributes of Timestamp  
Attributes of Timestamp
Description
timeout
Value in seconds after which the timestamp should be considered expired. Default value is "300".

UsernameToken

The <UsernameToken> element is used when a UsernameToken should be sent with outgoing messages. This UsernameToken contains the sender's user and password information. Table 3-12 provides a description of its attributes.

Table 3-12 Attributes of UsernameToken  
Attributes of UsernameToken
Description
name
The name of the user. If not specified, security environment handler must provide it at runtime.
password
The password of the user. If not specified, attempt would be made to obtain it from the security environment handler at runtime. Default value is true.
digestPassword
Indicates whether to send password in digest form or not. Default value is true.
useNonce
Indicates whether to send a nonce inside the username token or not. Sending a nonce helps in preventing replay attacks. Default value is true.
id
The id to be set on the username token in the message to be sent. This is also useful in referring to the token from other places in the security configuration file.

Sign

The <Sign> element is used to indicate that a sign operation needs to be performed on the outgoing messages. Table 3-13 provides a description of its attributes, Table 3-15 provides a description of its sub-elements.

Table 3-13 Attributes of Sign  
Attributes of Sign
Description
includeTimestamp
Indicates whether to also sign a timestamp as part of this signature or not. This is a mechanism useful in preventing replay attacks. The default value is true. Note that a true value for this attribute makes sure that a timestamp will be sent in the outgoing messages even if the <Timestamp> element has not been specified. Also note that at most one timestamp is sent in a message.

Table 3-14 Sub-elements of Sign  
Sub-elements of Sign
Description
Indicates the certificate corresponding to the private key used for signing. If this element is not present, attempt is made to get the default certificate from the security environment handler.
Indicates the target to be signed. Zero or more of these elements may be specified. If none is specified, the soap body is assumed to be the target.

Using Timestamp and includeTimestamp

The following configurations of Timestamp and the includeTimestamp attribute of the Sign element have the following effect:

  1. If a <Timestamp> element is configured, a timestamp will be sent in the message.
  2. If the includeTimestamp attribute on <Sign> has value true and <Timestamp> is not configured, a timestamp (with default timeout value) will be sent in the message and included in the signature.
  3. If the includeTimestamp attribute on <Sign> has value true and <Timestamp> is configured, a timestamp with the properties (e.g, timeout) specified on the <Timestamp> will be sent in the message and also be included in the signature.
  4. If the includeTimestamp attribute on <Sign> has value false, a timestamp is not included in the signature.
Encrypt

The <Encrypt> element is used to indicate that an encrypt operation needs to be performed on the outgoing messages. Table 3-15 provides a description of its sub-elements.

Table 3-15 Sub-elements of Encrypt  
Sub-elements of Encrypt
Description
Indicates the certificate to be used for encryption. If this element is not present, attempt is made to get the default certificate from the security environment handler. This element must not be specified if the <SymmetricKey> sub-element of <Encrypt> is specified.
Indicates the symmetric key to be used for encryption. This element must not be specified if the <X509Token> sub-element of <Encrypt> is present.
Indicates the target to be signed. Zero or more targets for encryption can be specified. If none is specified, the contents of the soap body are encrypted.

RequireTimestamp

If the <RequireTimestamp> element is present, a timestamp, in the form of a wsu:Timestamp element, must be present in the incoming messages. If the RequireTimestamp element is not specified, a Timestamp is not required. A timestamp specifies the particular point in time it marks. You may also want to consider using a nonce, which is a value that you should never receive more than once.

This element does not have any attributes or sub-elements.

RequireUsernameToken

The <RequireUsernameToken> element is used to specify that a username token must be present in the incoming messages. Table 3-16 provides a description of its attributes.

Table 3-16 Attributes of RequireUsernameToken  
Attributes of RequireUsernameToken
Description
passwordDigestRequired
Indicates whether the username tokens in the incoming messages are required to contain the passwords in digest form or not. Default value is true. (See also: digestPassword attribute on <UsernameToken>)
nonceRequired
Indicates whether a nonce is required to be present in the username tokens in the incoming messages. Default value is true. (See also: useNonce attribute on <UsernameToken>)

RequireSignature

The <RequireSignature> element is specified when a digital signature is required for all specified targets. If no signature is present, an exception is thrown. Table 3-17 provides a description of its attributes, Table 3-18 provides a description of its sub-elements.

Table 3-17 Attributes of RequireSignature  
Attributes of RequireSignature
Description
requireTimestamp
Indicates whether a timestamp must be included in the signatures in the incoming messages. Default value is true. (See also: includeTimestamp attribute on <Sign>)

Table 3-18 Sub-elements of RequireSignature  
Sub-elements of RequireSignature
Description
Specifies the target that should have been signed. Zero or more of these elements can be specified. If this element is not specified, it indicates that the soap body is required to be signed.

RequireEncryption

The <RequireEncryption> element is used when encryption is required for all incoming messages. If encryption is not present, an exception is thrown. Table 3-19 provides a description of its sub-elements.

Table 3-19 Sub-elements of RequireEncryption  
Sub-elements of RequireEncryption
Description
Specifies the target that should have been encrypted. Zero or more of these elements can be specified. If this element is not specified, it indicates that the contents of the soap body are required to be encrypted.

OptionalTargets

The <OptionalTargets> element is used when an operation is optional for a specific target. Table 3-20 provides a description of its sub-elements.

Table 3-20 Sub-elements of OptionalTargets  
Sub-elements of OptionalTargets
Description
Indicates that a security operation is allowed to be performed on this target though it was not required. One or more of these elements can be specified.

X509Token

The <X509Token> element is used to specify that a username token must be present in the incoming messages. Table 3-21 provides a description of its attributes.

Table 3-21 Attributes of X509Token  
Attributes of X509Token
Description
id
The id to be assigned to this token in the message. This attribute is useful in referring the token from other places in the security configuration file.
certificateAlias
The alias associated with the token (certificate).
keyReferenceType
The reference mechanism to be used for referring to the X509 token (certificate) which was involved in the security operation, in the outgoing messages. The default value is Direct. The list of allowed values for this attribute and their description is as follows:
1. Direct - certificate is sent along with the message.
2. Identifier - subject key identifier extension value of the certificate is sent in the message.
3. IssuerSerialNumber - issuer name and serial number of the certificate are sent in the message.

Target

The <Target> sub-element contains a string that can be used along with the keyReferenceType to identify the resource that needs to be signed or encrypted. If the Target sub-element is not specified, the default value is a target that points to the contents of the SOAP body of the message. The value of this element is specified as a text node inside this element. Its attributes are described in Table 3-22.

Table 3-22 Attributes of Target  
Attributes of Target
Description
type
Indicates the type of the target value. Default value is qname. The list of allowed values for this attribute and their description is as follows:
1. qname - If the target element has a local name Name and a namespace URI some-uri, the target value is {some-uri}Name.
2. xpath - Indicates that the target value is the xpath of the target element.
3. uri - If the target element has an id some-id, then the target value is #some-id.
contentOnly
Indicates whether the complete element or only the contents needs to be encrypted (or is required to be encrypted). The default value is true. (Relevant only for <Encrypt> and <RequireEncryption> targets)
enforce
If true, indicates that the security operation on the target element is definitely required. Default value is true. (Relevant only for <RequireSignature> and <RequireEncryption> targets)

SymmetricKey

The <SymmetricKey> element indicates the symmetric key to be used for encryption. This element must not be specified if the <X509Token> sub-element of <Encrypt> is present. Its attributes are discussed in Table 3-23.

Table 3-23 Attributes of SymmetricKey  
Attributes of SymmetricKey
Description
keyAlias
The alias of the symmetric key to be used for encryption. This attribute is required.

SecurityEnvironmentHandler

The <SecurityEnvironmentHandler> element specifies the implementation class name of the security environment handler. Read Writing SecurityEnvironmentHandlers for XWS-Security Applications for more information on SecurityEnvironmentHandlers.

How Do I Specify the Security Configuration for the Build Files?

After the security configuration files are created, you can easily specify which of the security configuration files to use for your application. In the build.properties file for your application, create a property to specify which security configuration file to use for the client, and which security configuration file to use for the server. An example from the simple sample application does this by listing all of the alternative security configuration files, and uncommenting only the configuration to be used. The simple sample uses the properties that are shown in boldface:

# look in /config directory for alternate security 
# configurations
# Client Security Config. file
#client.security.config=config/dump-client.xml
client.security.config=config/sign-client.xml
#client.security.config=config/encrypt-client.xml
#client.security.config=config/user-pass-authenticate-
  client.xml
#client.security.config=config/encrypt-usernameToken-
  client.xml
#client.security.config=config/encrypted-user-pass-client.xml
#client.security.config=config/sign-encrypt-client.xml
#client.security.config=config/encrypt-sign-client.xml
#client.security.config=config/sign-ticket-also-client.xml
#client.security.config=config/timestamp-sign-client.xml
# Use this client with encrypt-server.xml configured for 
# server.security.config
#client.security.config=config/encrypt-using-symmkey-
  client.xml

# Server Security Config. file
#server.security.config=config/dump-server.xml
server.security.config=config/sign-server.xml
#server.security.config=config/encrypt-server.xml
#server.security.config=config/user-pass-authenticate-
  server.xml
#server.security.config=config/encrypt-usernameToken-
  server.xml
#server.security.config=config/encrypted-user-pass-server.xml
#server.security.config=config/sign-encrypt-server.xml
#server.security.config=config/encrypt-sign-server.xml
#server.security.config=config/sign-ticket-also-server.xml
#server.security.config=config/timestamp-sign-server.xml 

As you can see from this example, several security scenarios are listed in the build.properties file. To run a particular security configuration option, simply uncomment one of the entries for a client configuration file, uncomment the corresponding entry for the server configuration file, and comment all of the other options.

In general, the client and server configuration files should match. However, in some cases, more than one client configuration can be used with a server configuration. For example, either encrypt-using-symmkey-client.xml or encrypt-client.xml can be used with encrypt-server.xml. 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.

After the property has been defined in the build.properties file, you can refer to it from the file that contains the asant (or ant) targets, which is build.xml.

When you create an asant (or ant) target for JAX-RPC clients and services, you use the wscompile utility to generate stubs, ties, serializers, and WSDL files. XWS-Security has been integrated into JAX-RPC through the use of security configuration files. The code for performing the security operations on the client and server is generated by supplying the configuration files to the JAX-RPC wscompile tool. The wscompile tool can be instructed to generate security code by making use of the -security option and supplying the security configuration file. An example of the target that runs the wscompile utility with the -security option pointing to the security configuration file specified in the build.properties file to generate server artifacts, from the simple sample application, looks like this:

<target name="gen-server" depends="prepare"
   description="Runs wscompile to generate server artifacts">
    <echo message="Running wscompile...."/>
    <wscompile 
       verbose="${jaxrpc.tool.verbose}" 
       xPrintStackTrace="true"    
       keep="true" fork="true" 
       security="${server.security.config}"
       import="true"
       model=
         "${build.home}/server/WEB-INF/${model.rpcenc.file}"
       base="${build.home}/server/WEB-INF/classes"
       classpath="${app.classpath}"
       config="${config.rpcenc.file}">
      <classpath>
        <pathelement 
          location="${build.home}/server/WEB-INF/classes"/>
        <path refid="app.classpath"/>
      </classpath>
    </wscompile>
  </target> 

An example of the target that runs the wscompile utility with the security option pointing to the security configuration file specified in the build.properties file to generate the client-side artifacts, from the simple sample application, looks like this:

<target name="gen-client" depends="prepare"
  description="Runs wscompile to generate client side artifacts">
    <echo message="Running wscompile...."/>
    <wscompile 
       fork="true" 
       verbose="${jaxrpc.tool.verbose}"
       keep="true"
       client="true" 
       security="${client.security.config}"
       base="${build.home}/client"
       features=""
       config="${client.config.rpcenc.file}">
       <classpath>
         <fileset dir="${build.home}/client">
           <include name="secenv-handler.jar"/>
         </fileset>
         <path refid="app.classpath"/>
       </classpath>
    </wscompile>
</target> 

Refer to the documentation for the wscompile utility in Useful XWS-Security Command-Line Tools for more information on wscompile options.

Are There Any Sample Applications Demonstrating XWS-Security?

This release of the Java WSDP includes two example applications that illustrate how a JAX-RPC developer can use the XML and Web Services Security framework. The example applications can be found in the <JWSDP_HOME>/xws-security/samples/<sample_name>/ directory. Before you can run the sample applications, you must follow the setup instructions in Setting Up To Use XWS-Security With the Sample Applications.

The sample applications print 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 these examples, the server-side code is found in the <JWSDP_HOME>/xws-security/samples/<sample_name>/server/src/<sample_name>/ directory. Client-side code is found in the <JWSDP_HOME>/xws-security/samples/<sample_name>/client/src/<sample_name>/ directory. The asant (or ant) targets build objects under the /build/server/ and /build/client/ directories.

This example can be deployed onto any of the following containers. For the purposes of this tutorial, only deployment to the Sun Java System Application Server Platform Edition 8 will be discussed. The README.txt file for each example provides more information on deploying to the other containers. The containers can be downloaded from http://java.sun.com/webservices/containers/index.html.

This example uses keystore and truststore files that are included in
the <JWSDP_HOME>/xws-security/etc/ directory. The container on which you choose to deploy your applications must be configured to recognize the keystore and truststore files. For more information on using keystore and truststore files, read the keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html. For more information on how to configure the Application Server to recognize these files, refer to Setting Up the Application Server For the Examples, or to the application's README.txt file if deploying on the Web Server or Tomcat.

The following sample applications are included:

Divider
Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

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.