What is the XWS-Security Framework?

You use the XWS-Security framework to secure JAX-RPC applications. This means that you 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?.

You 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, 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 security 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. See Configuring Security Configuration Files for more information on creating and using security configuration files.

To use the XWS-Security framework, you need to 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, User Name Token) you are planning to use. 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 Platform Edition 8 (Application Server). If you are deploying to a different container, you may want to use the Apache Ant tool instead.

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. A complete set of options for values that can be placed within these elements are listed in Useful XWS-Security Command-Line Tools. 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:

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 security configuration file that uses digital signatures would look like this:

The xwss elements can be listed sequentially so that more than one security mechanism can be applied to the SOAP message. For example, to first sign a message and then encrypt it, you would 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:

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 first specifies that the security mechanism to use is Authenticate. A second xwss element is nested within the Authenticate elements to specify which type of authentication to use (currently only UsernameAndPassword is supported). 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 The User Name/Password Database For the Application Server for a summary. A client-side security configuration file that specifies UsernameAndPassword authentication would look like this:

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.

Note: In the following schema, a ? character before an attribute or subelement indicates that zero or one instances of this attribute or subelement are allowed. A * character before an attribute or subelement indicates that zero or more instances of this attribute or subelement are allowed.

Table 3-3 shows the schema diagram on the left, and a description of the schema on the right.

Table 3-3 Security Configuration File Schema Elements and Description
Security Configuration File Schema Elements	Description
`SecurityConfiguration`	This element is the top-level XML element that indicates that what follows is a security configuration file.
`[attributes]`
`?useTimestamps`	If `useTimestamps` is set to `true`, a timestamp is sent with the message. If `useTimestamps` is not specified (default) or is set to `false`, a `Timestamp` is not sent with the message. A timestamp says which 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.
`?dumpMessages`	If `dumpMessages` is set to `true`, all incoming and outgoing messages are printed at the standard output. If `dumpMessages` is not specified (default) or is set to `false`, no incoming or outgoing messages are printed.
`[subelements]`	These subelements can appear in any order. The order in which they appear determines the order in which they are executed.
`*Encrypt`	Use the `Encrypt` element to request that an encryption operation be performed.
`[attributes]`
`?target`	The `target` attribute is a string representation of the `QName` of the element to be targeted for encryption. For example, if the element has a local name `Name` and a namespace URI `some-uri`, the target value is `{some-uri}Name`. The default is the `QName` of the SOAP Body.
`?encryptContentOnly`	If `encryptContentOnly` is set to `true`, only the contents of the target element are encrypted. The default is `true`.
`?receiverCertificateAlias`	The truststore alias corresponding to the certificate of the receiver of the message. This attribute is required when `Encrypt` is used.
`?keyReferenceType`	The reference mechanism of the certificate used for encryption that is to be used in preparing the message to be sent. This reference mechanism helps the receiver locate the same certificate at his end. The certificate leads the receiver to its private key. The receiver uses this private key to decrypt the message. Valid values for `keyReferenceType` are `Direct`, `Identifier`, and `IssuerSerialNumber`. If `Direct` is used, the receiver certificate is sent along with the message. `Direct` is the default value. If `Identifier` is used, the Base64-encoded subject key identifier extension value of the certificate is sent in the message. If `IssuerSerialNumber` is used, the issuer name and serial number of the certificate used are sent in the message.
`*Sign`	Use the `Sign` element to request that a digital signature operation be performed.
`[attributes]`
`?target`	The `target` attribute is a string representation of the `QName` of the element to be targeted for signature. For example, if the element has a local name `Name` and a namespace URI `some-uri`, the target value is `{some-uri}Name`. The default is the `QName` of the SOAP Body.
`?senderCertificateAlias`	The keystore alias corresponding to the certificate/private-key pair of the sender used for signing. If there is a single key entry in the keystore, this attribute is not required. If there is more than one key entry in the keystore, this attribute is required.
`?keyReferenceType`	The reference mechanism of the certificate corresponding to the private-key used for the signature that is to be used in preparing the message to be sent. This reference mechanism helps the receiver locate the same certificate at his end. The retrieved certificate helps the receiver verify the signed message. Valid values for `keyReferenceType` are `Direct`, `Identifier`, and `IssuerSerialNumber`. If `Direct` is used, the receiver certificate is sent along with the message. `Direct` is the default value. If `Identifier` is used, the Base64-encoded subject key identifier extension value of the certificate is sent in the message. If `IssuerSerialNumber` is used, the issuer name and serial number of the certificate used are sent in the message.
`?signToken`	If `signToken` is set to `true`, the security token (certificate data) associated with the signature is also signed in the same message. The default value is `false`.
`*Authenticate`	Use the `Authenticate` element when the sender wants to be authenticated at the receiver end.
`[subelements]`
`?UsernameAndPassword`	Use the `UsernameAndPassword` element when a `UsernameToken` should be sent with the message. This `UsernameToken` would contain the sender's user and password information. This subelement is mandatory when `Authenticate` is used.
`[attributes]`
`?name`	The name of the user. The `name` attribute is mandatory when `UsernameAndPassword` is used.
`?password`	The password of the user. The `password` attribute is mandatory when `UsernameAndPassword` is used.
`?useNonce`	If `useNonce` is set to `true`, a nonce value is sent with the username token. A nonce is different from a timestamp because a timestamp says which particular point in time it marks. A nonce is a value that you should never receive more than once. WSS uses nonces to protect services such that servers can detect a replay of a previously used message authenticator (at the same service). Sending a nonce value is an effective counter-measure against replay attacks. The default value is `true`. For more information about a nonce, read `http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf`.
`?digestPassword`	If `digestPassword` is set to `true`, the password is transported in digest form. The default value is `true`.
`[subelements]`
`?Encrypt`	Use the `Encrypt` subelement of `UsernameAndPassword` if the `UsernameToken` needs to be encrypted. If the `Encrypt` subelement is used, the target of encryption is the `UsernameToken`. The complete token, not only the contents, is encrypted.

`?receiverCertificateAlias`	The truststore alias corresponding to the certificate of the receiver of the message. This attribute is required when `Encrypt` is used.
`?keyReferenceType`	The reference mechanism of the certificate used for encryption that is to be used in preparing the message to be sent. This reference mechanism helps the receiver locate the same certificate at his end. The certificate leads the receiver to its private key. The receiver uses this private key to decrypt the message. Valid values for `keyReferenceType` are `Direct`, `Identifier`, and `IssuerSerialNumber`. If `Direct` is used, the receiver certificate is sent along with the message. `Direct` is the default value. If `Identifier` is used, the Base64-encoded subject key identifier extension value of the certificate is sent in the message. If `IssuerSerialNumber` is used, the issuer name and serial number of the certificate used are sent in the message.

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 using the following properties:

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 the security configuration you want to run, and comment all of the other options.

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:

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:

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 shown. The README.txt file for each example provides more information on deploying to the other containers.

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