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.
- 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/
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.
- Make sure that you have a container installed. For more information on containers, read http://java.sun.com/webservices/containers/index.html.
- 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- Set system properties as described in Setting System Properties.
- Read the information in Setting Up the Application Server For the Examples.
Setting System Properties
The
asant
(orant)
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.
- Set
JAVA_HOME
to the location of your J2SE installation directory, for example,/home/<
your_name
>/j2sdk1.4.2_04/
.- Set
JWSDP_HOME
to the location of your Java WSDP 1.6 installation directory, for example,/home/<
your_name
>/jwsdp-1.6/
.- 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, setSJSWS_HOME
orTOMCAT_HOME
instead.- Set
ANT_HOME
to the location where theasant
(orant
) 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/.
- 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:
- Download and install a JCE provider JAR (Java ARchive) file.
- Copy the JCE provider JAR file to
<
JAVA_HOME
>/jre/lib/ext/
.- 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.
- 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. Thejava.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:
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
> to2
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.ABCProviderMake 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- Save and close the file.
- 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
(orant)
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 theSecurityEnvironmentHandler
to handle theCallbacks
.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 axwss:X509Token
element) has a value ofIdentifier
, which indicates the use of an X.509SubjectKeyIdentifier
extension. For all other values of thekeyReferenceType
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:
Note: When running on Microsoft Windows, you must escape any backslashes in the
javahome
,jwsdp.home
, andsjsas.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 setsjsas.home
as follows:sjsas.home = C:\\Sun\\AppServer
orsjsas.home=C:/Sun/AppServer
sjsas.home
: To specify that you are running under the Application Server, set this property to the directory where the Application Server is installed and make sure there is not a comment symbol (#
) to the left of this entry. If you are running under a different container, set the location for its install directory under the appropriate property name (tomcat.home
orsjsws.home
) and uncomment that entry instead. Only one of the container home properties should be uncommented at any one time.username
,password
: Enter the appropriate username and password values for a user assigned to the role ofadmin
for the container instance being used for this sample. A user with this role is authorized to deploy applications onto the Application Server.endpoint.host
,endpoint.port
: If you changed the default host and/or port during installation of the Application Server (or other container), change these properties to the correct values for your host and port. If you installed the Application Server using the default values, these properties will already be set to the correct values.VS.DIR
=If you are running under the Sun Java System Web Server, enter the directory for the virtual server. If you are running under any other container, you do not need to modify this property.jwsdp.home
: Set this property to the directory where Java WSDP is installed. The keystore and truststore URL's for the client are configured relative to this property.http.proxyHost
,http.proxyPort
: If you are using remote endpoints, set these properties to the correct proxy server address and port. If you are not using remote endpoints, put a comment character (#
) before these properties. A proxy server will follow the format ofmyserver.mycompany.com
. The proxy port is the port on which the proxy host is running, for example,8080
.