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.

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

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

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.

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

Service

Table 3-3 Sub-elements of JAXRPCSecurity element
Sub-elements of JAXRPCSecurity	Description
Service	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.
SecurityEnvironmentHandler	Specifies the implementation class name of the security environment handler (Required).

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.

Port

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

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.

Operation

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
SecurityConfiguration	Indicates that what follows is security configuration for the port. This over-rides any security configured for the service.
Operation	Indicates a port within a JAX-RPC service. Any (including zero) number of these elements may be specified.

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.

SecurityConfiguration

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
SecurityConfiguration	This element indicates that what follows is security configuration for the operation. This over-rides any security configured for the port and the service.

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
Timestamp	Indicates that a timestamp must be sent in the outgoing messages.
UsernameToken	Indicates that a username token must be sent in the outgoing messages.
Sign	Indicates that a sign operation needs to be performed on the outgoing messages.
Encrypt	Indicates that an encrypt operation needs to be performed on the outgoing messages.
RequireTimestamp	Indicates that a timestamp must be present in the incoming messages.
RequireUsernameToken	Indicates that a username token must be present in the incoming messages.
RequireSignature	Indicates that the incoming messages must contain a signature.
RequireEncryption	Indicates that the incoming messages must be encrypted.
OptionalTargets	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.

UsernameToken

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

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.

Using Timestamp and includeTimestamp

Table 3-14 Sub-elements of Sign
Sub-elements of Sign	Description
X509Token	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.
Target	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.

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

If a <Timestamp> element is configured, a timestamp will be sent in the message.

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.

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.

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.

RequireTimestamp

Table 3-15 Sub-elements of Encrypt
Sub-elements of Encrypt	Description
X509Token	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.
SymmetricKey	Indicates the symmetric key to be used for encryption. This element must not be specified if the <X509Token> sub-element of <Encrypt> is present.
Target	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.

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.

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.

RequireEncryption

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

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.

OptionalTargets

Table 3-19 Sub-elements of RequireEncryption
Sub-elements of RequireEncryption	Description
Target	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.

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

X509Token

Table 3-20 Sub-elements of OptionalTargets
Sub-elements of OptionalTargets	Description
Target	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.

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.

SecurityEnvironmentHandler

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

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.

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>

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.

simple

This sample application lets you plug in different client and server-side configurations describing security settings. This example has support for digital signatures, XML encryption/decryption, and username token authentication. This example allows and demonstrates combinations of these basic security mechanisms through configuration files. See Understanding and Running the Simple Sample Application for more information on this example.

jaas-sample

The jaas-sample application uses the Java Authentication and Authorization Service (JAAS) to demonstrate the following functionality:

How to obtain a user name and password at run-time and send it in a WSS UsernameToken to the server.

Using JAAS authentication to authenticate the user name and password in the server application.

Accessing the authenticated sender's subject from within the endpoint implementation methods.

Read more about JAAS at http://java.sun.com/products/jaas/.

In this release, the interop sample application that was shipped with Java WSDP 1.4 is not included. However, the simple and jaas-sample applications include many sample configuration files, some of which model the interop scenarios. The sample configuration files can be configured to model all the interop scenarios using the security configuration schema.