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 <[email protected]>
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
