Apache WSS4J 2.0.0 - part I

Apache WSS4J is an open-source Java implementation of the security standards for web services. The project was founded in 2004 and is widely used, including by the web service stacks Apache CXF and Apache Axis. Apache WSS4J 1.6.0 was released in April 2011, and featured a wide range of improvements such as support for SAML 2.0 assertions. This blog post is the first in a series of articles on the new features and changes that will be arriving in the imminent WSS4J 2.0.0 release. In this article, we will provide an overview of the new features, the changed project structure, as well as a migration guide for existing users.

1) Overview of new features

Apache WSS4J 2.0.0 delivers the following major new features, along with a substantial set of minor features:

• Support for a streaming (StAX) based WS-Security implementation that covers all of the main specifications. This is both faster and uses far less memory than the DOM-based alternative.
• A WS-SecurityPolicy model that can be shared between both DOM + StAX implementations.
• Support for "real-time" WS-SecurityPolicy validation for the StAX implementation.
• Support for the SOAP with Attachments (SWA) Profile 1.1 specification.
• Support for caching based on EhCache.
• Support for encrypting passwords in Crypto properties files using Jasypt

These new features will be covered in more detail in future articles.

2) Project Structure

The source for Apache WSS4J 2.0.0 can be perused here. Support for building WSS4J using Apache Ant has been dropped, Apache Maven must be used to build the project. Support for JDK 1.5 has also been dropped. Unlike previous releases, WSS4J 2.0.0 now contains multiple Maven modules, the most important of which are as follows:

• bindings: Contains code generated from security schemas
• policy: Contains a (shared) WS-SecurityPolicy model
• ws-security-common: Shared code between the DOM + StAX implementations
• ws-security-dom: The DOM implementation.
• ws-security-stax: The StAX implementation.
• ws-security-policy-stax: The WS-SecurityPolicy validation layer for the StAX code.

Note that the old "org.apache.ws.security" package is no longer used as part of this refactoring, instead each module uses "org.apache.wss4j.X". The WS-SecurityPolicy model in the "policy" module replaces different models used in web service stacks such as Apache CXF + Axis, thus simplifying the code in the security components of these projects. The "ws-security-policy-stax" module gives us the ability to validate WS-SecurityPolicy against an inbound request in "real-time". This is opposed to the DOM implementation, which only validates WS-SecurityPolicy against the request after security processing has completed.

3) Migration Guide

Care has been taken to limit the impact of changes in WSS4J 2.0.0 on existing user configuration. However there are some inevitable incompatibilities, facilitated by the major version upgrade. I will details some of these changes in this section, and then expand on them on the website in more detail closer to release. These changes only affect the DOM in-memory implementation, as the StAX implementation is new in this release.

3.1) Signature Verification Crypto

In WSS4J 1.6.x, it was only possible to specify a Crypto implementation for both Signature Creation + Verification. In WSS4J 2.0.0, there is now a separate Signature Verification Crypto instance, that can be configured via the following configuration tags:

• "signatureVerificationPropFile" - The path of the crypto property file to use for Signature verification.
• "signatureVerificationPropRefId" - The key that holds a reference to the object holding complete information about the signature verification Crypto implementation.

3.2) WSPasswordCallback package change

In WSS4J, you need to define a CallbackHandler to supply a password to a WSPasswordCallback Object when dealing with UsernameTokens, or to unlock private keys for Signature creation, etc. In WSS4J 2.0.0, the functionality is exactly the same, except that the package of the WSPasswordCallback Object has changed from "org.apache.ws.security" to "org.apache.wss4j.common.ext". Any CallbackHandler implementation will need to be updated to use the new package.

3.3) SAML creation changes

A CallbackHandler implementation is required to create a SAML Assertion, by populating various beans. Similar to the WSPasswordCallback package change, there are also some package changes for SAML. The base package for the SAMLCallback class, and of the various "bean" classes, has changed from "org.apache.ws.security.saml.ext" to "org.apache.wss4j.common.saml".

In addition, the "samlPropFile" and "samlPropRefId" configuration tags have been removed. These tags pointed to a properties file/object, which could be used to define the issuer of the Assertion, as well as the Crypto configuration used to sign the Assertion. In WSS4J 2.0.0, it is the responsibility of the CallbackHandler to configure the SAMLCallback Object appropriately. The SAMLCallback Object has the following new properties, which can be configured to sign an Assertion:

• boolean signAssertion
• String issuerKeyName
• String issuerKeyPassword
• Crypto issuerCrypto
• boolean sendKeyValue
• String canonicalizationAlgorithm
• String signatureAlgorithm

3.4) Caching changes

WSS4J 2.0.0 uses three EhCache-based caches by default for the following scenarios, to prevent replay attacks:

• UsernameToken nonces
• Signed Timestamps
• SAML 2.0 OneTimeUse Assertions

If you are seeing a error about "replay attacks" after upgrade, then you may need to disable a particular cache. More on this in a future article.