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.