This is an automated email from the ASF dual-hosted git repository. coheigea pushed a commit to branch coheigea/stax-doc in repository https://gitbox.apache.org/repos/asf/ws-wss4j.git
commit e0f26cb3bdea517fa9590185e73fcd74829e1c1f Author: Colm O hEigeartaigh <[email protected]> AuthorDate: Wed Sep 9 06:57:08 2026 +0100 Add security documentation for StAX --- .../java/org/apache/wss4j/stax/setup/InboundWSSec.java | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/ws-security-stax/src/main/java/org/apache/wss4j/stax/setup/InboundWSSec.java b/ws-security-stax/src/main/java/org/apache/wss4j/stax/setup/InboundWSSec.java index bdb86ebaf..5adbbbcf3 100644 --- a/ws-security-stax/src/main/java/org/apache/wss4j/stax/setup/InboundWSSec.java +++ b/ws-security-stax/src/main/java/org/apache/wss4j/stax/setup/InboundWSSec.java @@ -54,6 +54,18 @@ import org.apache.xml.security.stax.securityToken.SecurityTokenProvider; /** * Inbound Streaming-WebService-Security * An instance of this class can be retrieved over the WSSec class + * + * <p><b>Security note - streaming hands out content before verification completes:</b> + * the XMLStreamReader returned by {@code processInMessage} delivers decrypted content and + * the events of signed elements to the application as they are read from the wire. The + * digest of a signed part is only compared when the corresponding END element is + * reached, and message-level verdicts (for example the WS-SecurityPolicy decision at the + * operation event) also complete only as the stream is consumed. This is inherent to + * streaming XML security. Applications MUST therefore treat all message content as + * unverified until the returned stream has been consumed to completion without a + * security exception: buffer-then-dispatch (as, for example, Apache CXF does), and never + * commit side effects (database writes, outbound calls, acknowledgements) incrementally + * while the stream is still being read.</p> */ public class InboundWSSec { @@ -173,7 +185,10 @@ public class InboundWSSec { * * @param xmlStreamReader The original XMLStreamReader * @param securityEventListeners A list of SecurityEventListeners to receive security-relevant events. - * @return A new XMLStreamReader which does transparently the security processing. + * @return A new XMLStreamReader which does transparently the security processing. Note + * that content read from it is only fully verified once the stream has been + * consumed to completion without a security exception - do not commit side + * effects based on partially-read content (see the class-level security note). * @throws XMLStreamException thrown when a streaming error occurs * @throws WSSecurityException */
