This is an automated email from the ASF dual-hosted git repository.
coheigea pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ws-wss4j.git
The following commit(s) were added to refs/heads/master by this push:
new c9cdddace Document streaming policy enforcement (#714)
c9cdddace is described below
commit c9cdddaceeef9a4f8eb3ba9651823170baf4ac66
Author: Colm O hEigeartaigh <[email protected]>
AuthorDate: Mon Sep 21 07:33:11 2026 +0100
Document streaming policy enforcement (#714)
---
THREAT-MODEL.md | 24 ++++++++++++++++++++++++
src/site/asciidoc/streaming.adoc | 13 +++++++++++++
2 files changed, 37 insertions(+)
diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md
index 3229a454a..ba981e41a 100644
--- a/THREAT-MODEL.md
+++ b/THREAT-MODEL.md
@@ -213,6 +213,30 @@ is in-model only if it maps to one of them.
`SIGNATURE_PARTS` / `ENCRYPTION_PARTS` /
`REQUIRE_SIGNED_ENCRYPTED_DATA_ELEMENTS`
*(documented: `src/site/asciidoc/best_practice.adoc`,
`src/site/asciidoc/config.adoc`)*.
+- **A policy is not a guarantee that every assertion in it is enforced.**
+ An assertion the `PolicyEnforcer` does not recognise is skipped, so a
+ server can enforce strictly less than the policy it advertises while
+ reporting success. The exposure is bounded but not closed:
+ - a *top-level* unrecognised assertion is logged at WARN naming the
+ assertion, and the system property
+ `org.apache.wss4j.policy.failOnUnsupportedAssertions=true` turns it
+ into a build-time rejection. The default is to warn and continue, so
+ that a policy carrying a vendor assertion keeps working;
+ - a *nested* assertion - inside a binding, a token, an AlgorithmSuite -
+ is dropped with no diagnostic at all, a misspelled name among them,
+ and none is available: a parent offers the same nested policy to every
+ parser in its inheritance chain (`AsymmetricBinding` then
+ `AbstractSymmetricAsymmetricBinding` then `AbstractBinding`), each
+ assertion matches exactly one of them, so "did not match here" carries
+ no information. Reporting it would mean tracking which parser in the
+ chain consumed each assertion;
+ - within a nested policy only the first alternative of a compact policy
+ is read.
+
+ An operator who depends on a specific assertion being enforced should
+ confirm it against the enforcer rather than assume the advertised policy
+ is the enforced one *(documented:
+ `src/site/asciidoc/streaming.adoc`)*.
- **`ws-security-web`**: in-model insofar as the servlet entry point
reaches WSS4J; the surrounding servlet container is out.
- **JAXB bindings**: pure DTO objects, in-model only insofar as the
diff --git a/src/site/asciidoc/streaming.adoc b/src/site/asciidoc/streaming.adoc
index 3c4112cfc..1c73eb94c 100644
--- a/src/site/asciidoc/streaming.adoc
+++ b/src/site/asciidoc/streaming.adoc
@@ -74,4 +74,17 @@ 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.
+ * A policy assertion that the PolicyEnforcer does not recognise is not
+enforced. A top-level assertion in that position is logged at WARN naming the
+assertion, and setting the system property
+"org.apache.wss4j.policy.failOnUnsupportedAssertions" to "true" rejects the
+policy outright instead of under-enforcing it. An assertion nested inside
+another - inside a binding, a token or an AlgorithmSuite - is dropped without
+any diagnostic at all, a misspelled name among them. No diagnostic is available
+for that case: an assertion is offered to every parser in its parent's
+inheritance chain and matches exactly one of them, so failing to match says
+nothing on its own. Check the effective policy if you rely on a nested
+assertion being enforced.
+ * Where a compact policy offers several alternatives within a nested policy,
+only the first is read.
