Apache WSS4J Migration Guides

Information about migrating to various new versions of WSS4J is provided in this section.

Apache WSS4J 2.2.0 Migration Guide

This section is a migration guide for helping Apache WSS4J 2.1.x users to migrate to the 2.2.x releases.

JDK8 minimum requirement

WSS4J 2.1.x required JDK7 as a minimum requirement. WSS4J 2.2.x requires at least JDK8.

Base64 changes

In WSS4J 2.1.x, the Base64 implementation that ships with the JDK (java.util.Base64) is used, instead of the Base64 implementation that ships with Apache Santuario. It is unlikely, but this may have an impact on users who are parsing messages with Base64 implementations that depend on specific CR or LF characters, as the Santuario and Java Base64 implementations differ slightly. Both the Apache Santuario and Java Base64 implementations can correctly decode the messages created with Apache WSS4J 2.2.x.

Kerberos changes

There are some changes with regards to Kerberos in WSS4J 2.1.x. The KerberosClientAction and KerberosServiceAction classes are removed. Instead use KerberosClientExceptionAction and KerberosServiceExceptionAction in the same package. The KerberosTokenDecoderImpl is removed as we can now get access to the secret key via the JDK APIs. As a consequence, the ws-security-common module no longer has a dependency on Apache Directory.

Apache WSS4J 2.1.0 Migration Guide

This section is a migration guide for helping Apache WSS4J 2.0.x users to migrate to the 2.1.x releases.

JDK7 minimum requirement

WSS4J 2.0.x required JDK6 as a minimum requirement. WSS4J 2.1.x requires at least JDK7. The Xerces and xml-api dependencies have been removed from the DOM code, as they are no longer required due to the JDK7 minimum requirement.

OpenSAML 3.x migration

A key dependency change in WSS4J 2.1.0 is the upgrade from OpenSAML 2.x to 3.x (currently 3.1.0). OpenSAML 3.x contains a large number of package changes. Therefore if you have any OpenSAML dependencies in a CallbackHandler used to create SAML Assertions in WSS4J, code changes will be required.

The most common OpenSAML dependency is to include a "SAMLVersion" to tell the SAMLCallback whether to create a SAML 2.0 or 1.1 Assertion. WSS4J 2.1 provides an alternative way of specifying the SAML Version, via a Version bean. See here for an example.

Custom processor changes

If you have a custom Processor instance to process a token in the security header in some custom way, you must add the WSSecurityEngineResult that is generated by the processing, to the WSDocInfo Object via the "addResult" method. Otherwise, it will not be available when security results are retrieved and processed.

Apache WSS4J 2.0.0 Migration Guide

This section is a migration guide for helping Apache WSS4J 1.6.x users to migrate to the 2.0.x releases. Also see the new features page for more information about the new functionality available in WSS4J 2.0.x.

Migrating to using the streaming (StAX) code

WSS4J 2.0.0 introduces a streaming (StAX-based) WS-Security implementation to complement the existing DOM-based implementation. The DOM-based implementation is quite performant and flexible, but having to read the entire request into memory carries performance penalties. The StAX-based code offers largely the same functionality as that available as part of the DOM code, and is configured in mostly the same way (via configuration tags that are shared between both stacks).

As of the time of writing, Apache CXF is the only web services stack to integrate the new WS-Security streaming functionality. To switch to use the streaming code for the manual "Action" based approach, simply change the outbound and inbound interceptors as follows:

  • "org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" to "org.apache.cxf.ws.security.wss4j.WSS4JStaxOutInterceptor".

  • "org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor" to "org.apache.cxf.ws.security.wss4j.WSS4JStaxInInterceptor".

For the WS-SecurityPolicy based approach of configuring WS-Security, simply set the JAX-WS property SecurityConstants.ENABLE_STREAMING_SECURITY ("ws-security.enable.streaming") to "true".

For more information on the streaming functionality available in WSS4J 2.0.0, please see the streaming documentation page.

Crypto/CallbackHandler changes

Typically, a user configures Signature and Encryption keys via a Crypto properties file. In WSS4J 1.6.x, the property names all start with "org.apache.ws.security.crypto.*". In WSS4J 2.0.0, the new prefix is "org.apache.wss4j.crypto.\*". However, WSS4J 2.0.0 will accept the older prefix value. No other changes are necessary for migrating Crypto properties.

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.

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.

SAML Assertion 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".

Apache WSS4J 1.6.x uses the SAMLIssuer interface to configure the creation and signing of a SAML Assertion. In Apache WSS4J 2.0.0, the SAMLIssuer functionality has been moved to the SAMLCallback, so that the CallbackHandler used to create a SAML Assertion is responsible for all of the signing configuration as well. Therefore, the properties file that is used in WSS4J 1.6.x to sign a SAML Assertion is no longer used in WSS4J 2.0.0, and the "samlPropFile" and "samlPropRefId" configuration tags have been removed.

The SAMLCallback Object contains the additional properties in WSS4J 2.0.0 that can be set to sign the Assertion:

  • boolean signAssertion - Whether to sign the assertion or not (default "false").

  • String issuerKeyName - The keystore alias for signature

  • String issuerKeyPassword - The keystore password for the alias

  • Crypto issuerCrypto - The Crypto instance used for signature

  • boolean sendKeyValue - Whether to send the keyvalue or the X509Certificate (default "false").

  • String canonicalizationAlgorithm - The C14n algorithm to use for signature.

  • String signatureAlgorithm - The Signature algorithm.

Configuration tag changes

In WSS4J 1.6.x, configuration tags were configured in the WSHandlerConstants class. In WSS4J 2.0.0, both the DOM and StAX-based code largely share the same configuration options, and so the configuration tags are defined in ConfigurationConstants. Note that the WSS4J 1.6.x configuration class (WSHandlerConstants) extends this class in WSS4J 2.0.0, so there is no need to change any configuration code when upgrading.

The configuration tags that have been removed and added are detailed below. The non-standard key derivation and UsernameToken Signature functionality that was optional in WSS4J 1.6.x has been removed. Some new actions are added for the streaming code, as well as some options surrounding caching. An important migration point is that there is now a separate configuration tag used for verifying signatures. In WSS4J 1.6.x, there was only one tag used for both signature creation and verification.

Removed Configuration tags in WSS4J 2.0.0

This section details the Configuration tags that are no longer present in WSS4J 2.0.0.

  • SIGN_WITH_UT_KEY (UsernameTokenSignature) - Perform a .NET specific signature using a Username Token action. Removed as it was not standard compliant.

  • PASSWORD_TYPE_STRICT (passwordTypeStrict) - Whether to enable strict Username Token password type handling. In WSS4J 2.0.0 this functionality can be enabled by just setting the required PASSWORD_TYPE.

  • USE_DERIVED_KEY (useDerivedKey) - Whether to use the standard UsernameToken Key Derivation algorithm. Removed as only the standard algorithm is used in WSS4J 2.0.0.

  • ENC_KEY_NAME (embeddedKeyName) - The text of the key name to be sent in the KeyInfo for encryption. Embedded KeyNames are not supported in WSS4J 2.0.0.

  • ADD_UT_ELEMENTS (addUTElements) - Additional elements to add to a Username Token, i.e. "nonce" and "created". See the ADD_USERNAMETOKEN_NONCE and ADD_USERNAMETOKEN_CREATED properties below.

  • WSE_SECRET_KEY_LENGTH (wseSecretKeyLength) - The length of the secret (derived) key to use for the WSE UT_SIGN functionality. Removed as it is not standard compliant.

  • ENC_CALLBACK_CLASS (embeddedKeyCallbackClass) - The CallbackHandler implementation class used to get the key associated with a key name. KeyName is not supported in WSS4J 2.0.0.

  • ENC_CALLBACK_REF (embeddedKeyCallbackRef) -The CallbackHandler implementation object used to get the key associated with a key name. KeyName is not supported in WSS4J 2.0.0.

New Configuration tags in WSS4J 2.0.0

This section details the new Configuration tags in WSS4J 2.0.0.

  • USERNAME_TOKEN_SIGNATURE (UsernameTokenSignature) - Perform a UsernameTokenSignature action.

  • SIGNATURE_DERIVED (SignatureDerived) - Perform a Signature action with derived keys.

  • ENCRYPT_DERIVED (EncryptDerived) - Perform a Encryption action with derived keys.

  • SIGNATURE_WITH_KERBEROS_TOKEN (SignatureWithKerberosToken) - Perform a Signature action with a kerberos token. Only for StAX code.

  • ENCRYPT_WITH_KERBEROS_TOKEN (EncryptWithKerberosToken) - Perform a Encryption action with a kerberos token. Only for StAX code.

  • KERBEROS_TOKEN (KerberosToken) - Add a kerberos token.

  • CUSTOM_TOKEN (CustomToken) - Add a "Custom" token from a CallbackHandler

  • SIG_VER_PROP_FILE (signatureVerificationPropFile) - The path of the crypto property file to use for Signature verification.

  • SIG_VER_PROP_REF_ID (signatureVerificationPropRefId) - The String ID that is used to store a reference to the Crypto object or the Crypto Properties object for Signature verification.

  • ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM (allowRSA15KeyTransportAlgorithm) - Whether to allow the RSA v1.5 Key Transport Algorithm or not. Default is "false".

  • ADD_INCLUSIVE_PREFIXES (addInclusivePrefixes) - Whether to add an InclusiveNamespaces PrefixList as a CanonicalizationMethod child when generating Signatures using WSConstants.C14N_EXCL_OMIT_COMMENTS. Default is "true".

  • ADD_USERNAMETOKEN_NONCE (addUsernameTokenNonce) - Whether to add a Nonce Element to a UsernameToken (for plaintext). Default is "false"

  • ADD_USERNAMETOKEN_CREATED (addUsernameTokenCreated) - Whether to add a Created Element to a UsernameToken (for plaintext). Default is "false"

  • ALLOW_USERNAMETOKEN_NOPASSWORD (allowUsernameTokenNoPassword) - Whether a UsernameToken with no password element is allowed. Default is "false".

  • VALIDATE_SAML_SUBJECT_CONFIRMATION (validateSamlSubjectConfirmation) - Whether to validate the SubjectConfirmation requirements of a received SAML Token (sender-vouches or holder-of-key). Default is "true".

  • INCLUDE_SIGNATURE_TOKEN (includeSignatureToken) - Whether to include the Signature Token in the security header as well or not (for IssuerSerial + Thumbprint cases). Default is "false"

  • INCLUDE_ENCRYPTION_TOKEN (includeEncryptionToken) - Whether to include the Encryption Token in the security header as well or not (for IssuerSerial, Thumbprint, SKI cases). Default is "false"

  • ENABLE_NONCE_CACHE (enableNonceCache) - Whether to cache UsernameToken nonces. Default is "true"

  • ENABLE_TIMESTAMP_CACHE (enableTimestampCache) - Whether to cache Timestamp Created Strings (these are only cached in conjunction with a message Signature). Default is "true"

  • ENABLE_SAML_ONE_TIME_USE_CACHE (enableSamlOneTimeUseCache) - Whether to cache SAML2 Token Identifiers, if the token contains a "OneTimeUse" Condition. Default is "true".

  • USE_2005_12_NAMESPACE (use200512Namespace) - Whether to use the 2005/12 namespace for SecureConveration + DerivedKeys, or the older namespace. The default is "true"

  • OPTIONAL_SIGNATURE_PARTS (optionalSignatureParts) - Parameter to define which parts of the request shall be signed, if they exist in the request.

  • OPTIONAL_ENCRYPTION_PARTS (optionalEncryptionParts) - Parameter to define which parts of the request shall be encrypted, if they exist in the request.

  • ENC_MGF_ALGO (encryptionMGFAlgorithm) - Defines which encryption mgf algorithm to use with the RSA OAEP Key Transport algorithm for encryption. The default is mgfsha1.

  • VALIDATOR_MAP (validatorMap) - A map of QName, Object (Validator) instances to be used to validate tokens identified by their QName.

  • NONCE_CACHE_INSTANCE (nonceCacheInstance) - A ReplayCache instance used to cache UsernameToken nonces. The default instance that is used is the EHCacheReplayCache.

  • TIMESTAMP_CACHE_INSTANCE (timestampCacheInstance) - A ReplayCache instance used to cache Timestamp Created Strings. The default instance that is used is the EHCacheReplayCache.

  • SAML_ONE_TIME_USE_CACHE_INSTANCE (samlOneTimeUseCacheInstance) - A ReplayCache instance used to cache SAML2 Token Identifier Strings (if the token contains a OneTimeUse Condition). The default instance that is used is the EHCacheReplayCache.

  • PASSWORD_ENCRYPTOR_INSTANCE (passwordEncryptorInstance) - A PasswordEncryptor instance used to decrypt encrypted passwords in Crypto properties files. The default is the JasyptPasswordEncryptor.

  • DERIVED_TOKEN_REFERENCE (derivedTokenReference) - This controls how deriving tokens are referenced.

  • DERIVED_TOKEN_KEY_ID (derivedTokenKeyIdentifier) - This controls the key identifier of Derived Tokens.

  • DERIVED_SIGNATURE_KEY_LENGTH (derivedSignatureKeyLength) - The length to use (in bytes) when deriving a key for Signature.

  • DERIVED_ENCRYPTION_KEY_LENGTH (derivedEncryptionKeyLength) - The length to use (in bytes) when deriving a key for Encryption.

Derived Key and Secure Conversation namespace change

In WSS4J 1.6.x, the default namespace used for Derived Key and Secure Conversation was the older "http://schemas.xmlsoap.org/ws/2005/02/sc" namespace. In WSS4J 2.0.0, the default namespace is now "http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512". To switch back to use the older namespace, you can set the new configuration property "USE_2005_12_NAMESPACE" to "false".

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.

RSA v1.5 Key Transport algorithm not allowed by default

WSS4J supports two key transport algorithms, RSA v1.5 and RSA-OAEP. A number of attacks exist on RSA v1.5. Therefore, you should always use RSA-OAEP as the key transport algorithm. In WSS4J 2.0.0, the RSA v1.5 Key Transport algorithm is not allowed by default (as opposed to previous versions of WSS4J, where it is allowed). If you wish to allow it, then you must set the WSHandlerConstants.ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM property to "true".

InclusiveNamespaces PrefixList change

In WSS4J 1.6.x, when BSP Compliance was switched off on the outbound side, it had the effect that an InclusiveNamespaces PrefixList was not generated as a CanonicalizationMethod child of a Signature Element (as required by the BSP specification). In WSS4J 2.0.0, this is now controlled by a separate configuration tag "addInclusivePrefixes", which defaults to true.

New features available in Apache WSS4J 2.0.0

Overview of new features

Apache WSS4J 2.0.0 delivers the following major new features:

  • Support for a streaming (StAX) based WS-Security implementation that covers all of the main specifications.

  • 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.

Streaming (StAX) based WS-Security implementation

WSS4J 2.0.0 introduces a new streaming (StAX) based WS-Security implementation. Please see the dedicated page for more information.

WS-SecurityPolicy support

WSS4J 2.0.0 introduces a new WS-SecurityPolicy model as part of the "wss4j-policy" module. This model can be shared between both the DOM and StAX WS-Security implementations. Web service stacks such as Apache CXF and Apache Axis/Rampart that use WSS4J for WS-Security no longer need to maintain their own model. In this way any bug fixes to the model will get picked up by all web service stacks that rely on WSS4J.

In addition to the new WS-SecurityPolicy model, a significant new feature of WSS4J 2.0.0 is that the new streaming WS-Security implementation has the ability to perform "real-time" validation of a request against the set of applicable WS-SecurityPolicy policies. The DOM-based code in WSS4J does not have any concept of WS-SecurityPolicy, but instead processes an inbound request, and relies on the web service stack to compare the results against the applicable policies. The advantage of the streaming approach in WSS4J 2.0.0 is that bogus requests can be rejected quicker, which may help to avoid DoS based scenarios.

Support for signing and encrypting message attachments

WSS4J 2.0.0 introduces support for signing and encrypting SOAP message attachments, via the the SOAP with Attachments (SWA) Profile 1.1 specification. Please see the dedicated page for more information.

Replay Attack detection using EhCache

In WSS4J 1.6.x, a "ReplayCache" interface was introduced to cache tokens to guard against replay attacks for the following scenarios:

  • Signed Timestamps

  • UsernameToken nonces

  • SAML OneTimeUse Assertions

However, replay attack detection was not "switched on" by default in WSS4J 1.6.x. In WSS4J 2.0.x, replay attack detection is enabled by default using an implementation of the "ReplayCache" interface based on EhCache. The following configuration tags can be used to configure caching:

  • ConfigurationConstants.TIMESTAMP_CACHE_INSTANCE ("timestampCacheInstance"): This holds a reference to a ReplayCache instance used to cache Timestamp Created Strings. The default instance that is used is the EHCacheReplayCache.

  • ConfigurationConstants.ENABLE_TIMESTAMP_CACHE ("enableTimestampCache"): Whether to cache Timestamp Created Strings (these are only cached in conjunction with a message Signature). The default value is "true".

  • ConfigurationConstants.NONCE_CACHE_INSTANCE ("nonceCacheInstance"): This holds a reference to a ReplayCache instance used to cache UsernameToken nonces. The default instance that is used is the EHCacheReplayCache.

  • ConfigurationConstants.ENABLE_NONCE_CACHE ("enableNonceCache"): Whether to cache UsernameToken nonces. The default value is "true".

  • ConfigurationConstants. SAML_ONE_TIME_USE_CACHE_INSTANCE ("samlOneTimeUseCacheInstance"): This holds a reference to a ReplayCache instance used to cache SAML2 Token Identifier Strings (if the token contains a OneTimeUse Condition). The default instance that is used is the EHCacheReplayCache.

  • ConfigurationConstants.ENABLE_SAML_ONE_TIME_USE_CACHE ("enableSamlOneTimeUseCache"): Whether to cache SAML2 Token Identifiers, if the token contains a "OneTimeUse" Condition. The default value is "true".

Encrypting passwords in Crypto property files

A typical example of the contents of a Crypto properties file (for Signature creation) is as follows:

  • org.apache.wss4j.crypto.provider=org.apache.wss4j.common.crypto.Merlin

  • org.apache.wss4j.crypto.merlin.keystore.type=jks

  • org.apache.wss4j.crypto.merlin.keystore.password=security

  • org.apache.wss4j.crypto.merlin.keystore.alias=wss40

  • org.apache.wss4j.crypto.merlin.keystore.file=keys/wss40.jks

Note that the password used to load the keystore is in cleartext. One of the new features of Apache WSS4J 2.0.0 is the ability to instead store a (BASE-64 encoded) encrypted version of the keystore password in the Crypto properties file. A new PasswordEncryptor interface is defined to allow for the encryption/decryption of passwords. A default implementation is now provided based on Jasypt called JasyptPasswordEncryptor, which uses "PBEWithMD5AndTripleDES".

The WSPasswordCallback class has an additional "usage" called WSPasswordCallback.PASSWORD_ENCRYPTOR_PASSWORD, which is used to return the master password for use with the PasswordEncryptor implementation. When WSS4J is loading a Crypto implementation via a properties file, and it encounters a password encrypted in the format "ENC(encoded encrypted password)", it queries a CallbackHandler for a password via this WSPasswordCallback usage tag. It is possible to pass a custom PasswordEncryptor implementation to WSS4J via the new configuration tag ConfigurationConstants.PASSWORD_ENCRYPTOR_INSTANCE ("passwordEncryptorInstance").

Miscellaneous new features

Support was added in WSS4J 1.6.x to obtain a Kerberos ticket from a KDC (Key Distribution Center) and include it in the security header of a request, as well as to process the received token. However, there was no built-in way to extract the secret key from the ticket to secure the request. Instead it was up to the user to plug in a custom "KerberosTokenDecoder" implementation to support this behaviour. In WSS4J 2.0.0, a default KerberosTokenDecoder implementation is provided, and so WSS4J now supports signing/encrypting using Kerberos tokens by default.

A new "CustomToken" Action is defined in WSS4J 2.0.0. If this action is defined, a token (DOM Element) will be retrieved from a CallbackHandler via WSPasswordCallback.Usage.CUSTOM_TOKEN and written out as is in the security header. This provides for an easy way to write out tokens that have been retrieved out of band. Another related new feature is the ability to associate an action with a particular set of keys/algorithms. This means that it is now possible to configure two different Signature actions, that use different keys/algorithms.

Support for enforcing the Basic Security Profile (BSP) 1.1 specification was added in WSS4J 1.6.x. In WSS4J 2.0.0, it is possible to disable individual BSP Rules for a non-compliant request, instead of having to disable BSP enforcement altogether as for WSS4J 1.6.x. The RequestData class has a setIgnoredBSPRules method, that takes a list of BSPRule Objects as an argument. The BSPRule class contains a complete list of Basic Security Profile rules that are enforced in WSS4J.

WSS4J 2.0.0 now enforces the SubjectConfirmation requirements of an inbound SAML Token, instead of leaving it to the web services stack. For sender-vouches, a Signature must be present that covers both the SOAP Body and the SAML Assertion. For holder-of-key, a Signature must be present that signs some part of the SOAP request using the key information contained in the SAML Subject. Note that a Signature can be either a message or transport level Signature (i.e. using TLS is acceptable). A new configuration tag is defined that allows the user to switch off this validation if required (ConfigurationConstants.VALIDATE_SAML_SUBJECT_CONFIRMATION - "validateSamlSubjectConfirmation").

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.