(ws-wss4j) branch master updated: Adding docs about trust credentials for BST (#706)

[co...@apache.org]

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 d2939c88e Adding docs about trust credentials for BST (#706)
d2939c88e is described below

commit d2939c88ed22436f2e11d82a89e4b696a173fc4e
Author: Colm O hEigeartaigh <co...@users.noreply.github.com>
AuthorDate: Fri Sep 18 10:52:59 2026 +0100

    Adding docs about trust credentials for BST (#706)
---
 THREAT-MODEL.md                                         | 17 +++++++++++++++++
 .../java/org/apache/wss4j/dom/engine/WSSConfig.java     |  9 +++++++++
 2 files changed, 26 insertions(+)

diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md
index 957498a9d..7efb50d5e 100644
--- a/THREAT-MODEL.md
+++ b/THREAT-MODEL.md
@@ -711,6 +711,23 @@ The embedding SOAP stack / application **must**:
 - **Mixing the action-based and WS-SecurityPolicy approaches in the
   same handler chain.** The behavior across both is documented but
   rarely tested.
+- **Registering a `Validator` for `WSConstants.BINARY_TOKEN` in order to
+  inspect or transform a BinarySecurityToken.** Registering *any*
+  Validator for that QName marks the token as validated, and
+  `SignatureSTRParser` then treats a Signature referencing that token as
+  a trusted credential, so the Signature Validator
+  (`SignatureTrustValidator` by default) never runs for it — a
+  certificate the truststore does not trust is accepted. This is
+  long-standing intentional behaviour, and is how Kerberos and other
+  opaque BinarySecurityTokens obtain their direct trust
+  *(`ValidatorTest.testValidatedBSTSignature` pins it)*. The trap is that
+  a Validator registered for an unrelated purpose — or a
+  `NoOpValidator` — disables signature trust verification just as
+  effectively, with nothing to signal it. Register a Validator for this
+  QName only if it verifies the token itself, or accept that signatures
+  referencing that token are not trust-checked. No BinarySecurityToken
+  Validator is registered by default, so the default configuration is
+  unaffected *(documented: `WSSConfig.setValidator` javadoc)*.
 - **Reading a `SIGN` result as proof of sender identity without looking
   at what keyed it.** With the action-based approach, `action="Signature
   Encrypt"` is satisfied by a signature keyed from an inbound
diff --git a/ws-security-dom/src/main/java/org/apache/wss4j/dom/engine/WSSConfig.java b/ws-security-dom/src/main/java/org/apache/wss4j/dom/engine/WSSConfig.java
index 9257ae739..733c99eff 100644
--- a/ws-security-dom/src/main/java/org/apache/wss4j/dom/engine/WSSConfig.java
+++ b/ws-security-dom/src/main/java/org/apache/wss4j/dom/engine/WSSConfig.java
@@ -476,6 +476,15 @@ public final class WSSConfig {
      *
      * Please note that the Validator object does NOT get class-loaded per invocation, and so
      * it is up to the implementing class to ensure that it is thread-safe.
+     *
+     * Note for WSConstants.BINARY_TOKEN: registering any Validator for this QName - including
+     * one registered only to inspect or transform the token, or a NoOpValidator - marks the
+     * token as validated, and a Signature referencing that token is then treated as a trusted
+     * credential, so the Signature Validator (SignatureTrustValidator by default) does not
+     * run for it. This is how Kerberos and other opaque BinarySecurityTokens obtain direct
+     * trust, but it applies equally to a Validator that verifies nothing. Register a Validator
+     * here only if it verifies the token itself, or accept that signatures referencing that
+     * token are not trust-checked.
      */
     public Class<?> setValidator(QName el, Validator validator) {
         Object result = validatorMap.put(el, validator);