(ws-wss4j) branch master updated: More docs updates

[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 79cc522f0 More docs updates
79cc522f0 is described below

commit 79cc522f0dd23e720b0b85d2396245c3ba908ddd
Author: Colm O hEigeartaigh <co...@apache.org>
AuthorDate: Mon Sep 21 10:42:31 2026 +0100

    More docs updates
---
 THREAT-MODEL.md                      | 21 +++++++++++++++++++++
 src/site/asciidoc/best_practice.adoc | 28 ++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md
index 32fdd3c91..d49e08e08 100644
--- a/THREAT-MODEL.md
+++ b/THREAT-MODEL.md
@@ -636,6 +636,27 @@ matching disclaimer.
   enforce security requirements")*. The action-based API requires the
   caller to specify which parts must be signed; failing to specify them
   produces a working but insecure deployment.
+- **No binding between a content encryption key and the algorithm it is
+  used with.** An `EncryptedData` states its own algorithm, and XML
+  Encryption gives the recipient nothing that ties the key delivered in
+  the `EncryptedKey` to it, so whoever sends — or alters — the message
+  chooses the algorithm the recipient decrypts under. The key length
+  check in `KeyUtils.prepareSecretKey` refuses a key of the wrong length
+  for the declared algorithm, which rules out a relabel across key
+  sizes, but not one within a size: `aes256-gcm` relabelled as
+  `aes256-cbc` presents a 32-byte key either way, and turns an
+  authenticated mode into one whose padding is a known oracle. WSS4J
+  enforces the algorithm it has been told to expect — an AlgorithmSuite
+  from WS-SecurityPolicy, `ENC_SYM_ALGO` where the stack sets an
+  AlgorithmSuite on the `RequestData`, or
+  `setEncryptionSymAlgorithm` on the streaming engine — and accepts what
+  it is sent where it has been told nothing, since it has no basis for
+  preferring one algorithm over another and the library's own outbound
+  default is CBC. Signing the `EncryptedData` covers the Algorithm
+  attribute and is the alternative where the expected algorithm is not
+  known in advance *(documented:
+  `src/site/asciidoc/best_practice.adoc` §"Specify the symmetric
+  encryption algorithm on the receiving side")*.
 - **No `REQUIRE_SIGNED_ENCRYPTED_DATA_ELEMENTS` enforcement in the
   streaming engine.** The tag is defined in the shared
   `ConfigurationConstants` and read only by the DOM processors
diff --git a/src/site/asciidoc/best_practice.adoc b/src/site/asciidoc/best_practice.adoc
index f79228b78..24345e3ea 100644
--- a/src/site/asciidoc/best_practice.adoc
+++ b/src/site/asciidoc/best_practice.adoc
@@ -71,6 +71,34 @@ WSS4J has support for "gcm" mode algorithms as well. This can be specified via
 WSHandlerConstants.ENC_SYM_ALGO ("encryptionSymAlgorithm"), for example to 
 "http://www.w3.org/2009/xmlenc11#aes128-gcm".
 
+=== Specify the symmetric encryption algorithm on the receiving side
+
+Choosing "gcm" for what you send is only half of it. An EncryptedData element states
+its own algorithm, and nothing in the message binds the content encryption key to the
+algorithm it was meant for, so the sender of a message - or anyone who can modify one
+in flight - decides which algorithm the recipient uses to decrypt it. Relabelling an
+aes256-gcm EncryptedData as aes256-cbc leaves a key of exactly the length either
+algorithm requires, so the key length check does not notice, and the recipient
+decrypts in an unauthenticated mode whose padding is a known oracle.
+
+Tell the receiving side what to expect, and it will reject anything else:
+
+ * WS-SecurityPolicy states it in the AlgorithmSuite, which is the reason to prefer
+that approach.
+ * For the streaming code, WSSSecurityProperties.setEncryptionSymAlgorithm.
+ * For the DOM code, WSHandlerConstants.ENC_SYM_ALGO ("encryptionSymAlgorithm") - the
+same property that chooses the outbound algorithm. As with the signature and key
+transport algorithms below, it only takes effect on the receiving side where the web
+services stack sets an AlgorithmSuite on the RequestData: Apache CXF's
+WSS4JInInterceptor does, a stack calling the engine directly does not.
+
+Where the expected algorithm genuinely is not known in advance, sign the EncryptedData
+elements instead: a signature covers the Algorithm attribute, so a relabelled element
+no longer verifies. On the DOM code
+WSHandlerConstants.REQUIRE_SIGNED_ENCRYPTED_DATA_ELEMENTS
+("requireSignedEncryptedDataElements") requires every EncryptedData to sit in a signed
+subtree. The streaming code does not implement that tag.
+
 === Use Subject DN regular expressions with chain trust
 
 WSS4J 1.6.7 introduced the ability to specify regular expressions on the Subject DN of a