This is an automated email from the ASF dual-hosted git repository. coheigea pushed a commit to branch coheigea/streaming-enforcement in repository https://gitbox.apache.org/repos/asf/ws-wss4j.git
commit 57473f7ca165932f609745dccf6e998103e052c2 Author: Colm O hEigeartaigh <[email protected]> AuthorDate: Mon Sep 21 07:23:22 2026 +0100 Document streaming policy enforcement --- 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 7efb50d5e..c9a2c1292 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.
