Streaming (StAX) WS-Security support in Apache WSS4J 2.0.0

Overview of new features

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 suffers from having to read the entire XML tree into memory. For large SOAP requests this can have a detrimental impact on performance. In addition, for web services stacks such as Apache CXF which are streaming-based, it carries an additional performance penalty of having to explicitly convert the request stream to a DOM Element.

The new StAX-based WS-Security implementation does not read the request into memory, and hence uses far less memory for large requests. It is also more performant in certain circumstances. 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). It does not offer the low-level API available in the DOM code to individually construct various WS-Security tokens, but instead must be used by specifying various actions to perform.

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

Limitations of the streaming WS-Security implementation

The new streaming implementation in WSS4J 2.0.0 meets the vast majority of the most common use-cases. However, it does not support everything that the DOM implementation supports. The limitations are:

  • XPath evaluation is not supported apart from certain simple expressions. XPath evaluations are used with WS-SecurityPolicy RequiredElements, SignedElements, (Content)EncryptedElements. XPath expressions that point directly to the element are supported, e.g. /soap:Envelope/soap:Header/wsa:To. See WSS-445.
  • WS-SecurityPolicy "Strict" Layout validation is not enforced. This includes enforcing whether a Timestamp is first or last. See WSS-444.
  • A SymmetricBinding policy with a ProtectTokens assertion is not supported. See WSS-456.
  • The combination of EncryptBeforeSigning + EncryptSignature policies are not supported. See WSS-464.
  • Deriving keys from Username Tokens (Endorsing Username Tokens) are not supported.
  • Endorsing tokens don't work with Symmetric + Asymmetric binding on the client side, unless the endorsing token is a SAML or IssuedToken.
  • Derived Endorsing Tokens are not supported on the client side.