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 240c68a6c Improving kerberos docs
240c68a6c is described below
commit 240c68a6c374126245707785a7bbbb1fc7372fa2
Author: Colm O hEigeartaigh <[email protected]>
AuthorDate: Mon Sep 21 09:35:19 2026 +0100
Improving kerberos docs
---
THREAT-MODEL.md | 13 +++++++++++++
src/site/asciidoc/config.adoc | 8 ++++++++
2 files changed, 21 insertions(+)
diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md
index 0ea98b153..82d8ba8d6 100644
--- a/THREAT-MODEL.md
+++ b/THREAT-MODEL.md
@@ -811,6 +811,19 @@ The embedding SOAP stack / application **must**:
documented example) in production deployments.**
- **Disabling BSP compliance via `IS_BSP_COMPLIANT=false` to "make
interop work" with a non-conformant stack.**
+- **Choosing an AlgorithmSuite whose encryption key length disagrees
+ with the Kerberos encryption type the KDC issues session keys for.**
+ A Kerberos session key is whatever length the ticket's etype makes it
+ — 16 bytes for aes128-cts and rc4-hmac, 32 for aes256-cts, 24 for
+ des3-cbc-sha1 — and it is used directly as the symmetric key, so it is
+ the KDC, not the policy, that fixes the length. `KeyUtils`
+ `prepareSecretKey` rejects a length that does not match the declared
+ algorithm rather than truncating it, which is what stops the same
+ session key being used as both an AES-128 and an AES-256 key. The
+ deployment consequence is that the suite has to be chosen to match the
+ etype; signing is unaffected, as the HMAC algorithms take a key of any
+ length *(documented: `src/site/asciidoc/config.adoc`
+ ENCRYPTION_WITH_KERBEROS_TOKEN)*.
- **Treating `PASSWORD_DIGEST` as offline-attack-resistant.** Combined
with a weak password, the digest can be brute-forced offline
*(documented: `src/site/asciidoc/config.adoc` and OASIS UT 1.1)*.
diff --git a/src/site/asciidoc/config.adoc b/src/site/asciidoc/config.adoc
index a35af6f39..e23ba3560 100644
--- a/src/site/asciidoc/config.adoc
+++ b/src/site/asciidoc/config.adoc
@@ -129,6 +129,14 @@ Note that for releases from 2.0.0 → 2.2.x, this
configuration tag was called E
* *WSS4J 2.0.0* SIGNATURE_WITH_KERBEROS_TOKEN (SignatureWithKerberosToken) -
Perform a Signature action with a kerberos token. Only for StAX code.
* *WSS4J 2.3.0* ENCRYPTION_WITH_KERBEROS_TOKEN (EncryptionWithKerberosToken)
- Perform a Encryption action with a kerberos token. Only for StAX code.
Note that for releases from 2.0.0 -> 2.2.x, this configuration tag was called
ENCRYPT_WITH_KERBEROS_TOKEN (EncryptWithKerberosToken).
+When a Kerberos token supplies the symmetric key, the encryption algorithm must
+require a key of exactly the length of the session key that the KDC issued,
which is
+fixed by the encryption type of the ticket: 16 bytes for aes128-cts and for
rc4-hmac,
+32 bytes for aes256-cts, 24 bytes for des3-cbc-sha1. A key of any other length
is
+rejected rather than silently truncated to fit, so, for example, an
AlgorithmSuite of
+Basic256 cannot be used against a KDC that issues aes128 session keys. This
applies to
+both stacks, and on both the sending and the receiving side. Signing with a
Kerberos
+token is unaffected, because the HMAC algorithms accept a key of any length.
* *WSS4J 2.0.0* KERBEROS_TOKEN (KerberosToken) - Add a kerberos token. Only
for StAX code.
* *WSS4J 2.0.0* CUSTOM_TOKEN (CustomToken) - Add a "Custom" token from a
CallbackHandler
* *WSS4J 1.6.x only* SIGN_WITH_UT_KEY (UsernameTokenSignature) - Perform a
.NET specific signature using a Username Token action.
