Apache Santuario (XML Security for Java) — Threat Model

§1 Header

Project: Apache Santuario — XML Security for Java (apache/santuario-xml-security-java), artifact org.apache.santuario:xmlsec.
Written against: main @ HEAD (2026-06), 4.0.x/3.0.x line.
Author: ASF Security team, drafted via the threat-model-producer rubric (Michael Scovetta rubric) at the Apache Santuario PMC's request (path 3).
Status: DRAFT — under maintainer review (2026-06-10). Not yet ratified.
Version binding: versioned with the project; a report against version N is triaged against the model as it stood at N.
Reporting cross-reference: §8-violating findings go to the disclosure channel in SECURITY.md; §3/§9 findings are closed citing this document.
Provenance legend: (documented) = project source / SECURITY.md / advisories (cited); (maintainer) = a Santuario maintainer in this review; (inferred) = reasoned from code/domain, not yet confirmed — each has a §14 open question.
Draft confidence: ~26 documented / 0 maintainer / 22 inferred.

What it is. A Java library implementing the W3C XML Signature and XML Encryption standards (plus the JSR-105 javax.xml.crypto API). It is consumed in-process by applications and frameworks (notably WS-Security stacks — WSS4J, CXF, OpenSAML/Shibboleth, Apache Santuario users in SAML/SOAP) to sign, verify, encrypt, and decrypt XML. It ships two implementations: a mature DOM-based stack and a newer StAX (streaming) stack. The security-critical operations are verification and decryption of attacker-controlled XML.

§2 Scope and intended use

Intended use: an application calls the library to verify a signature on, or decrypt, an XML document that originates outside the application's trust boundary (a SOAP message, a SAML assertion, a signed document). Equally, to produce signatures/ciphertext over its own (trusted) data.

Caller trust level: the calling application is trusted; the XML input to verification/decryption is untrusted and adversary-controlled. This is the defining trust split of the library. (inferred — Q1.)

Component families.

Family	Entry point	Processes untrusted XML?	In model?
DOM XML Signature (verify)	`XMLSignature.checkSignatureValue`, `SignedInfo`	yes	Yes
DOM XML Encryption (decrypt)	`XMLCipher.doFinal` / `decryptData`	yes	Yes
StAX (streaming) Sig/Enc	`InboundXMLSec`, `*InputProcessor`	yes	Yes
Transforms / canonicalization	`Transform`, `Transforms`, `Canonicalizer`	yes (transform chain runs on attacker XML)	Yes
Key resolution	`KeyResolver`, `*KeyResolverSpi`	yes (`KeyInfo` is attacker-supplied)	Yes
Signing / encryption (produce)	`XMLSignature.sign`, `XMLCipher.encryptData`	no — over trusted data	partial — see §3
JSR-105 API surface	`javax.xml.crypto.dsig.*`	as above	Yes (delegates to DOM)

§3 Out of scope (explicit non-goals)

Establishing trust in the verifying key. The library tells the caller “this signature is cryptographically valid under key K” and can resolve K from the message‘s KeyInfo. It does not decide whether K is trusted. Validating the certificate chain / matching K against an allow-list is the **caller’s** responsibility (§10). A report that boils down to “I trusted a self-signed cert in KeyInfo” is OUT-OF-MODEL: trusted-input / BY-DESIGN. (documented — KeyResolver returns keys; trust decisions are not in this layer.)
What the signature covers. The library verifies that referenced content has a valid digest; it does not decide whether the right content was signed. Checking that the signature covers the security-relevant elements (the XML-Signature-Wrapping defence) is the caller's job — see §9/§11. (documented — this is the canonical XSW caveat.)
Retired C++ project (santuario-xml-security-cpp) and the two archived repos — out of scope. (documented — SECURITY.md “retired”.)
The application's XML toolchain after extraction. Once the caller pulls decrypted/verified content out and re-parses or deserializes it, that is the caller's pipeline.

§4 Trust boundaries and data flow

The boundary is the XML document submitted for verification/decryption. Everything in that document — elements, Reference URIs, Transform chains, KeyInfo, EncryptedKey, algorithm identifiers, namespace prefixes — is attacker-controlled and must be treated as hostile.

untrusted XML (SOAP/SAML/doc)
   │  attacker controls structure, transforms, KeyInfo, algorithms
   ▼
parse (DocumentBuilderFactory — DTD handling = §8/§5a)
   ▼
Signature verify: resolve References -> run Transform chain -> canonicalize -> digest -> verify sig
   │                         ▲ XSLT/XPath transforms run here (§9 false friend)
Decrypt: resolve EncryptedKey -> KeyResolver -> unwrap -> decrypt -> (optional) re-parse
   ▼
result handed to caller  ──►  caller must check WHO signed + WHAT was signed (§10)

Reachability precondition (the triager's test): a finding is in-model only if reachable from the untrusted XML during verify/decrypt with secure validation enabled (§5a). A finding that requires secure validation to be off, or requires the caller to skip trust/coverage checks, is out of model (§5a / §3).

§5 Assumptions about the environment

Runtime: a conformant JRE with a JAXP XML parser and a JCE provider for the crypto primitives. The library relies on the platform parser's DTD/entity controls (§5a). (inferred — Q2.)
JCE provider: primitive correctness (RSA/AES/SHA, GCM nonce handling) is the provider's; the library composes them. (inferred — Q3.)
Concurrency: XMLSignature/XMLCipher instances are not assumed thread-safe; per-operation instances are the expected usage. (inferred — Q4.)
No ambient side effects beyond what a Transform/KeyResolver is configured to do — but note the default-resolver and transform behaviour can dereference URIs (§9). (inferred — Q5, high priority.)

§5a Build-time and configuration variants — the central knob

Secure validation mode is the load-bearing configuration. Santuario exposes a “secure validation” flag (e.g. XMLSignature / XMLCipher.setSecureValidation(true), the org.apache.xml.security.secureValidation property, and on by default in some JSR-105 paths). With secure validation on, the library:

rejects DTDs / disables external entity and RetrievalMethod/KeyInfo remote dereferencing,
forbids dangerous transforms (notably XSLT),
enforces minimum key sizes and rejects known-weak digest/MAC/signature algorithms (e.g. MD5, SHA-1-in-signatures, RSA < 1024-ish, HMAC truncation),
caps the number of Reference/Transform elements to bound expansion. (documented — these are the historical CVE mitigations folded into secure validation; exact set is Q-confirmed in §14.)

The insecure-default problem (must be resolved by the maintainer). Whether secure validation is on by default depends on entry point and version (the JSR-105 javax.xml.crypto path vs the native org.apache.xml.security path have differed). This reshapes §8/§9/§11a/§13 simultaneously:

If secure validation is the supported posture for untrusted input and a caller must opt in, then a report that only manifests with it off is OUT-OF-MODEL: non-default-build and §10 carries “enable secure validation.”
If it is on by default everywhere, the §8 properties hold out of the box. This is wave-1 Q6 and the most important question in the model.

§6 Assumptions about inputs

Per-parameter trust for the security-critical entry points:

Entry point	Parameter	Attacker-controllable?	Caller must enforce
signature verify	the XML document / `SignedInfo`	yes	enable secure validation; check coverage (§10)
signature verify	`KeyInfo` (embedded key/cert)	yes	establish trust in the resolved key — do not trust `KeyInfo` blindly
signature verify	`Reference` URI / `Transform` chain	yes	rely on secure validation to bound transforms/derefs
decrypt	`EncryptedData` / `EncryptedKey`	yes	secure validation; treat decrypted bytes as untrusted
decrypt	algorithm identifiers	yes	secure validation enforces allow-list
sign / encrypt	content to protect, signing key	no — caller-supplied trusted	protect the private key (caller)

Plus: the parser-level inputs (DOCTYPE, entities, external refs) are attacker-controlled and governed by §5a/§8.

§7 Adversary model

In scope: the party that supplies the XML being verified or decrypted — a network peer in a WS-Security/SAML exchange, the sender of a signed document. Capabilities: full control of the XML structure, transforms, KeyInfo, algorithms; ability to craft signature-wrapping, transform, key- confusion, decryption-oracle, and resource-exhaustion payloads. (inferred — Q1.)
Out of scope: an attacker who controls the calling process or the trust/keystore configuration (they have already won); side-channel/co-tenant adversaries against the JCE provider (§5); an attacker who can make the caller disable secure validation or skip trust checks.

§8 Security properties the project provides (with secure validation on)

DTD / XXE rejection. Secure validation rejects DOCTYPE and external entity resolution during parse/verify. Violation: external entity resolved / SSRF / file read. Severity: critical. (documented — secure validation; Q6 for default.)
Dangerous-transform rejection. XSLT (and other code-executing/remote- deref transforms) are disallowed under secure validation. Violation: XSLT/script or remote fetch via a Transform. Severity: critical. (documented.)
Weak-algorithm rejection. Known-weak digest/MAC/signature algorithms and undersized keys are rejected under secure validation. Violation: a signature accepted under MD5/short-HMAC/short-RSA. Severity: critical. (documented — folds prior CVEs.)
Expansion bounding. The number of Reference/Transform elements is capped to bound CPU/memory under secure validation. Violation: super- linear blowup from many references/transforms. Severity: security (DoS). (inferred — Q7: confirm the exact caps.)
Cryptographic correctness of the verify/decrypt operation given a well-formed signature and a provided key — i.e. an invalid signature does not verify true. Violation: signature forgery / bypass. Severity: critical. (documented — core function.)

§9 Security properties the project does not provide

It does not tell you the signature covers the right thing. A valid signature over some element is not a signature over the element your application cares about. XML Signature Wrapping (XSW) lives entirely in this gap and is the #1 real-world Santuario-adjacent vulnerability class — it is the caller's responsibility to verify that the verified Reference resolves to the security-relevant content. (documented — canonical caveat.)
- False friend: “the signature verified” is not “the document is authentic and unmodified where it matters.”
It does not establish key trust. Resolving a key from KeyInfo is a convenience, not a trust decision; certificate-path validation / key pinning is the caller's (§3/§10).
No protection if secure validation is disabled. With it off, XXE, XSLT transforms, weak algorithms, and unbounded expansion are all reachable — by design, for backward-compatible processing of trusted XML. (documented — §5a.)
No decryption-oracle hardening at the protocol layer. The library performs the cryptographic decrypt; padding-oracle / replay / “decrypt-then- verify ordering” defences are protocol-level (WS-Security/SAML) concerns the caller's stack must handle. (inferred — Q8.)
Well-known attack classes the integrator owns: XSW (coverage checking), XXE/billion-laughs when secure validation is off, key-confusion via unvalidated KeyInfo, and decryption oracles at the protocol layer.

§10 Downstream responsibilities

Enable secure validation for any XML from outside your trust boundary.
Check what was signed — verify the signature's References resolve to the exact content you are about to trust (defeat XSW); prefer ID-based references you control and re-check post-verify.
Establish key trust independently — validate the cert chain / match the key against an allow-list; never trust KeyInfo-embedded keys implicitly.
Treat decrypted/verified bytes as untrusted until your own validation passes; apply resource limits at the boundary.
Protect signing/decryption private keys (caller-side key management).

§11 Known misuse patterns

Trusting a valid signature without checking coverage → XSW.
Trusting KeyInfo keys/certs without path validation → accept attacker's key.
Processing untrusted XML with secure validation off → XXE / XSLT / weak- algo / expansion.
Using verification as authorization without binding the signer identity to an authorization decision.

§11a Known non-findings (recurring false positives)

DocumentBuilderFactory / transform / weak-algo reachable with secure validation OFF — non-finding: off is the trusted-input posture (§5a); reachability precondition (secure validation on) not met. OUT-OF-MODEL: non-default-build (pending Q6).
“KeyInfo lets an attacker supply a key” — non-finding: key trust is the caller's (§3/§9). BY-DESIGN.
“A valid signature didn't protect element X” where X wasn‘t referenced — non-finding: coverage checking is the caller’s (§9). BY-DESIGN / VALID-HARDENING only if the API makes the safe check unreasonably hard.
Findings in the retired C++ project / archived repos — OUT-OF-MODEL: unsupported-component (§3).
JCE-provider primitive issues (RNG, GCM) — out of layer (§5).

§12 Conditions that would change this model

A change to secure-validation defaults or the set of checks it performs (§5a).
A new transform/canonicalization algorithm, or a new key-resolver that dereferences remote material.
The StAX stack diverging from the DOM stack on any §8 property.
A report that cannot be routed to a §13 disposition → revise §8/§9.

§13 Triage dispositions

Disposition	Meaning	Licensed by
`VALID`	A §8 property breaks with secure validation on, via untrusted XML.	§8, §6, §7
`VALID-HARDENING`	No §8 break, but the API makes a §11 misuse (esp. XSW coverage) too easy.	§11
`OUT-OF-MODEL: trusted-input`	Requires attacker control of key-trust / config the model trusts.	§6
`OUT-OF-MODEL: adversary-not-in-scope`	Requires an excluded capability.	§7
`OUT-OF-MODEL: non-default-build`	Only manifests with secure validation off.	§5a
`OUT-OF-MODEL: unsupported-component`	Retired C++ / archived repos.	§3
`BY-DESIGN: property-disclaimed`	Key trust, coverage checking, protocol oracles.	§9
`KNOWN-NON-FINDING`	Matches §11a.	§11a
`MODEL-GAP`	Unroutable.	triggers §12

§14 Open questions for the maintainers

Wave 1 — the load-bearing ones.

Q1. Confirm the trust split: calling application trusted; the XML submitted to verify/decrypt is fully attacker-controlled; the in-scope adversary is the XML supplier. (§2/§4/§7.)
Q6. Secure validation defaults — for each entry point (native org.apache.xml.security vs JSR-105 javax.xml.crypto, DOM vs StAX, and by version), is secure validation on by default, or must the caller opt in? This decides whether secure-validation-off findings are VALID or OUT-OF-MODEL: non-default-build. (§5a/§8/§9/§11a/§13.)
Q-XSW. Confirm the project‘s official position that **signature-coverage checking (XSW defence) is the caller’s responsibility**, and point at the canonical guidance you want cited when closing XSW reports. (§9/§10.)

Wave 2 — the secure-validation checklist (confirm/correct the §8 list).

Q7. Exact set enforced by secure validation: which algorithms/key sizes are rejected, which transforms are forbidden, and the caps on Reference/Transform counts? (§8.)
Q3/Q5. Which transforms or key-resolvers can dereference remote/local URIs, and are any enabled even under secure validation? (§5/§8/§9.)
Q8. Do you make any protocol-level guarantee (decryption-oracle, replay, decrypt/verify ordering), or is that explicitly the WS-Security/SAML caller's layer? (§9.)

Wave 3 — surface & coexistence.

Q2/Q4. Parser/JCE assumptions and thread-safety expectations. (§5.)
Q9. This adds THREAT_MODEL.md + AGENTS.md alongside your existing SECURITY.md (which we kept). Confirm the disclosure pointer and whether the model should become canonical with SECURITY.md linking to it. (§1/§15.)

§15 Appendix — existing-policy back-map

The repo's SECURITY.md is a disclosure-process + supported-versions policy (no embedded threat model); it points at the ASF security process and the published advisories at santuario.apache.org/secadv.html. This THREAT_MODEL.md is additive — SECURITY.md is preserved and gains a pointer to the model. The published advisories are a high-value source for refining §8/§11a in a later pass (each historical CVE maps to a secure-validation mitigation).