This is an automated email from the ASF dual-hosted git repository.
coheigea pushed a commit to branch 2_4_x-fixes
in repository https://gitbox.apache.org/repos/asf/ws-wss4j.git
The following commit(s) were added to refs/heads/2_4_x-fixes by this push:
new a884b65c4 Add security documentation for StAX (#679)
a884b65c4 is described below
commit a884b65c43623995ce0c834c07b98d072efc7f6b
Author: Colm O hEigeartaigh <[email protected]>
AuthorDate: Wed Sep 9 07:21:28 2026 +0100
Add security documentation for StAX (#679)
---
.../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
*/
