Apache WSS4J 1.6.0 Migration Guide

This page describes the new features of WSS4J 1.6.0, and the things to be aware of when upgrading from WSS4J 1.5.x. Note that WSS4J 1.6.x has now been replaced by WSS4J 2.0.x, please see the WSS4J 2.0.0 migration guide for more information.

New features

This section describes the main new features that have been implemented in WSS4J 1.6. For more information on the changes, please click on the links. You can also review the list of JIRAs that have been fixed in WSS4J 1.6.

  • JSR-105 support: WSS4J 1.6 has been ported to use the JSR 105 API for XML Digital Signature.

  • SAML2 support: WSS4J 1.6 includes full support for creating, manipulating and parsing SAML2 assertions, via the Opensaml2 library.

  • Performance work: A general code-rewrite has been done with a focus on improving performance, e.g. the changes that have been made to processor loading.

  • Basic Security Profile 1.1 compliance: WSS4J 1.6 provides support for the BSP 1.1 specification.

  • JDK 1.5 port: The JDK 1.4 requirement of WSS4J 1.5.x has been dropped as part of this work.

  • Support for Crypto trust-stores: WSS4J 1.6 separates the concept of keystore and truststores for Crypto implementations.

  • New Validator interface: WSS4J 1.6 moves all validation of security tokens into a new Validator interface, which allows for custom validation of specific tokens.

  • Support for the Kerberos Token Profile (in WSS4J 1.6.2 and 1.6.3).

Upgrade notes

This section describes the changes that have been made in WSS4J 1.6 that will impact on an existing user of WSS4J 1.5.x. Although WSS4J 1.6 is not 100% backwards compatible with 1.5.x, a general goal for the release was to restrict the API changes to those that were strictly necessary.

  • All Axis1 dependencies have been removed. Any user wishing to use WSS4J with Axis1 must use the WSS4J 1.5.x library. As Axis1 has been replaced by Axis2, this is unlikely to be an issue.

  • A number of changes have been made to the Crypto interface. See here, here and here for an indepth explanation. In a nutshell, these changes are:

    1. The BouncyCastle crypto implementation has been removed (replaced by Merlin)

    2. A new set of Merlin "truststore" configuration tags have been added. The behaviour of the old Merlin configuration tags will work exactly the same way in WSS4J 1.6.

    3. The CA certs are now <b>not</b> loaded by default.

    4. PublicKeys (from KeyValues) are now not handled by a PublicKeyCallback, but by the Crypto implementation directly.

  • If the WSEncryptionPart used to point to an element for signature or encryption does not either store the element directly, or store the wsu:Id, all DOM Elements that match the stored localname/namespace will be processed. See the Special Topics page for more information.

  • WSS4J 1.5.x used Opensaml1 to provide extremely limited support for SAML 1 assertions. WSS4J 1.6 has been upgraded to Opensaml2, and provides far more comprehensive support for SAML. See here for more information on this. Some changes to be aware of are:

    1. The way of creating SAML assertions via a properties file has completely changed. For example, see SAML Token Test.

    2. WSS4J 1.5.x ignored (enveloped) signatures on SAML (1.1) assertions - this is no longer the case, so deployments which do not set the correct keystore/truststore config for dealing with signature verification will fail.

    3. The SAMLTokenProcessor no longer saves all tokens as an "WSConstants.ST_UNSIGNED" action. It saves tokens that do not have an enveloped signature as this action, and token which do have an enveloped signature are saved as a "WSConstants.ST_SIGNED" action.

    4. The object that is saved as part of the action above has changed, from an Opensaml1 specific Assertion object, to an AssertionWrapper instance, which is a WSS4J specific object which encapsulates an Assertion, as well as some information corresponding to signature verification, etc.

  • The way that UsernameTokens are processed has been changed. See here for more information. Some important changes are:

    1. The plaintext password case has exactly the same behaviour as the digest case. The identifier is now WSPasswordCallback.USERNAME_TOKEN and not WSPasswordCallback.USERNAME_TOKEN_UNKNOWN, and the CallbackHandler does not do any authentication, but must set the password on the callback.

    2. The custom password type case defaults to the same behaviour as the plaintext case, assuming wssConfig.getHandleCustomPasswordTypes() returns true.

    3. For the case of a username token with no password element, the default behaviour is simply to ignore it, and to store it as a new result of type WSConstants.UT_NOPASSWORD.

  • Some changes have been made to the WSPasswordCallback identifiers, used to obtain passwords for various actions. For more information see here. In a nutshell, these changes consist of:

    1. The WSPasswordCallback KEY_NAME, USERNAME_TOKEN_UNKNOWN and WSPasswordCallback.ENCRYPTED_KEY_TOKEN identifiers have been removed.

    2. CUSTOM_TOKEN is not longer used in the processors to get a secret key.

    3. SECRET_KEY is a new identifier for finding secret keys. It replaces the occasionally incorrect use of CUSTOM_TOKEN, as well as KEY_NAME and ENCRYPTED_KEY_TOKEN.

  • Timestamp validation and signature trust verification is not done by the WSHandler implementation any more, but is performed when the security header is processed.