(ws-wss4j) 01/01: Add security documentation for StAX

[co...@apache.org]

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 <co...@apache.org>
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
      */