Installing and Configuring XML Security

To work with XML Security, you need to get a current build. The XML Security builds are available at http://xml.apache.org/security/download.html. Click the link to choose a mirror site. On the page listing the mirrors, click a mirror that’s close to you. Doing so will take you to a distribution director with entries for the C-library version, the Java-library version, and a PGP public key file in keys.asc. When you click the link for the Java-library, you’ll be presented with a list of distributions. Both binary and source distributions are provided.

For the sake of example, let’s assume you’re interested in the latest development release 1.0.5D2. The binary distribution is in a file named xml-security-bin-1_0_5D2.zip. The source distribution is in a file named xml-security-src-1_0_5D2.zip. XML Security is providing distributions only in zip file format. This shouldn’t be a problem, because unzipping utilities exist for Windows, UNIX, Linux, and Mac OS X. There are PGP signature files for each of the distribution files—they have the same name as the associated distribution file but end in .sig. The signature file for the xml-security-bin-1_0_5D2.zip file is in the file xml-security-bin-1_0_5D2. You should create a new directory for the xml-security distribution you’re unpacking and unzip the files into it. Once you’ve done that, the new directory contains the following directories and files:

• ant—Ant taskdefs used by the XML Security build file.

• build—The results of running the Ant build:

  • doc—HTML documentation.

  • xmlsec.jar—XML Security library.

  • xmlsecSamples.jar—XML Security sample programs.

  • xmlsecTests.jar—XML Security test suite.

• data—The data files for the XML Security test suite.

• libs—The jar files required by XML Security. Note that you need Xalan 2.2 or later if you’re going to use XPath or XSLT-related functionality.

• src_samples—The source code for the sample applications.

• build.xml—The Ant build file for XML Security.

• Install—Simple installation instructions.

• Keys.asc—The PGP keys files for the XML Security developers.

• License.txt—The Apache Software License.

• README—A brief README file.

• README.html—The gateway to the XML security documentation.

You also need to download the Bouncy Castle JCE Provider, and if you’re using JDK 1.3, the Bouncy Castle cleanroom JCE implementation for Java 1.3. You can obtain these files from the Bouncy Castle Website at www.bouncycastle.org. For JDK 1.3, you’ll want the combined JCE provider and implementation jar. This file is named jce-jdk13-nnn.jar, where nnn is the version number. For JDK 1.3, you’ll want the file bcprov-jdk14-nnn.jar, again, where nnn is the version number. Your classpath must include the BouncyCastle jar as well as the xmlsec.jar from the build directory and the various jars in the lib directory.

If you’re running JDK 1.4, you may need to deal with two additional items. XML Security depends on a released version of Xalan with a version number of at least 2.2. The version of Xalan that’s built into JDK 1.4 is Xalan 2.2D13, which is incompatible. To solve this problem, you should take the xml-apis.jar and xalan.jar files from XML Security’s lib directory and install them in the JDK using the Java Endorsed Standards Mechanism. Doing so overrides the version built into the JDK.

The other JDK 1.4 issue you may run into is related to encryption strength. By default, the JDK 1.4 ships with a restricted encryption policy file. Your application may require encryption algorithms that need cryptography with unlimited strength. You can change the JCE policy file by downloading the JCE Unlimited Strength Jurisdiction Policy Files for the JDK version you’re using. You can obtain these files via http://java.sun.com/products/jce/index-14.html#UnlimitedDownload. Once you’ve downloaded the jar file, you can follow the instructions inside it to install the needed files. Basically, you take the contents of the jar file and copy them over the corresponding files in JAVA_HOME/jre/lib/security. You should back up the old files somewhere in case you need to use them again.