Setting Up To Use XWS-Security With the Sample Applications

This addendum discusses creating and running applications that use the XWS-Security framework, and deploying these applications onto the Sun Java System Application Server Platform Edition 8.1. For deployment onto other containers, read the README.txt file for the example applications for more information.

Follow these steps to set up your system to compile, run, and deploy the sample applications included in this release that use the XWS-Security framework.

  1. Make sure that you have installed the Java 2 Platform, Standard Edition version 1.4.2 or higher. If not, you can download the JDK from the following URL:
    http://java.sun.com/j2se/
  2. If you are using version 1.4.x of the Java SDK, configure a version of a JCE provider that supports RSA encryption. Information on doing this is discussed in Configuring a JCE Provider.

  3. Make sure that you have a container installed. For more information on containers, read http://java.sun.com/webservices/containers/index.html.
  4. Make sure that you have installed Java WSDP 1.6. If not, you can download the JWSDP from the following URL:
    http://java.sun.com/webservices/jwsdp/index.jsp
  5. Set system properties as described in Setting System Properties.

Setting System Properties

The asant (or ant) build files for the XWS-Security samples shipped with this release rely on certain environment variables being set correctly. Make sure that the following environment variables are set to the locations specified in this list. If you are not sure how to set these environment variables, refer to the file <JWSDP_HOME>/xws-security/docs/samples.html for more specific information. This file includes instructions for both the Unix and Microsoft Windows platforms. Throughout this document, instructions for running on the Unix platform will be provided.

  1. Set JAVA_HOME to the location of your J2SE installation directory, for example, /home/<your_name>/j2sdk1.4.2_04/.
  2. Set JWSDP_HOME to the location of your Java WSDP 1.6 installation directory, for example, /home/<your_name>/jwsdp-1.6/.
  3. Set SJSAS_HOME to the location of your Application Server installation directory, for example, /home/<your_name>/SUNWappserver/. If you are deploying onto a different container, set SJSWS_HOME or TOMCAT_HOME instead.
  4. Set ANT_HOME to the location where the asant (or ant) executable can be found. If you are running on the Application Server, this will be <SJSAS_HOME>/bin/. If you are running on a different container, this location will probably be <JWSDP_HOME>/apache-ant/bin/.
  5. Set the PATH variable so that it contains these directories: <JWSDP_HOME>/jwsdp-shared/bin/, <SJSAS_HOME>/bin/, <ANT_HOME>/, and <JAVA_HOME>/bin/.

Configuring a JCE Provider

You only need to perform the steps in this section if you are running Java WSDP 1.6 on J2SE 1.4.x.

The Java Cryptography Extension (JCE) provider included with J2SE 1.4.x does not support RSA encryption. Because the XWS-Security sample applications use RSA encryption, you must download and install a JCE provider that does support RSA encryption in order for these sample applications to run, if you are using encryption, and if you are using a version of the Java SDK prior to version 1.5.0.


Note: RSA is public-key encryption technology developed by RSA Data Security, Inc. The acronym stands for Rivest, Shamir, and Adelman, the inventors of the technology.


If you are running the Application Server on version 1.5 of the Java SDK, the JCE provider is already configured properly. If you are running the Application Server on version 1.4.x of the Java SDK, follow these steps to add a JCE provider statically as part of your JDK environment:

  1. Download and install a JCE provider JAR (Java ARchive) file.
  2. Copy the JCE provider JAR file to <JAVA_HOME>/jre/lib/ext/.
  3. Stop the Application Server (or other container). If the Application Server is not stopped, and restarted later in this process, the JCE provider will not be recognized by the Application Server.
  4. Edit the <JAVA_HOME>/jre/lib/security/java.security properties file in any text editor. Add the JCE provider you've just downloaded to this file. The java.security file contains detailed instructions for adding this provider. Basically, you need to add a line of the following format in a location with similar properties:
  5. security.provider.<n>=<provider class name>

    In this example, <n> is the order of preference to be used by the Application Server when evaluating security providers. Set <n> to 2 for the JCE provider you've just added.

    For example, if you've downloaded ABC JCE provider, and the Java class name of the ABC provider's main class is org.abc.ABCProvider, add this line.

             security.provider.2=org.abc.ABCProvider 
     

    Make sure that the Sun security provider remains at the highest preference, with a value of 1.

       security.provider.1=sun.security.provider.Sun

    Adjust the levels of the other security providers downward so that there is only one security provider at each level.

    The following is an example of a java.security file that provides the necessary JCE provider and keeps the existing providers in the correct locations.

             security.provider.1=sun.security.provider.Sun
             security.provider.2=org.abc.ABCProvider
             security.provider.3=com.sun.net.ssl.internal.ssl.Provider
             security.provider.4=com.sun.rsajca.Provider
             security.provider.5=com.sun.crypto.provider.SunJCE
             security.provider.6=sun.security.jgss.SunProvider

  6. Save and close the file.
  7. Restart the Application Server (or other container).

Setting Up the Application Server For the Examples

To set up the container for running the XWS-Security sample applications included with this release, you need to specify on which container you are running the asant (or ant) build targets (as discussed in Setting Build Properties), and you must point the container to the keystore and truststore files to be used to run the XWS-Security sample applications. For the sample applications, these are the keystore and truststore files included in the /xws-security/etc/ directory. For further discussion of using keystores and truststores with XWS-Security applications, read Keystore and Truststore Files with XWS-Security.

Keystore and Truststore Files with XWS-Security

For the simple sample, the keystore, truststore, and symmetric-key databases used by that example are located in the <JWSDP_HOME>/xws-security/etc/ directory. The locations of these files have been configured in the <JWSDP_HOME>/xws-security/etc/client-security-env.properties and <JWSDP_HOME>/xws-security/etc/server-security-env.properties files for the client and server respectively. These property files are used by the SecurityEnvironmentHandler to handle the Callbacks.

To plug in your own keystores and truststores for an application, make sure that the certificates are of version 3, and that the client truststore contains the certificate of the certificate authority that issued the server's certificate, and vice versa.

XWS-Security requires version 3 (v3) certificates when the keyReferenceType attribute (specified on a xwss:X509Token element) has a value of Identifier, which indicates the use of an X.509 SubjectKeyIdentifier extension. For all other values of the keyReferenceType attribute, a v1 certificate can also be used. Version 3 includes requirements specified by the WSS X509 Token Profile.

Setting Build Properties

To run the sample applications, you must edit the sample build.properties file for that sample application and specify information that is unique to your system and to your installation of Java WSDP 1.6 and the Application Server (or other container).

To edit the build.properties file for the example you want to run, follow these steps:

  1. Change to the directory for the sample application you want to run: <JWSDP_HOME>/xws-security/samples/<example>/.
  2. Copy the build.properties.sample file to build.properties.
  3. Edit the build.properties file, checking that the following properties (where applicable) are set correctly for your system:
    • javahome: Set this to the directory where J2SE version 1.4.2 or higher is installed.

Note: When running on Microsoft Windows, you must escape any backslashes in the javahome, jwsdp.home, and sjsas.home properties with another backslash or use forward slashes as a path separator. So, for example, if your Application Server installation is C:\Sun\AppServer, you must set sjsas.home as follows:

sjsas.home = C:\\Sun\\AppServer

or

sjsas.home=C:/Sun/AppServer


  1. Save and exit the build.properties file.